Continuous deployment from Github.
npm install app-sync
Continuous deployment from Github. This module downloads and runs node apps from Github, keeping them in sync with the remote repository based on Semantic Versioning.
npm install --save app-sync
If you are not using the module within it's Docker container, then ensure that pm2 is installed within it's runtime environment:
npm install pm2 -g
app-sync module is designed to be run within its docker image which takes a few environment variables for connecting to Github, and then a pointer to a manifest.yml on Github that defines the apps to run within it.docker pull philcockfield/app-sync
Required:
GITHUB_TOKEN # Auth token: https://github.com/settings/tokens
GITHUB_USER_AGENT # https://developer.github.com/v3/#user-agent-required
MANIFEST #
Optional:
RABBIT_MQ # URL to the RabbitMQ/AMQP server.
#### Manifest
The MANIFEST points to a YAML file that declares global configuration settings along with the node applications to run. The YAML files takes for form of:
``yaml
targetFolder: "/opt/downloads" # Optional
api: # Optional
route:
tokens: [
apps:
repo: "
route: "*"
branch: "devel"
bar:
repo: "philcockfield/app-sync/example/app-1"
route:
- "*/bar"
- "domain.com"
- "jungle.com/foo"
- "jazz.com/*"
redirect:
- "/from => /to"
`
- The optional targetFolder specifies where apps are downloaded to.rabbitMQ
- If omitted a default path is used.
- Use this if you need to change it to a shared container volume.
This is more efficient when load-balancing across multiple containers as each container shares the single app download.
- The optional is the URL to a RabbitMQ server used to communicate between multiple instances of the module running within different containers.api
- The optional contains details about the REST-API.route
- If omitted the API is not exposed.
- : The base route that the API is exposed upon, for example: */apitokens
- : An optional array of passwords to lock the API with. Pass the token in the query string.branch
- If the of an app is omitted the default of master is used.redirect
- The optional array allows you to catch certain routes within the gateway and force a redirect (302) to a different route.
Note - when you make and push changes to the manifest.yml file the running containers will not automatically update. Use the /api/restart REST method to force a restart when you are ready.
#### Repo
The repo: field must be a fully qualified Github repository including the user-name. Optionally you can include a path to a location within the repository where the node-app exists. The repository or folder that is pointed to must have a package.json file within it:
philcockfield/my-repo
philcockfield/my-repo/sub-folder/site
#### Route
The route: field describes a URL pattern to match for the app. The pattern takes the form of . Use a wildcard (*) to match any incoming domain. For example:
www.domain.com
api.domain.com
domain.com/path
*/path
*
/ # Default if only '*' is specified
domain.com/* # Explicitly stating the wild-card path
is assigned an automatically generated port that is passed in via the --port startup parameter. Listen on this port for requests. You may wish to use minimist to extract the port value, for example:`js
var argv = require("minimist")(process.argv.slice(2));
app.listen(argv.port);
`
REST API
If you have set the api/route field set within the MANIFEST the following API is available: GET: /api/ # Status of the complete system and all running apps
GET: /api/apps # Lists all running apps.
GET: /api/apps/:appId # Status of the specified app.
GET: /api/apps/:appId/restart # Restarts the specified app.
GET: /api/apps/:appId/update # Updates the specified app.
GET: /api/restart # Restarts the gateway and all apps.
POST: /api/github # "Push" web-hook from Github repositories.
If you have
api/tokens within your manifest.yml ensure your API url's have an ?token= query-string.Github Webhook
Commits to application repositories are monitored via Github webhooks. If the commit is on the registered branch, and the package version number has increased the app is downloaded and restarted.#### Setup
1. Ensure the
api/route: field has been set in the manifest YAML so that the API is exposed.
2. Within the Github repository settings, select Webhooks & Services and click Add Webhook
3. Settings:
- Payload URL: for example: https://foo.com/api/github
- Content type: application/jsonTutum
To create an app-sync service on Tutum:1. Services ⇨ Create Service
2. Image selection ⇨ Public repositories ⇨
philcockfield/app-sync
4. Add environment variables (ref):
- NODE_ENV: production
- GITHUB_TOKEN
- GITHUB_USER_AGENT
- MANIFEST
5. Optional. Add volume ⇨ Container path: /opt/downloads (leave host path blank). This value should be declared within the manifest.
6. Create and deploy.
Run Example
npm install
npm run example
To simulate a multi-container deployment ensure the
rabbitMQ server URL is declared. You can do this by setting the RABBIT_MQ environment variable, or point to a manifest.yml where the rabbitMQ field is set.In one console run:
npm run example1
then in a second console, run:
npm run example2
To simulate a change, update and checkin the
package.json version of either of the example apps (app-1 or app-2`).
---