Environment Variables

Spree uses environment variables for all deployment configuration. No secrets or credentials are stored in the codebase.

Required

These variables are required to run Spree in production.

Variable	Description	Example
`DATABASE_URL`	PostgreSQL connection URL	`postgres://user:pass@localhost:5432/spree`
`REDIS_URL`	Redis URL for background jobs (Sidekiq) and Action Cable	`redis://localhost:6379/0`
`REDIS_CACHE_URL`	Redis URL for caching (optional — falls back to `REDIS_URL`)	`redis://localhost:6380/0`
`SECRET_KEY_BASE`	Secret key for session encryption. Generate with `bin/rails secret`	`2fad5c0b79d25e4765d3018d8c740f8c3a665f0e5c...`

URLs and Hosts

RAILS_HOST is the canonical public host of your deployment. URLs Spree generates outside a request context use it — links in emails, webhook payloads, and image/attachment URLs in API responses (for the latter, CDN_HOST takes precedence when set).

When neither RAILS_HOST nor CDN_HOST is configured, image and attachment URLs fall back to the store’s URL setting, which is localhost on a fresh install — API responses will contain https://localhost/... URLs.

Variable	Default	Description
`RAILS_HOST`	—	Public host, optionally with a port — e.g. `store.example.com` or `203.0.113.7:8080`. Host only, no protocol. On Render, falls back to the platform-provided `RENDER_EXTERNAL_HOSTNAME`.
`CDN_HOST`	—	Optional host for serving static assets and images, e.g. a CDN distribution in front of your app. Host only, no protocol. Falls back to `RAILS_HOST`.

Generated URLs use https unless both RAILS_FORCE_SSL and RAILS_ASSUME_SSL are set to false (see SSL).

Email (SMTP)

This configuration is used for system emails (e.g. staff invitations, report ready, export complete). Customer facing emails are handled by the storefront via webhooks.

Spree works with any SMTP provider (Resend, Postmark, Mailgun, SendGrid, Amazon SES, etc.). Set SMTP_HOST to enable email delivery — when not set, no delivery method is configured and production email delivery fails (development opens emails in the browser via letter_opener).

Variable	Default	Description
`SMTP_HOST`	—	SMTP server address (e.g., `smtp.sendgrid.net`)
`SMTP_PORT`	`587`	SMTP server port
`SMTP_USERNAME`	—	SMTP auth username
`SMTP_PASSWORD`	—	SMTP auth password
`SMTP_FROM_ADDRESS`	—	Default “from” email address

Links in emails use the host configured via RAILS_HOST.

Web Server

Variable	Default	Description
`PORT`	`3000`	Web server port
`RAILS_MAX_THREADS`	`3`	Puma threads per worker
`WEB_CONCURRENCY`	`1`	Number of Puma workers. Set to `auto` for one per CPU core

Application

Variable	Default	Description
`RAILS_ENV`	`production`	Rails environment
`RAILS_LOG_LEVEL`	`info`	Log level (`debug`, `info`, `warn`, `error`)

File Storage (S3 / Cloudflare R2)

By default, uploaded files (product images, assets) are stored on the local filesystem. Set the appropriate credentials to use cloud storage instead. Spree auto-detects the provider based on which credentials are present.

Amazon S3

Variable	Default	Description
`AWS_ACCESS_KEY_ID`	—	AWS access key
`AWS_SECRET_ACCESS_KEY`	—	AWS secret key
`AWS_REGION`	—	AWS region (e.g., `us-east-1`)
`AWS_BUCKET`	`spree-production`	S3 bucket name

Cloudflare R2

Variable	Default	Description
`CLOUDFLARE_ENDPOINT`	—	R2 endpoint URL
`CLOUDFLARE_ACCESS_KEY_ID`	—	R2 access key
`CLOUDFLARE_SECRET_ACCESS_KEY`	—	R2 secret key
`CLOUDFLARE_BUCKET`	`spree-production`	R2 bucket name

Search (Meilisearch)

Optional. When configured, Spree uses Meilisearch for product search, filtering, and faceted navigation instead of SQL.

Variable	Default	Description
`MEILISEARCH_URL`	`http://localhost:7700`	Meilisearch server URL
`MEILISEARCH_API_KEY`	—	Meilisearch master key. Not needed for local development — only required when Meilisearch is started with `MEILI_MASTER_KEY`.

After setting these, enable the provider and reindex:

# config/initializers/spree.rb
Spree.search_provider = 'Spree::SearchProvider::Meilisearch'

spree rake spree:search:reindex

bundle exec rake spree:search:reindex

Error Tracking (Sentry)

Variable	Default	Description
`SENTRY_DSN`	—	Sentry DSN. When set, errors are reported to Sentry

SSL

By default, Spree assumes it runs behind an SSL-terminating reverse proxy. Set these to false if running without SSL (e.g., local development or behind a proxy that doesn’t do SSL termination).

Variable	Default	Description
`RAILS_ASSUME_SSL`	`true`	Assume requests arrive via SSL (sets `X-Forwarded-Proto`)
`RAILS_FORCE_SSL`	`true`	Redirect HTTP to HTTPS and use secure cookies

Local Development

These variables are used when running the server/ app locally (not via DATABASE_URL):

Variable	Default	Description
`DATABASE_HOST`	`localhost`	PostgreSQL host
`DATABASE_PORT`	`5432`	PostgreSQL port
`DATABASE_USERNAME`	`postgres`	PostgreSQL user

Deployment

Upgrading

Contributing

Security

Required

URLs and Hosts

Email (SMTP)

Web Server

Application

File Storage (S3 / Cloudflare R2)

Amazon S3

Cloudflare R2

Search (Meilisearch)

Error Tracking (Sentry)

SSL

Local Development

​Required

​URLs and Hosts

​Email (SMTP)

​Web Server

​Application

​File Storage (S3 / Cloudflare R2)

​Amazon S3

​Cloudflare R2

​Search (Meilisearch)

​Error Tracking (Sentry)

​SSL

​Local Development

Required

URLs and Hosts

Email (SMTP)

Web Server

Application

File Storage (S3 / Cloudflare R2)

Amazon S3

Cloudflare R2

Search (Meilisearch)

Error Tracking (Sentry)

SSL

Local Development