Docs menu
Deploying Rails
Deploy a Ruby on Rails app on Primcloud: Procfile, RAILS_MASTER_KEY, DATABASE_URL, migrations, and asset compilation.
On this page
Rails apps deploy on Primcloud through the standard Ruby build. Primcloud detects Rails from the railties gem in Gemfile.lock, generates a default web process that runs bin/rails server, and runs rake assets:precompile during the build. This page covers what Rails needs on top of the language defaults: environment variables, migrations, asset gotchas.
Starter template#
Use Heroku's heroku/ruby-rails-sample as a working reference. It's a small Rails app that boots on Primcloud with no changes beyond setting RAILS_MASTER_KEY and pointing at a PostgreSQL database.
If you're bootstrapping a new app from scratch, rails new produces a repo that deploys as-is, with two adjustments:
- Use PostgreSQL (
gem 'pg'), not SQLite. Primcloud's filesystem is ephemeral, so SQLite data doesn't survive a restart. - Commit
Gemfile.lock. Some.gitignoretemplates exclude it; don't.
Procfile for Rails on Primcloud#
You don't strictly need a Procfile. Primcloud auto-generates a web process for Rails apps:
web: bin/rails server --binding "[::]" --port "$PORT" --environment "$RAILS_ENV"
Ship a Procfile when you need more than just web: background workers, schedulers, release commands. A minimal Rails app with Sidekiq:
web: bundle exec puma -C config/puma.rb
worker: bundle exec sidekiq
If you write your own web line, Primcloud uses it verbatim, and the generated default is discarded. Bind to $PORT explicitly, and remember to enable IPv6 binding ("[::]") if you want IPv6 support.
Puma config. Rails 7+ generates a config/puma.rb that reads workers and threads from WEB_CONCURRENCY and RAILS_MAX_THREADS. Both are worth tuning per compute size. Start with WEB_CONCURRENCY=2 and RAILS_MAX_THREADS=5 on Standard 1x.
Release-time migrations. Rails migrations don't run automatically. Options:
- Ship a
releaseprocess type in yourProcfile:release: bin/rails db:migrate. This runs after the build succeeds, before the new version takes traffic, and the deploy fails if migrations fail. - Or run migrations manually from the Tasks feature after a deploy.
Env vars this framework expects#
Set these under Settings → Secrets. Primcloud provides defaults for the ones it can; the rest are on you.
Provided by Primcloud (override in the panel to change):
| Variable | Default | Notes |
|---|---|---|
RAILS_ENV |
production |
Which Rails environment to boot. |
RACK_ENV |
production |
Rack fallback. |
RAILS_SERVE_STATIC_FILES |
enabled |
Puma serves public/ files. |
RAILS_LOG_TO_STDOUT |
enabled |
Logs stream to the Logs page. |
SECRET_KEY_BASE |
Random, cached per app | Rails session/cookie signing key. |
You must set (Rails won't boot without these when your app relies on them):
DATABASE_URL: connection string for your PostgreSQL database. Format:postgres://user:pass@host:5432/dbname.RAILS_MASTER_KEY: the 32-byte hex value fromconfig/master.key(orconfig/credentials/production.key). Required if your app readsRails.application.credentials, which every fresh Rails app does. Never commitmaster.keyto your repo.
Commonly set (depending on the app):
REDIS_URL: if you're using Sidekiq, ActionCable's Redis adapter, or a Redis-backed cache. Format:redis://user:pass@host:6379/0.WEB_CONCURRENCY: number of Puma worker processes. Start with2on Standard 1x.RAILS_MAX_THREADS: threads per Puma worker. Default5from the Rails template.
Framework gotchas on Primcloud#
SQLite doesn't work for production. Primcloud's filesystem is ephemeral: files written to disk don't survive a restart, and each copy of a formation has its own filesystem. Use PostgreSQL. rails new --database=postgresql from the start; if you're on SQLite already, swap the adapter and re-run bundle install.
Assets precompile at build time. rake assets:precompile runs during the build, not in your running app. Anything the compile step needs (encrypted credentials, database access, external services) must be available then. This is why RAILS_MASTER_KEY needs to be set: Rails initializes the app during precompile, and initialization reads credentials.
If your compile step tries to reach the database (config.eager_load = true combined with certain initializers), it will fail at build time unless DATABASE_URL is also reachable. Options:
- Set
SECRET_KEY_BASE_DUMMY=1in the panel (Rails 7.1+). Rails uses a placeholder key during precompile so credentials access doesn't fail the build. - Restructure the code so DB access only happens at request time, not during initialization.
Node/Yarn for asset pipelines. If your app uses jsbundling-rails (esbuild, Rollup, Webpack) or cssbundling-rails, commit a package.json (and a yarn.lock if you use Yarn). The build detects them and installs Node.js so the JS toolchain is available during rake assets:precompile. If you bundle with Bun, commit bun.lock instead and Bun is installed for the asset build.
No Rails cache warmer runs. Nothing preloads Rails' cache after deploy. Rails will lazy-load classes on the first few requests, which can spike latency. Enable config.eager_load = true in config/environments/production.rb (Rails does this by default in newer versions) so classes load at boot instead.
Solid Cable / Solid Cache / Solid Queue. Rails 8's default adapters use PostgreSQL for background jobs, cable, and cache. They work on Primcloud; just make sure the tables exist. bin/rails db:migrate creates them from the generated migrations.
Active Storage. Local disk storage doesn't survive restarts. Configure config/storage.yml to use S3, GCS, or another remote backend, and set the corresponding credentials under Settings → Secrets.
Troubleshooting#
ActiveRecord::PendingMigrationError. Migrations weren't run before the app started. Add a release: bin/rails db:migrate line to your Procfile, or run migrations from the Tasks feature before your next deploy.
ActiveSupport::MessageEncryptor::InvalidMessage. RAILS_MASTER_KEY is missing or wrong. Copy the value from your local config/master.key into Settings → Secrets exactly (no trailing newline).
SECRET_KEY_BASE missing in production. You explicitly unset it, and Rails now can't boot. Delete the override under Settings → Secrets. Primcloud then sets one for you again.
Assets 404 in production. Either RAILS_SERVE_STATIC_FILES was disabled, or rake assets:precompile didn't run. Check the build log for the precompile step's output; check the env panel for RAILS_SERVE_STATIC_FILES=enabled.
"Not found: /rails/info/routes" or "Blocked host" in production. Rails' config.hosts allowlist rejects requests whose Host header isn't in the list. Add your Primcloud domain and any custom domain:
config.hosts << ENV.fetch("APP_HOSTNAME", "your-app.primcloud.app")
config.hosts << "yourdomain.com"
Or, if you're behind trusted infrastructure, config.hosts.clear disables the check entirely.