A simple yet powerful open-source CI system for individual developers, small teams and dev shops, specifically designed for JavaScript projects.
Avow is built for customization - creating continuous integration (and deployment) that fits your specific need. It's easy to hack on and makes it simple to create solutions that fit your needs.
1.) After cloning or downloading the contents of the Avow system to your server run
npm install to get all dependencies.
*Note: If you're planning to run in dev mode (i.e. node index.js) you need to
additionally run npm install grunt-cli -g.
2.) In the root of the directory create a file db_conf.json:
{
"adapter": "mongo",
"config": {
"host": "[MONGO_HOST]",
"database": "[DATABASE]",
"user": "[USER]",
"pass": "[PASSWORD]"
}
}Replacing the [VARIABLES] with your Mongo connection information.
3.) Create a user by running the following command:
node adduser.js [user@email.com] [password]
This will create a user based on the email address and password provided
4.) Start the service:
npm run prod
Avow has the ability to send email notifications to users when a build fails. To
enable this capability you must create a mail_conf.json file in the root:
{
"server": "[AVOW_SERVER]",
"host": "[SMTP_SERVER]",
"secureConnection": true,
"port": 465,
"auth": {
"user": "[SMTP_EMAIL]",
"pass": "[SMTP_PASSWORD]"
},
"maxConnections": 5,
"maxMessages": null
}Note: the AVOW_SERVER refers to the FQDN/IP for your Avow instance. This is used
to build return links from the outgoing email back to the failing build and should
be formatted like: http://yourserver.com:8181.
The default port (which can be changed in /config.js) is 8181, so when the
server is running you can access the web app via http://yourserver.com:8181.
You can then log in with the email address and password you created during installation.
Projects utilize an avow.json file in their root directory to inform the build
process of tasks to run. This file needs to be added to any project's repository
which will be added to the system.
A simple example of the avow.json file can be seen below:
{
"tasks": [
"npm install",
"grunt"
]
}The above would clone the repo and then run the tasks (in order) to complete the build.
Once the project has an avow.json configuration it can be added to the system:
From the main (Project List) screen you can click "New Project" to add a new project to the system. The "Project Config" screen will ask for 3 things:
- Name: This should consist of letters, numbers, and hyphens only and is used to reference the project
- Repo: The SSH repository clone URL
- Branch: If a valid SSH repo URL is supplied this will be a dropdown with the list of available branches
If the project is in a private repository you will need to add a deploy key. You
can simply use the server's .ssh/id_rsa.pub key for this (if it exists) or
generate one.
Once you have a deploy key simply add it to the repository in GitHub under the Settings >> Deploy Keys.
Alternatively, if you are running multiple repos (not just multiple branches) it may be easier to associate the server's pub-key with your Github account, or create a Github account for your server which has access to the repos you will be adding.
There are two ways to run builds through Avow:
In the main "Project List" screen you can manually run a build by clicking the icon in the "Build" column. This will start the build then direct you to the build page where the build can be monitored.
For the project to run whenever a commit is pushed to the repo + branch you can add a webhook in GitHub under the Project Settings >> Webhooks & Services with the following settings:
| Payload URL | Payload Version |
|---|---|
http://yourserver.com:8181/api/build/ |
application/vnd.github.v3+form |
Once these settings are in place the system will automatically process incoming
webhook POST's and execute a build.
The system is built on top of DozerJS which is a foundational framework for building full-stack NodeJS applications. If you would like to conribute to Avow obviously please follow conventions in place. The DozerJS Documentation provides additional details on expanding on the framework.
This software is released as-is, without warranty under the MIT-Style license.