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.

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.mdx
index 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:
![Cloudflare Cache Rule Settings](/images/developer/deployment/cloudflare_cache_rule_2.png)
-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 file
diff --git a/docs/developer/deployment/docker.mdx b/docs/developer/deployment/docker.mdx
index 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-secret
RAILS_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:3000
ports:
- "3000:3000"
healthcheck:
@@ -80,6 +83,7 @@ services:
DATABASE_URL: postgres://postgres@postgres:5432/spree_production
REDIS_URL: redis://redis:6379/0
SECRET_KEY_BASE: change-me-to-a-real-secret
+ RAILS_HOST: localhost:3000
command: bundle exec sidekiq
volumes:
@@ -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.mdx
index 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.mdx
index 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 Server
diff --git a/docs/developer/deployment/render.mdx b/docs/developer/deployment/render.mdx
index 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 after
Render 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 Sizing
The free/starter plans work for trying Spree. For production workloads, we recommend: