@spree/docs 0.1.126 → 0.1.127

package/dist/developer/deployment/cdn.md

@@ -37,3 +37,13 @@ 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!
+
+## 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`](environment_variables.md#urls-and-hosts). Host only, no protocol — URLs keep the scheme of your primary host.

package/dist/developer/deployment/docker.md

@@ -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:
@@ -104,6 +108,7 @@ The database is automatically created and migrated on first boot. The app is ava
 | `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](environment_variables.md) for the full list.
 

package/dist/developer/deployment/emails.md

@@ -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., `admin@mystore.com`) |
-| `RAILS_HOST` | `example.com` | Host used in email URLs |
+| `RAILS_HOST` | `example.com` | Public host used in email links and other [generated URLs](environment_variables.md#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.
 

package/dist/developer/deployment/environment_variables.md

@@ -16,6 +16,19 @@ 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.
+
+| 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](render.md), 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:** 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](../storefront/nextjs/customization.md#transactional-emails).
@@ -29,7 +42,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
 

package/dist/developer/deployment/render.md

@@ -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](environment_variables.md).
 
+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`](environment_variables.md#urls-and-hosts) to it — it takes precedence.
+
 ## Production Sizing
 
 The free/starter plans work for trying Spree. For production workloads, we recommend:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.126",
+  "version": "0.1.127",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",