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
- 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, ormainwhen the GHCR workflow builds it. Set its runtime port to yourproxy.app_port, or 80 when you left it out. - 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 yourenv.clearvalues next to them. A secret listed with an alias, such asDB_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. - 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 withkamal app stop. - Copy the database accessory. Run
kamal accessory exec db --reuse --raw "pg_dump -Fc --no-owner -U postgres app" > app.dumpwith your accessory's name, user and database. Upload the file to your storage bucket, add a PostgreSQL and choose From dump under Initial data. - 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 receivesREDIS_URL. The new store starts empty, so sessions and other Redis data start over. - Add the workers and the cron role. Each other role becomes a worker from the same image. Its
cmdbecomes the entrypoint, after your image'sENTRYPOINTscript, as in/rails/bin/docker-entrypoint bin/jobs. Each line of yourconfig/crontabbecomes a scheduled job with the line's schedule in UTC and its command insh -c '…'. Bind the databases to each of them. - 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.hostand 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.
- Kamal, Configuration and Roles
- Kamal, Proxy and Docker registry
- Kamal, Environment variables and Secrets
- Kamal, Accessories and app commands
- Kamal, Cron
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.