v1.0.0

What's changed

• Asset bridging by @djmb in #449 and #467
• Copy env files to remote hosts by @djmb in #438
• Add a require_destination setting by @djmb in #451
• Configurable Healthcheck Expose Port by @rience in #443
• Configurable Kamal directory by @djmb in #437
• Configurable Number of Lines in Healthcheck Log Output by @rience in #444
• Zero downtime deployment with cord file by @djmb in #439
• Fix: do not hardcode Net::SSH auth_methods by @gf3 in #440
• Fix: Prune healthcheck containers by @djmb in #425
• Fix: Stop stale containers when deploying by @djmb in #450
• Fix: Connect to remote host before creating builder by @djmb in #452
• Fix: Validate the build image by @djmb in #456
• Fix: Run interactive commands with the correct host by @djmb in #476

Full changelog: v0.16.1...v1.0.0

🎉🎉

Upgrading to 1.0

There are some significant changes in v1.0 of Kamal. You should test out the upgrade in a non-production environment first.

Upgrade steps

1. First push your env files to the hosts, either with:

• kamal envify [-d destination]
• Or if you manage .env files yourself, kamal env push [-d destination]

2. You should then reboot traefik and any accessories to pick up the new env files.
3. Then you can deploy your app

ENV files

Environment variables are now passed to the Docker containers via ENV files. The files are written to the hosts by the kamal env push command. This allows more control of when environment variables are changed and means that someone can run commands without needing to set up the environment locally.

Shell expansion no longer works with environment variables because they are no longer passed to docker run as command line arguments.

Run directory

Files are stored under in .kamal on the hosts. Existing lock and audit files are not migrated. You can configure this with the run_directory setting.

Zero-downtime deployments

To prevent Traefik from sending requests to a container that is shutting down, it needs to see the container as unhealthy before we call docker stop. We do this via a "cord". This is a file in a volume mounted into /tmp/kamal-cord in the container. The healthcheck is re-written to also check for the file.

To mark a container as unhealthy we delete the file or "cut the cord". The healthcheck will fail, Traefik will stop sending requests and then we can shut down the container safely. You can change the directory the cord will be stored in with:

healthcheck:
  cord: /var/run/kamal/cord

Or set it to false to disable the cord. However, this will remove the zero-downtime guarantee.

Assets

During a deployment you may get requests for old JS/CSS going to the new container and visa versa. To prevent 404s, tell Kamal where the those assets are stored in the container. Kamal will mount a volume containing both old and new files into that location.

asset_path: /rails/public/assets

External image verification

If you pull your own images (using kamal deploy --skip_push), they now need to be tagged with a label service=<app name>. This is so we find them when pruning old images.