Documentation Index
Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt
Use this file to discover all available pages before exploring further.
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... |
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. SMTP_HOST to enable email delivery — when not set, emails are logged to stdout.
| 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 |
RAILS_HOST | example.com | Host used in email URLs |
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. |
# config/initializers/spree.rb
Spree.search_provider = 'Spree::SearchProvider::Meilisearch'
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 |
