How Omaship Works

Omaship uses Rails engines to provide functionality while letting you customize everything.

The Engine Model

Your app includes several Omaship engines — Ruby gems that provide features. Each engine adds controllers, views, jobs, migrations, and workflows. Engines are installed in your Gemfile and receive updates when you run bundle update.

Managed vs User Files

This is the key concept. Omaship creates two types of files:

Managed files are updated automatically — don't edit these directly. These include _omaship-*.yml workflows, engine gem code, and core migrations.

User files are yours to customize and are never overwritten. These include deploy-production.yml, ci.yml, your app code, and template overrides.

How Updates Work

1. We release a new version of an engine
2. Omaship opens a PR in your repo with the update
3. You review the changes
4. Merge when ready

Overriding Engine Behavior

Rails looks for files in your app first, then falls back to engine files. To customize anything, create a file at the same path in your app — your version takes precedence.

# Engine provides:
gems/omaship_base/app/views/pages/home.html.erb

# You override with:
app/views/pages/home.html.erb

This works for views, partials, controllers, and styles:

# Override partials
app/views/shared/_header.html.erb
app/views/shared/_footer.html.erb

# Override controllers
app/controllers/pages_controller.rb

To find templates you can override, run bundle show omaship_base and browse its app/views directory.

The Engines

• omaship_base — CI/CD workflows, Kamal deployment, security scanning, infrastructure updates
• omaship_preview — PR preview deployments at pr-N-preview.yourdomain.com
• omaship_backup — Daily automated SQLite backups (local 7 days, cloud 30 days)
• omaship_payments — Stripe integration, subscriptions, customer billing portal
• omaship_admin — Admin dashboard for users, content, and settings
• omaship_landing — Editable landing page components (hero, features, pricing, FAQ)
• omaship_newsletter — Email campaigns, subscriber management, open/click tracking

Deployment

Omaship uses Kamal for deployment. When you push to main, CI builds a Docker image, pushes it to GitHub Container Registry, and deploys with zero downtime. You don't need to run Kamal manually — CI/CD handles it.

Configuration lives in config/deploy.yml (a user file you can customize).