Getting Started with Kamal

Getting Started with Kamal #

First step is to install Kamal. You can install it with Ruby or Docker.

If you have a Ruby environment available, you can install Kamal globally with:

gem install kamal

Otherwise, you can run a dockerized version via an alias (add this to your ~/.bashrc or similar to simplify re-use).

On macOS, use:

alias kamal='docker run -it --rm -v "${PWD}:/workdir" -v "/run/host-services/ssh-auth.sock:/run/host-services/ssh-auth.sock" -e SSH_AUTH_SOCK="/run/host-services/ssh-auth.sock" -v /var/run/docker.sock:/var/run/docker.sock ghcr.io/basecamp/kamal:latest'

On Linux, use:

alias kamal='docker run -it --rm -v "${PWD}:/workdir" -v "${SSH_AUTH_SOCK}:/ssh-agent" -v /var/run/docker.sock:/var/run/docker.sock -e "SSH_AUTH_SOCK=/ssh-agent" ghcr.io/basecamp/kamal:latest'

Then, inside your app directory, run kamal init.

This creates a new file config/deploy.yml which you will use to configure your deployment.

Hardening servers guide #

Before you deploy to your servers, you should harden them. Here are some suggestions:

Hardening servers guide #

There are a few things you should do to harden your servers. Here are some suggestions:

  • Disable root login
  • Disable password login
  • Use SSH keys for login
  • Use a firewall (ufw)
  • Use fail2ban
  • Disable ports other than 80, 443 and your SSH port (22 by default)
  • Enable automatic security updates

Optional:

  • Use a non-standard SSH port (optional)
  • Bastion host (optional)

There are many guides online for hardening servers, but these are the basics.

Linode has a good guide here.

Some tools i like to include in my servers:

  • btop - Used to monitor server resources in real time (like top but better)
  • LazyDocker - A terminal UI for monitoring Docker containers

Setting up your servers for deployment #

After you have hardened your servers, you can deploy your app.

Tweak the config/deploy.yml file to match your app’s configuration.

There is some examples of what you can add to the file on the configuration page. More specefic technologies can be found in the menu on the left. (If not, let me know and i will add it)

Remember to edit the .env file to add your registry password and your specific environment variables.

Now you’re ready for your first deployment:

kamal setup

Your app should now be running on your servers.

If not you can check the logs using:

kamal setup --verbose
Tip: You can view all of the commands by running kamal --help.

Now you can start using Kamal to manage your deployments.

For future deployments, you can use kamal deploy.

Important: Remember to save your changes with Git before running kamal deploy.

Additional resources #

Random: Rabbit hole i went down: