🛳 Deployment automation agent
Subilo is a tool to setup continuous deployments for applications running on machines with no external integrations, like IoT devices and VPSs.
The Subilo agent is a small server that lives on your application's machine and
listens for secure HTTP webhooks. These webhooks have information about what
application to deploy matching the Subilo configuration file (.subilorc).
The file also defines what steps should be taken to successfully deploy an
application, for example: git pull or pull the latest Docker image, restart
the application and send a notification.
Configuration (.subilorc):
toml
[[projects]]
name = "foo-app"
path = "~/apps/foo-app"
commands = [
"git pull",
"./restart-serever.sh",
"echo 'Pulled changes and restarted server successfully'",
]
Webhook:
This webhook is usually sent from a CI run after the tests passed.
bash
curl -X POST 'https://subilo.yourdomain.com/webhook' \
-H 'Authorization: Bearer ********' \
-H 'Content-Type: application/json' \
-d '{ "name": "foo-app" }'
Status and logs of these deployments can then be seen in the Dashboard using the URL and the authentication token provided by the Subilo agent.
bash
curl -s -L https://raw.githubusercontent.com/huemul/subilo/master/install.sh | bash
This command runs the
install script.
The script downloads the latest Subilo release and attempts to add the Subilo bin
path to the $PATH in the correct profile file (~/.profile, ~/.bashrc,
~/.bash_profile, ~/.zshrc or ~/.config/fish/config.fish)
cargo install subilo
Download the latest released binary and add executable permissions:
wget -O subilo "https://github.com/huemul/subilo/releases/download/v0.1.2/subilo-x86-64-linux"
chmod +x subilo
Now that Subilo is available, the help subcommand can be run to display the
CLI information:
``` subilo --help subilo 0.0.1 Tiny deployment agent
USAGE:
subilo [FLAGS] [OPTIONS]
FLAGS: -h, --help Prints help information -V, --version Prints version information -v, --verbose Makes Subilo verbose. Useful for debugging and seeing what's going on "under the hood"
OPTIONS:
-s, --secret
SUBCOMMANDS: help Prints this message or the help of the given subcommand(s) serve Start subilo agent token Create a token based on the secret to authorize agent connections ```
Create a .subilorc file with the required configuration. An example can be
found here.
To start the agent the serve command should be used specifying the
authentication secret, the port (optional), config file and logs directory
(optional).
Example:
bash
subilo --secret super-secret serve --port 8089 --config /path/to/.subilorc
NOTE: at the moment, the API to display the deployment jobs status and logs is based on these logs files.
To get access to the agent endpoints, create an authentication token using the
token command in the CLI.
This token is used to access the POST /webhook endpoint and deploy
an application using the predefined commands in .subilorc.
Example:
bash
subilo --secret "super-secret" token --permissions "job:write"
By default, the token only has read parmissions. In other words, only access the logs and information endpoints. These endpoints can be used to see the status and logs of the deployment jobs. They are what powers the subilo.io website.
Example:
bash
subilo --secret "super-secret" token
We recommend running Subilo with systemd to easily manage it. But that's completely optional, you may run it however suits you.
Create a systemd service file (/etc/systemd/system/subilo.service) with the
following attributes:
``` [Unit] Description=Subilo
[Service] ExecStart=/path/to/subilo -s super-secret-secret serve -l /path/to/subilo-logs -p 8080 -c /path/to/.subilorc
[Install] WantedBy=multi-user.target ```
Then enable and start Subilo service:
```bash
systemctl enable /etc/systemd/system/subilo.service systemctl start subilo ```
To read logs and check status from systemctl, the following commands can be used:
bash
systemctl status subilo
journalctl -u subilo -b
Once Subilo is running and exposed to the internet, deployment jobs can be
triggered by a POST request to the /webhook endpoint wiht the application's
name on the payload.
bash
curl -X POST 'https://subilo.yourdomain.com/webhook' \
-H 'Authorization: Bearer ********' \
-H 'Content-Type: application/json' \
-d '{ "name": "foo-app" }'
The name is matched against the .subilorc configuration file and the
specified commands are run to deploy the app.
Usually, this webhook is trigger from a CI run, so after the application's tests
passed, it can be safely deployed. Store the token as a secret in the CI
configuration and add a curl command to POST to the /webhook endpoint to
trigger a deploy.
```bash cargo run
cargo watch -x run
cargo run -- --port 9090 --logs-dir ./logs ```
```bash cargo test
cargo watch -x test ```