Deployment Guide

Omaship handles deployment automatically. Push to main and your changes are live. Open a PR and get a preview URL. Here's how it all works.

Automatic Deployment on Push

Every push to your main branch triggers an automatic deployment:

1. CI runs — Tests, linting, and security scans execute in GitHub Actions
2. Docker image builds — Your app is containerized with an optimized production image
3. Health check — The new container starts and passes health checks
4. Traffic switches — Zero-downtime cutover to the new version

The entire process typically takes 2-4 minutes. You can watch it live in your ship's dashboard or in GitHub Actions.

# That's it. Push and it's deployed.
git push origin main

Preview Deployments for PRs

Every pull request automatically gets its own preview deployment at:

pr-{number}-preview.yourdomain.com

Preview deployments are powered by the omaship_preview engine and require a wildcard DNS record:

CNAME *.preview → yourdomain.com

Previews are fully functional copies of your app with their own database. They're automatically cleaned up when the PR is merged or closed.

Kamal-Based Architecture

Omaship uses Kamal (by 37signals) under the hood for deployments. This means:

• Docker-based — Your app runs in containers for consistency between dev and prod
• Zero-downtime deploys — Kamal's rolling deployment ensures no dropped requests
• Traefik reverse proxy — Automatic SSL termination, routing, and load balancing
• No vendor lock-in — Standard Docker + SSH deployment, works on any VPS

The deployment configuration lives in config/deploy.yml in your repository. Omaship manages this file, but you can inspect it to understand your setup.

# View your deployment config
cat config/deploy.yml

# Check deployment status
kamal details

Rolling Back Deployments

If a deployment causes issues, you have two options:

Quick Rollback

From your ship's dashboard, click "Rollback" on any previous deployment to instantly revert to that version. This re-deploys the previous Docker image without rebuilding.

Git Revert

Revert the problematic commit and push. A new deployment triggers automatically:

git revert HEAD
git push origin main

Environment Variables & Secrets

Omaship manages your environment variables and secrets through GitHub's encrypted secrets, which are injected at deploy time.

How Secrets Work

• Omaship-managed secrets — Database URLs, deployment keys, and infrastructure credentials are set up automatically. Don't modify these.
• Your secrets — Add custom environment variables in Settings → Environment on your ship's dashboard

Adding a Secret

1. Go to your ship's Settings → Environment
2. Click "Add Variable"
3. Enter the key and value
4. Deploy to apply (secrets are injected during deployment)

# Access in your Rails app
ENV["MY_API_KEY"]
Rails.application.credentials.my_api_key

Next Steps

• Managing Ships — Ship creation, settings, and statuses
• DNS Setup — Configure your domain and enable previews
• Troubleshooting — Fix common deployment issues