|
| 1 | +# Templates guide |
| 2 | + |
| 3 | +Exoframe allows doing complex deployments using third party recipes. |
| 4 | +This guide aims to explain basics you need to know to create your own recipes. |
| 5 | +If you are looking for recipe usage - please see [Basics](Basics.md) part of the docs. |
| 6 | + |
| 7 | +## Basics |
| 8 | + |
| 9 | +Exoframe uses [yarn](https://yarnpkg.com/) to install third-party recipes. |
| 10 | +The recipes then are executed on Exoframe server using Node.js `require()` method. |
| 11 | +So, make sure that your template's `package.json` has correct `main` attribute. |
| 12 | + |
| 13 | +Your template main script needs to export the following variables and methods: |
| 14 | + |
| 15 | +```js |
| 16 | +// function to get list of questions that should be presented |
| 17 | +// to user. uses Inquirer.js question format |
| 18 | +exports.getQuestions = async () => []; |
| 19 | + |
| 20 | +// function to execute current recipe with user answers |
| 21 | +exports.runSetup = async props => {}; |
| 22 | +``` |
| 23 | + |
| 24 | +## Recipe props |
| 25 | + |
| 26 | +During the execution `runSetup` will get the properties object from Exoframe server. |
| 27 | +This object contains all data and methods required to build and execute new docker containers. |
| 28 | +Here's a snippet from the Exoframe server code that shows the props object being assembled: |
| 29 | + |
| 30 | +```js |
| 31 | +// generate recipe props |
| 32 | +const recipeProps = { |
| 33 | + // user answers |
| 34 | + answers, |
| 35 | + // server config |
| 36 | + serverConfig, |
| 37 | + // current user username |
| 38 | + username, |
| 39 | + // temp dir that contains the project |
| 40 | + tempDockerDir, |
| 41 | + // docker-related things |
| 42 | + docker: { |
| 43 | + // docker daemon, instance of dockerode |
| 44 | + daemon: docker, |
| 45 | + // exoframe build function |
| 46 | + // has following signature: async ({username, resultStream}) => {} |
| 47 | + // executes `docker build` in project temp dir |
| 48 | + // returns following object: {log, image} |
| 49 | + build, |
| 50 | + // exoframe start function |
| 51 | + // has the following signature: async ({image, username, resultStream}) => {} |
| 52 | + // executes `docker start` with given image while setting all required labels, env vars, etc |
| 53 | + // returns inspect info from started container |
| 54 | + start, |
| 55 | + // exoframe startFromParams function |
| 56 | + // has the following signature: |
| 57 | + // async ({ |
| 58 | + // image, |
| 59 | + // deploymentName, |
| 60 | + // projectName, |
| 61 | + // username, |
| 62 | + // backendName, |
| 63 | + // frontend, |
| 64 | + // hostname, |
| 65 | + // restartPolicy, |
| 66 | + // Env = [], |
| 67 | + // additionalLabels = {}, |
| 68 | + // Mounts = [], |
| 69 | + // }) => {} |
| 70 | + // executes `docker start` with given image while setting all required labels, env vars, etc |
| 71 | + // returns inspect info from started container |
| 72 | + startFromParams, |
| 73 | + // exoframe image pulling function |
| 74 | + // has the following signature: async (tag) => {} |
| 75 | + // returns pull log on success |
| 76 | + pullImage, |
| 77 | + // exoframe network get function |
| 78 | + // returns currently used exoframe network |
| 79 | + getNetwork, |
| 80 | + }, |
| 81 | + // exoframe utilities & logger |
| 82 | + // see code here: https://github.com/exoframejs/exoframe-server/blob/master/src/util/index.js |
| 83 | + util: Object.assign({}, util, { |
| 84 | + logger, |
| 85 | + }), |
| 86 | +}; |
| 87 | +``` |
| 88 | + |
| 89 | +## Executing the recipe |
| 90 | + |
| 91 | +Once user has answered all your questions, you will need to execute the recipe. |
| 92 | +It is up to you to build _and_ start all required docker images. |
| 93 | +Here's an example for the Wordpress recipe: |
| 94 | + |
| 95 | +```js |
| 96 | +// image names |
| 97 | +const mysqlImage = 'mariadb:latest'; |
| 98 | +const wordpressImage = 'wordpress:latest'; |
| 99 | +const phpmyadminImage = 'phpmyadmin/phpmyadmin:latest'; |
| 100 | + |
| 101 | +// ask user to provide params for deployment |
| 102 | +exports.getQuestions = () => [ |
| 103 | + { |
| 104 | + type: 'input', |
| 105 | + name: 'projectName', |
| 106 | + message: 'Wordpress project name:', |
| 107 | + }, |
| 108 | + { |
| 109 | + type: 'input', |
| 110 | + name: 'mysqlPassword', |
| 111 | + message: 'MySQL root password:', |
| 112 | + }, |
| 113 | + { |
| 114 | + type: 'input', |
| 115 | + name: 'wordpressDomain', |
| 116 | + message: 'Domain for Wordpress:', |
| 117 | + }, |
| 118 | + { |
| 119 | + type: 'confirm', |
| 120 | + name: 'phpmyadminStart', |
| 121 | + message: 'Also start PHPMyAdmin?', |
| 122 | + }, |
| 123 | + { |
| 124 | + type: 'input', |
| 125 | + name: 'phpmyadminDomain', |
| 126 | + message: 'Domain for PHPMyAdmin:', |
| 127 | + }, |
| 128 | +]; |
| 129 | + |
| 130 | +// start mysql |
| 131 | +const startMysql = async ({util, answers, username, docker}) => { |
| 132 | + // generate new deployment name (optional, in this case we do this to have the same hostname) |
| 133 | + const deploymentName = util.nameFromImage(mysqlImage); |
| 134 | + // start new docker container / service |
| 135 | + return docker.startFromParams({ |
| 136 | + // provide image name |
| 137 | + image: mysqlImage, |
| 138 | + // use project name from user answers |
| 139 | + projectName: answers.projectName, |
| 140 | + // pass in username |
| 141 | + username, |
| 142 | + // apply deployment name |
| 143 | + deploymentName, |
| 144 | + // also use deployment name for hostname |
| 145 | + hostname: deploymentName, |
| 146 | + // set restart policy |
| 147 | + restartPolicy: 'always', |
| 148 | + // create volume to persist data |
| 149 | + Mounts: [ |
| 150 | + { |
| 151 | + Type: 'volume', |
| 152 | + Source: `${answers.projectName}-mysqldata`, |
| 153 | + Target: '/var/lib/mysql', |
| 154 | + }, |
| 155 | + ], |
| 156 | + // pass in env vars config |
| 157 | + Env: [`MYSQL_ROOT_PASSWORD=${answers.mysqlPassword}`], |
| 158 | + }); |
| 159 | +}; |
| 160 | + |
| 161 | +// start wordpress |
| 162 | +const startWordpress = async ({util, answers, serverConfig, username, docker, mysql}) => { |
| 163 | + // generate new deployment name (optional) |
| 164 | + const deploymentName = util.nameFromImage(wordpressImage); |
| 165 | + |
| 166 | + // get mysql hostname from inspect object |
| 167 | + const mysqlHost = serverConfig.swarm |
| 168 | + ? mysql.Spec.Networks[0].Aliases |
| 169 | + : mysql.NetworkSettings.Networks.exoframe.Aliases[0]; |
| 170 | + |
| 171 | + // start new container / service |
| 172 | + return docker.startFromParams({ |
| 173 | + // set image name |
| 174 | + image: wordpressImage, |
| 175 | + // set project name |
| 176 | + projectName: answers.projectName, |
| 177 | + // set username |
| 178 | + username, |
| 179 | + // set deployment name (can be omitted) |
| 180 | + deploymentName, |
| 181 | + // set frontend string for Traefik since we want |
| 182 | + // it to be accessible from web |
| 183 | + frontend: `Host:${answers.wordpressDomain}`, |
| 184 | + // set restart policy |
| 185 | + restartPolicy: 'always', |
| 186 | + // set env vars config |
| 187 | + Env: [`WORDPRESS_DB_HOST=${mysqlHost}`, `WORDPRESS_DB_PASSWORD=${answers.mysqlPassword}`], |
| 188 | + }); |
| 189 | +}; |
| 190 | + |
| 191 | +// start phpmyadmin |
| 192 | +const startPhpmyadmin = async ({util, answers, serverConfig, username, docker, mysql}) => { |
| 193 | + // generate new deployment name (optional) |
| 194 | + const deploymentName = util.nameFromImage(phpmyadminImage); |
| 195 | + |
| 196 | + // get mysql hostname from inspect object |
| 197 | + const mysqlHost = serverConfig.swarm |
| 198 | + ? mysql.Spec.Networks[0].Aliases |
| 199 | + : mysql.NetworkSettings.Networks.exoframe.Aliases[0]; |
| 200 | + |
| 201 | + // start container / service |
| 202 | + return docker.startFromParams({ |
| 203 | + // set image name |
| 204 | + image: phpmyadminImage, |
| 205 | + // set project name from user answers |
| 206 | + projectName: answers.projectName, |
| 207 | + // set username |
| 208 | + username, |
| 209 | + // set deployment name (can be omitted) |
| 210 | + deploymentName, |
| 211 | + // set frontend rule for Traefik since we want |
| 212 | + // it to be accessible from web |
| 213 | + frontend: `Host:${answers.phpmyadminDomain}`, |
| 214 | + // set restart policy |
| 215 | + restartPolicy: 'always', |
| 216 | + // set env vars config |
| 217 | + Env: [`PMA_HOST=${mysqlHost}`, `MYSQL_ROOT_PASSWORD=${answers.mysqlPassword}`], |
| 218 | + }); |
| 219 | +}; |
| 220 | + |
| 221 | +exports.runSetup = async ({answers, serverConfig, username, docker, util}) => { |
| 222 | + // init log |
| 223 | + const log = []; |
| 224 | + |
| 225 | + try { |
| 226 | + util.logger.debug('starting work..'); |
| 227 | + // start mysql container |
| 228 | + util.logger.debug('starting mysql..'); |
| 229 | + const mysql = await startMysql({util, answers, username, docker}); |
| 230 | + log.push({message: 'Mysql container started', data: mysql, level: 'info'}); |
| 231 | + util.logger.debug('created mysql container..'); |
| 232 | + |
| 233 | + // start wordpress container |
| 234 | + util.logger.debug('starting wordpress..'); |
| 235 | + const wordpress = await startWordpress({util, answers, serverConfig, username, docker, mysql}); |
| 236 | + log.push({message: 'Wordpress container started', data: wordpress, level: 'info'}); |
| 237 | + util.logger.debug('created wordpress container..'); |
| 238 | + |
| 239 | + // start phpmyadmin if needed |
| 240 | + if (answers.phpmyadminStart) { |
| 241 | + util.logger.debug('starting phpmyadmin..'); |
| 242 | + const phpmyadmin = await startPhpmyadmin({util, answers, serverConfig, username, docker, mysql}); |
| 243 | + log.push({message: 'PHPMyAdmin container started', data: phpmyadmin, level: 'info'}); |
| 244 | + util.logger.debug('created phpmyadmin container..'); |
| 245 | + } |
| 246 | + } catch (e) { |
| 247 | + util.logger.error('error:', e); |
| 248 | + log.push({message: e.toString(), data: e, level: 'error'}); |
| 249 | + } |
| 250 | + |
| 251 | + // return log to user |
| 252 | + return log; |
| 253 | +}; |
| 254 | +``` |
| 255 | + |
| 256 | +## Examples |
| 257 | + |
| 258 | +* [Wordpress recipe](https://github.com/exoframejs/exoframe-recipe-wordpress) (incl. Wordpress, MariaDB and PHPMyAdmin) |
0 commit comments