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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Document new RAILS_HOST and CDN_HOST env vars (#14312)
Damian Legawiec09edaaf6bd35
diff --git a/docs/developer/deployment/cdn.mdx b/docs/developer/deployment/cdn.mdxindex f45dbadaaa..4058962ded 100644--- a/docs/developer/deployment/cdn.mdx+++ b/docs/developer/deployment/cdn.mdx@@ -36,4 +36,14 @@ Now scroll down and set the settings as below:-Finally, click on "Deploy" and you are done!\ No newline at end of file+Finally, click on "Deploy" and you are done!++## Dedicated CDN Host++The setup above caches on your primary domain and needs no extra configuration. If you instead serve assets and images from a separate CDN hostname (e.g. a CloudFront or Fastly distribution at `cdn.example.com` with your app as the origin), set the `CDN_HOST` environment variable:++```bash+CDN_HOST=cdn.example.com+```++Static asset URLs and image/attachment URLs (including those in API responses) will then use this host instead of [`RAILS_HOST`](/developer/deployment/environment_variables#urls-and-hosts). Host only, no protocol — URLs keep the scheme of your primary host.\ No newline at end of filediff --git a/docs/developer/deployment/docker.mdx b/docs/developer/deployment/docker.mdxindex f44b68f19d..8e510f4f09 100644--- a/docs/developer/deployment/docker.mdx+++ b/docs/developer/deployment/docker.mdx@@ -62,6 +62,9 @@ services:SECRET_KEY_BASE: change-me-to-a-real-secretRAILS_FORCE_SSL: "false"RAILS_ASSUME_SSL: "false"+ # Public host used in generated URLs (images/attachments in API+ # responses, email links) — set to your domain or IP in production.+ RAILS_HOST: localhost:3000ports:- "3000:3000"healthcheck:@@ -80,6 +83,7 @@ services:DATABASE_URL: postgres://postgres@postgres:5432/spree_productionREDIS_URL: redis://redis:6379/0SECRET_KEY_BASE: change-me-to-a-real-secret+ RAILS_HOST: localhost:3000command: bundle exec sidekiqvolumes:@@ -106,6 +110,7 @@ Use [create-spree-app](/developer/create-spree-app/quickstart) for a fully scaff| `DATABASE_URL` | PostgreSQL connection URL | `postgres://user:pass@host:5432/spree` || `REDIS_URL` | Redis URL for jobs, caching, and Action Cable | `redis://redis:6379/0` || `SECRET_KEY_BASE` | Secret key for session encryption | Generate with `bin/rails secret` |+| `RAILS_HOST` | Public host used in generated URLs — image/attachment URLs in API responses, email links. Without it they fall back to the store's URL setting (`localhost` on a fresh install) | `store.example.com` |See [Environment Variables](/developer/deployment/environment_variables) for the full list.diff --git a/docs/developer/deployment/emails.mdx b/docs/developer/deployment/emails.mdxindex 8ee371be72..d305c7b95e 100644--- a/docs/developer/deployment/emails.mdx+++ b/docs/developer/deployment/emails.mdx@@ -80,7 +80,7 @@ Set the following environment variables on the **Spree backend** to enable syste| `SMTP_USERNAME` | — | SMTP auth username || `SMTP_PASSWORD` | — | SMTP auth password || `SMTP_FROM_ADDRESS` | — | Default "from" email address (e.g., `[email protected]`) |-| `RAILS_HOST` | `example.com` | Host used in email URLs |+| `RAILS_HOST` | `example.com` | Public host used in email links and other [generated URLs](/developer/deployment/environment_variables#urls-and-hosts) — image/attachment URLs use `CDN_HOST` instead when set |When `SMTP_HOST` is not set, emails are printed to the Rails log instead of being sent.diff --git a/docs/developer/deployment/environment_variables.mdx b/docs/developer/deployment/environment_variables.mdxindex e7f1d29e48..d2e34b83d9 100644--- a/docs/developer/deployment/environment_variables.mdx+++ b/docs/developer/deployment/environment_variables.mdx@@ -16,6 +16,21 @@ These variables are required to run Spree in production.| `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).++<Warning>+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.+</Warning>++| 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](/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. 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](#ssl)).+## Email (SMTP)<Tip>@@ -31,7 +46,8 @@ Spree works with any SMTP provider (Resend, Postmark, Mailgun, SendGrid, Amazon| `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 |++Links in emails use the host configured via [`RAILS_HOST`](#urls-and-hosts).## Web Serverdiff --git a/docs/developer/deployment/render.mdx b/docs/developer/deployment/render.mdxindex 6b70b9b83f..0adc74ed3b 100644--- a/docs/developer/deployment/render.mdx+++ b/docs/developer/deployment/render.mdx@@ -57,6 +57,8 @@ Default credentials are created during `db:seed`. Change them immediately afterRender sets `DATABASE_URL`, `REDIS_URL`, and `SECRET_KEY_BASE` automatically from the blueprint. For additional configuration (SMTP, file storage, Sentry, etc.), see [Environment Variables](/developer/deployment/environment_variables).+Generated URLs (images and attachments in API responses, email links) automatically use Render's `RENDER_EXTERNAL_HOSTNAME` (`<your-app-name>.onrender.com`). When you attach a custom domain, set [`RAILS_HOST`](/developer/deployment/environment_variables#urls-and-hosts) to it — it takes precedence.+## Production SizingThe free/starter plans work for trying Spree. For production workloads, we recommend: