Here’s some possible steps to take and notes from upgrading a single server Kamal setup to the new Kamal 2.
1. Upgrade to Kamal 1.9.x
First upgrade to Kamal 1.9 and confirm you can still deploy:
$ gem install kamal --version 1.9.0
$ kamal config
$ kamal deploy
2. Upgrade to Kamal 2
Update Kamal version again to a 2.x release:
$ gem install kamal --version 2.1.0
Do not redeploy just yet.
3. Remove Traefik mentions
Remove the Traefik section from config/deploy.yml:
traefik:
options:
publish:
- "443:443"
volume:
- "/letsencrypt/acme.json:/letsencrypt/acme.json"
network: "private"
...
And remove any other mentions of the proxy such as traefik.* labels everywhere.
4. Remove healthcheck section
Remove old healthcheck settings from config/deploy.yml:
healthcheck:
# path: /up
# port: 3000
interval: 5s
5. Update builder config
Remove the multiarch option and specify one or more architectures with arch (options are amd64 and arm64):
builder:
arch:
- amd64
- arm64
You likely want amd64. You can keep the cache settings.
Consult the official guide for remote builders.
6. Add the new proxy settings
Add a similar Kamal Proxy settings based on your needs:
proxy:
ssl: true
host: tubeandchill.com
app_port: 3000
healthcheck:
path: /up
interval: 3
timeout: 30
If you were issuing TLS certificates with Traefik, you can now replace it by setting ssl to true and specifying your host there. Otherwise you can skip it.
The healthcheck path remained the same at /up but you might need to remove the health check path from host check:
# for Rails 7+
config.host_authorization = { exclude: ->(request) { request.path == "/up" } }
The application port is now being set to 80 (was 3000). Change it back to 3000 here or update your Dockerfile to use 80.
7. Create new secrets file
Kamal changed how secrets work. Before you explore the new secrets options you can just move your old ones:
$ cp .env .kamal/secrets
This will mean .kamal/secrets also cannot be checked in source control, so add it to .gitignore.
You can explore the new secrets in more detail in documentation.
Note that there no convertion from .env.erb or kamal push env anymore. All gone.
8. Recheck your configuration
Recheck your new configuration by running kamal config:
$ kamal config
If you were using custom Docker networks for accessory communication, do not remove them just yet. Only if you named them kamal then delete them from the configuration as they would conflict.
9. Run in-place upgrade
Do a first Kamal 2 deploy by running an upgrade:
$ kamal upgrade
This will do a bunch of things like removing Traefik, creating the kamal Docker network, switch to Kamal Proxy, reboot the application and finally reboot accessories.
10. Remove custom Docker networks
Now you can likely remove your custom Docker network since everything can run with the new kamal one.
You can reboot your application and accessories to apply this latest change:
$ kamal deploy
$ kamal accessory reboot [ACCESSORY]
11. Fix wrong upgrade
Remember that if the upgrade replaces the proxy but fails later you can fix the underlying issue and continue yourself by redeploying the application or rebooting accessories.
