Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

12.0 KB
Raw Blame
---
title: Environment Variables
description: Reference for Spree deployment environment variables — database, secrets and encryption keys, web server, background jobs, SMTP, file storage, and application settings.
---

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

## Required

These two variables are all a production deployment strictly needs:

| Variable | Description | Example |
| --- | --- | --- |
| `DATABASE_URL` | Database connection URL — see [Database Configuration](/developer/deployment/database) | `postgres://user:pass@localhost:5432/spree` |
| `SECRET_KEY_BASE` | Secret used to encrypt sessions and cookies. Generate with `openssl rand -hex 64` | `2fad5c0b79d25e4765d3018d8c740f8c3a665f0e5c...` |

You'll almost always want to set [`SPREE_HOST`](#urls-and-hosts) too — without it, generated URLs point at `localhost`, and the three [Active Record encryption](#active-record-encryption) keys — without them, secrets Spree stores are kept in plain text.

## Active Record encryption

Spree encrypts sensitive values at rest with [Active Record encryption](https://guides.rubyonrails.org/active_record_encryption.html): payment gateway and integration secrets (API keys and webhook signing secrets), webhook endpoint signing secrets, payment gateway customer IDs, and the OAuth tokens stored on user identities. It does so only when encryption keys are configured — without them, these values are stored in plain text and a production app logs a warning at boot.

| Variable | Description |
| --- | --- |
| `ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY` | Key for (non-deterministic) encrypted attributes |
| `ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY` | Key for deterministic encrypted attributes — the ones Spree looks records up by, such as webhook signing secrets and gateway customer IDs |
| `ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT` | Salt for deriving the encryption keys |

Set all three. Each is a random string — generate a set with any of:

<CodeGroup>

```bash Spree CLI
spree encryption init           # writes a set to your project's .env (never overwrites existing keys)
spree encryption init --print   # prints a fresh set, e.g. for your hosting provider
```

```bash Without Spree CLI
bin/rails db:encryption:init
```

</CodeGroup>

- **New projects** — `create-spree-app` generates the keys into `.env`, and the [Render Blueprint](/developer/deployment/render) generates them for production.
- **Production** — use a separate set of keys from development and store it in your secret manager as a backup.
- **Rails credentials** — instead of env vars, you can put the values printed by `bin/rails db:encryption:init` under `active_record_encryption` in your encrypted credentials. When both are present, the env vars win.

<Warning>
Never change or lose the keys once data is encrypted — records encrypted with them become unreadable. Rails supports [rotating the primary key](https://guides.rubyonrails.org/active_record_encryption.html#rotating-keys) by adding the new key and keeping the old one, but it doesn't support rotating the deterministic key — and webhook endpoint secrets and gateway customer IDs are encrypted deterministically. Keep `ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY` and `ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT` unchanged unless you plan a migration that re-encrypts those records.
</Warning>

### Enabling encryption on an existing installation

Records written before the keys were set are stored in plain text. OAuth tokens on user identities stay readable and are encrypted on their next write. Webhook endpoint secrets and gateway customer IDs are not readable in plain text once encryption is on, so enable encryption with plaintext support first, then encrypt the existing rows:

1. Allow reading and looking up plaintext rows in `config/application.rb`:

   ```ruby
   config.active_record.encryption.support_unencrypted_data = true
   config.active_record.encryption.extend_queries = true
   ```

2. Set the three keys ([see above](#active-record-encryption)) and deploy.
3. Encrypt the existing rows from a Rails console (`spree console` or `bin/rails console`):

   ```ruby
   [Spree::WebhookEndpoint, Spree::GatewayCustomer, Spree::UserIdentity].each { |model| model.find_each(&:encrypt) }
   ```

4. Remove the two settings from step 1 and deploy again.

Apps created from an older `spree-starter` also need `config/application.rb` to read the env vars — see the [5.6 to 6.0 upgrade guide](/developer/upgrades/5.6-to-6.0#enable-active-record-encryption).

## URLs and Hosts

`SPREE_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).

<Note>
  This setting used to be called `RAILS_HOST`. That name still works, so an existing deployment needs no change — `SPREE_HOST` wins when both are set.
</Note>

<Warning>
When neither `SPREE_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.
</Warning>

| Variable | Default | Description |
| --- | --- | --- |
| `SPREE_HOST` | — | Public host, optionally with a port — e.g. `store.example.com` or `203.0.113.7:8080`. Host only, no protocol. On [Render](/developer/deployment/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 — see [CDN](/developer/deployment/cdn). Host only, no protocol. Falls back to `SPREE_HOST`. |

Generated URLs use `https` unless both `RAILS_FORCE_SSL` and `RAILS_ASSUME_SSL` are set to `false` (see [SSL](#ssl)).

## Web Server

| Variable | Default | Description |
| --- | --- | --- |
| `PORT` | `3000` | Port the web server listens on |
| `RAILS_MAX_THREADS` | `3` | Concurrent requests each web server process handles |
| `WEB_CONCURRENCY` | `1` | Number of web server processes per container. Set to `auto` for one per CPU core — each process needs roughly 1 GB of RAM |

## Background Jobs

Background jobs (emails, image processing, webhooks, imports) run inside the web container by default — no extra service needed. See [Background Jobs](/developer/deployment/background_jobs) for how this works and when to split out a dedicated worker.

| Variable | Default | Description |
| --- | --- | --- |
| `SOLID_QUEUE_IN_PUMA` | `true` | Run background jobs inside the web container. Set to `false` when you run a dedicated worker service (`bin/jobs`) |
| `JOB_THREADS` | `3` | How many background jobs run concurrently. Raise it on a dedicated worker; the database connection pool sizes itself from this |
| `JOB_CONCURRENCY` | `1` | Number of worker processes — the scaling knob for a dedicated worker |
| `SPREE_IMPORT_JOB_CONCURRENCY` | 75% of `JOB_THREADS` | How much of the job capacity a single CSV import may occupy, so imports can't starve other work. `0` removes the cap |
| `MISSION_CONTROL_USER` / `MISSION_CONTROL_PASSWORD` | — | Login for the `/jobs` dashboard (HTTP Basic auth). Required in production — the dashboard stays locked without them |

## Email (SMTP)

<Tip>
This configuration powers all emails Spree sends — customer transactional emails (order confirmation, shipping notification; on by default) and staff notifications. A storefront can optionally take over customer emails via webhooks — see [Emails](/developer/deployment/emails).
</Tip>

Spree works with any SMTP provider (Resend, Postmark, Mailgun, SendGrid, Amazon SES, etc.). Set `SMTP_HOST` to enable email delivery — when not set, production email delivery is disabled (in development, emails are captured by Mailpit at `http://localhost:8025` instead of being sent). See [Emails](/developer/deployment/emails) for the full guide.

| 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 [`SPREE_HOST`](#urls-and-hosts).

## Application

| Variable | Default | Description |
| --- | --- | --- |
| `RAILS_ENV` | `production` | Runtime environment — leave as `production` when deploying |
| `RAILS_LOG_LEVEL` | `info` | Log level (`debug`, `info`, `warn`, `error`) |
| `SPREE_TELEMETRY_DISABLED` | — | Set to `1` to stop the usage data the daily update check sends; the check keeps sending the version. `DO_NOT_TRACK=1` does the same. See [Update Checks and Usage Data](/developer/deployment/usage-data) |
| `SPREE_UPDATE_CHECK_DISABLED` | — | Set to `1` to stop the daily update check entirely; the dashboard's update notice never appears |

## 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. See [Asset Storage](/developer/deployment/assets) for the full guide.

### 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](/integrations/search/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`. In production always start Meilisearch with a master key and set this to match: without one, anyone who can reach port 7700 can read, rewrite or delete the index. The master key is the control to rely on; keeping the port unpublished or bound to `127.0.0.1` is defence in depth, not a substitute — on Linux a `ports:` entry bypasses `ufw`/`firewalld`, and Docker engines older than 28.0.1 can leak even unpublished ports to the LAN ([why](/developer/deployment/docker#published-ports-and-firewalls)). |

After setting these, add the `spree_meilisearch` gem, enable the provider and reindex:

```ruby
# config/initializers/spree.rb
Spree.search_provider = 'SpreeMeilisearch::SearchProvider'
```

<CodeGroup>

```bash Spree CLI (Docker)
spree task search:reindex
```

```bash Without Spree CLI
bundle exec rake spree:search:reindex
```

</CodeGroup>

## Error Tracking (Sentry)

| Variable | Default | Description |
| --- | --- | --- |
| `SENTRY_DSN` | — | [Sentry](https://sentry.io/) DSN. When set, errors are reported to Sentry |

## SSL

By default, Spree assumes it runs behind an SSL-terminating reverse proxy or load balancer. 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` | Treat incoming requests as arriving over HTTPS (trust the proxy's forwarded headers) |
| `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 |