Migrate from Kamal to Tenkai

Deploy the image Kamal already builds with Tenkai, and move its roles, secrets and database accessory, step by step.

Last verified on 2 November 2026 against Kamal's documentation. Report a mistake.

Kamal already builds your app into an image and pushes it to a registry, so Tenkai deploys that same image. Your roles, secrets and database accessory move to a Tenkai cluster. That cluster also backs up your database and installs your servers' updates when you ask.

What each part becomes

In Kamal On Tenkai
web role behind kamal-proxy Web application
Other roles with a cmd, such as workers Workers
image in your registry Container image
env.clear Variables
env.secret and .kamal/secrets Sensitive variables
Database accessory PostgreSQL or MySQL
Redis accessory Redis® or Valkey
Cron role Scheduled jobs
volumes of the app Kept directory
proxy.app_port Runtime port
proxy.host with ssl: true Custom domains

Before you start

You need a cluster with a project on it, as projects and clusters explains. Start it on a new server, so your Kamal hosts keep serving until you switch.

Tenkai pulls a public image, or a private image from GHCR. When your image is private on another registry, publish it to GHCR from your CI.

Move your app

  1. Create the web application. Add a web application, choose Container image and enter your image with a tag that moves with each build, such as ghcr.io/acme/app:latest, or main when the GHCR workflow builds it. Set its runtime port to your proxy.app_port, or 80 when you left it out.
  2. Copy the variables. Run kamal secrets print, wrap each value in single quotes and paste the lines in the project's Variables with Edit as .env…. Mark them Sensitive, and add your env.clear values next to them. A secret listed with an alias, such as DB_PASSWORD:MAIN_DB_PASSWORD, prints under its second name, so rename it to the first. Leave out the database URL, because a binding gives it.
  3. Stop the writes. Stop the web and cron roles with kamal app stop --roles=web,cron. Let your workers empty the queue, then stop them with kamal app stop.
  4. Copy the database accessory. Run kamal accessory exec db --reuse --raw "pg_dump -Fc --no-owner -U postgres app" > app.dump with your accessory's name, user and database. Upload the file to your storage bucket, add a PostgreSQL and choose From dump under Initial data.
  5. Bind the databases. Bind the database to the web application with the name your app reads, such as DATABASE_URL. A Rails 8 app keeps Solid Cache, Queue and Cable in this one database, as the Rails guide explains. For a Redis accessory, add a Redis® and bind it, so the app receives REDIS_URL. The new store starts empty, so sessions and other Redis data start over.
  6. Add the workers and the cron role. Each other role becomes a worker from the same image. Its cmd becomes the entrypoint, after your image's ENTRYPOINT script, as in /rails/bin/docker-entrypoint bin/jobs. Each line of your config/crontab becomes a scheduled job with the line's schedule in UTC and its command in sh -c '…'. Bind the databases to each of them.
  7. Deploy and point your domain. Deploy the web application, then the workers and scheduled jobs, and check the default address. Add each deploy hook to your workflow after the push of your image, as deploy from GitHub Actions explains. Then add your proxy.host and point its DNS record to the one Tenkai shows.

Volumes

A volumes entry, such as app_storage:/rails/storage, becomes a kept directory at its container path. Rails 8 keeps its SQLite databases and Active Storage files there. Deploy the application once, then bring the files over. Pack /var/lib/docker/volumes/app_storage/_data with tar on your Kamal host, put the archive at an HTTPS address and download it into the directory from the application's terminal.

Sources

We read these pages on 2 November 2026, with Kamal 2.12.0.

Redis is a registered trademark of Redis Ltd. Any rights therein are reserved to Redis Ltd.

Something wrong in this guide?

Kamal and Tenkai both change, so a step can go out of date. If a command fails or a step does not match what you see, tell us at [email protected]. Once you have an account, you can also choose “Report a bug” in your user menu, as the account guide explains. We fix the guide and reply to you.

Bring your apps home

Enroll a server you already rent and deploy your first application. Free for one server, no credit card.

Start for free