Kamal deployment

This document guides you through setting up your virtual private server for the first time.

Pre-requisities

Buy a domain name for the SSL/TLS setup.
Set up emails on the domain name for the Let’s Encrypt email contact or choose a different address.
Set up a Docker registry, put down name and access token.

Create an SSH key or prepare an existing one.

 $ ssh-keygen -t ed25519 -C "admin@domainplaceholder.com"

Buy a virtual private server, choose Ubuntu 22 and set it up with the SSH key from previous step. Do not use passwords.
Update DNS A and CNAME entries so that the domain leads to the public IP of the VPS.
Prepare RAILS_MASTER_KEY for Rails Encrypted Credentials if you haven’t already.
```
 $ EDITOR=code bin/rails credentials:edit --environment=production
```

Configuration

Provide your domain name, IP address, and a Docker repository:

$ bin/replace domainplaceholder.com ...
$ bin/replace 170.64.149.226 ...
$ bin/replace repousername ...

Substitute the placeholder ... values for your own. Using the rename script ensures your documentation updates at the same time.

You email will default to admin@.... If you need a different one, find&replace and change before your deploy.

Your config/deploy.yml should be complete now. Recheck the file for sanity check.

Environment file

Now you’ll need to put together your secret .env file.

Generate a dummy one:

$ bin/generate_dotenv

PostgreSQL and Redis passwords were generated uniquely for you, but make sure all ENVs are filled in.

Provisioning

Once your configuration is in place, you can provision the server and set up Kamal:

$ ssh-add ~/.ssh/path_to_private_key
$ bin/provision
$ kamal setup

Here’s what this does:

ssh-add will add your key to your SSH agent.

This ensure your key is available and you don’t need to retype your password every time ssh is called.
bin/provision can provision your new server based on the Kamal configuration in config/deploy.yml.

It creates a storage location, Let’s encrypt directory, installs Docker, creates a private Docker network, creates an application user with sudo access and disables root for security.

Note: If there is an issue while provisioning, rerunning it should help.
kamal setup is a standard Kamal’s initial provisioning.

It builds the required images and runs any necessary tasks to prepare your server for deploying with kamal deploy.

Note: If there is an issue setting up the server, you’ll need to remove accessories before running kamal setup again.

Continues delivery

A GitHub action to deploy on every push to main or master branch is included the test_and_deploy.yml workflow within .github/workflows, but is not enabled by default. When ready, uncomment the deploy step and make sure to replace references to Docker registry username and service (as in config/deploy.yml).

The pre-made deploy step requires at least the following secrets to be provided on the GitHub side as Actions secrets and variables in project Settings:

KAMAL_REGISTRY_PASSWORD
SSH_PRIVATE_KEY
SSH_PASSPHRASE (if you used a password)