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 Docker port security and upgrade guidance (#15088)

Damian Legawiecdce5d228623d
diff --git a/docs/developer/deployment/aws.mdx b/docs/developer/deployment/aws.mdx
index a94c3c04ec..602ae8f887 100644
--- a/docs/developer/deployment/aws.mdx
+++ b/docs/developer/deployment/aws.mdx
@@ -37,6 +37,10 @@ Then install Docker:
curl -fsSL https://get.docker.com | sh
```
+<Note>
+ The security group is the firewall here, and it does its job regardless of Docker: it filters traffic before it reaches the instance. A host firewall like `ufw` would not — Docker's own `iptables` rules publish container ports straight past it. That is also why the compose file below publishes only Caddy's `80` and `443`: `web` has no `ports:` entry, so port 3000 is reachable only from Caddy. See [Published ports and firewalls](/developer/deployment/docker#published-ports-and-firewalls) before adding one.
+</Note>
+
## 3. Run Spree
Build [your project's image](/developer/deployment/docker) and push it to a registry the instance can pull from (ECR or any other) — or use the stock `ghcr.io/spree/spree:latest` image to start. Then create a `docker-compose.yml` on the instance:
diff --git a/docs/developer/deployment/docker.mdx b/docs/developer/deployment/docker.mdx
index 8d96f7d3e9..5436593510 100644
--- a/docs/developer/deployment/docker.mdx
+++ b/docs/developer/deployment/docker.mdx
@@ -38,6 +38,10 @@ services:
image: postgres:18-alpine
environment:
POSTGRES_HOST_AUTH_METHOD: trust
+ # No ports: — Postgres is reachable only from the compose network (on
+ # Docker Engine 28.0.1+; older engines can leak unpublished ports to the
+ # LAN). Trust auth is safe for exactly as long as this stays true; see
+ # "Published ports and firewalls" below before adding a ports: entry.
volumes:
- postgres_data:/var/lib/postgresql
healthcheck:
@@ -65,6 +69,8 @@ services:
# responses, email links) — set to your domain or IP in production.
SPREE_HOST: localhost:3000
ports:
+ # Published on every interface, straight past ufw/firewalld. Fine on a
+ # laptop; on an internet-facing host see "Published ports and firewalls".
- "3000:3000"
healthcheck:
test: curl -f http://localhost:3000/up || exit 1
@@ -110,6 +116,32 @@ Background jobs run inside the web container by default. When job load deserves
command: bin/jobs
```
+### Published ports and firewalls
+
+On Linux, every `ports:` entry is implemented with Docker's own `iptables` NAT and `FORWARD` rules, and those rules are evaluated **before** the host's `INPUT` chain. A host firewall such as `ufw` or `firewalld` never sees that traffic: `ufw default deny incoming` with `ports: "5432:5432"` in a compose file still leaves Postgres open to the whole internet, and a database or cache published that way is found by scanners within minutes. Docker Engine 28.0 tightened what *unpublished* ports leak to the local network, but a port published on all interfaces is as reachable on Docker 28 as it was before.
+
+<Warning>
+ Never add a `ports:` entry to `postgres` (or Redis, or Meilisearch) on an internet-facing host. The compose file above runs Postgres with `POSTGRES_HOST_AUTH_METHOD: trust` — passwordless — which is only safe because the container has no published port and is reachable solely from the compose network. `spree upgrade` does not rewrite compose files, so projects created before Spree 5.5.2 should [check their port bindings](/developer/upgrades/5.6-to-6.0#check-the-ports-your-compose-files-publish).
+</Warning>
+
+What this means for a production host:
+
+- **Terminate TLS inside compose and don't publish `web` at all.** Add a Caddy (or nginx) service that proxies to `web:3000` and publishes only `80` and `443`, as the [EC2 guide](/developer/deployment/aws#3-run-spree) does. Then the only published ports are the ones you meant to open.
+- **If a reverse proxy runs on the host instead**, bind the app to loopback so the proxy is the only way in:
+
+ ```yaml
+ ports:
+ - "127.0.0.1:3000:3000"
+ ```
+
+ With a plain `"3000:3000"` the app also answers directly on port 3000, over plain HTTP, no matter what `ufw` says.
+- **Debug ports stay on loopback.** A Postgres port for `psql`, a Mailpit UI, a Meilisearch dashboard: publish them as `127.0.0.1:<port>:<port>`, or better, don't publish them and use `docker compose exec` instead. The spree-starter compose files already do this.
+- **A cloud security group is unaffected.** AWS security groups, Hetzner Cloud firewalls, DigitalOcean firewalls and the like filter traffic before it reaches the host, so Docker's rules can't bypass them. They are a reliable place to allow only `80` and `443`.
+- **To filter published ports on the host anyway**, put the rules in Docker's `DOCKER-USER` chain, which Docker evaluates before its own forwarding rules. Setting `"iptables": false` in the daemon config is not a practical alternative — containers lose outbound NAT.
+- **Run Docker Engine 28.0.1 or newer.** Older engines let hosts on the same LAN reach container ports that were never published by routing straight to the container's IP. `curl -fsSL https://get.docker.com | sh` installs a current engine; a distribution's `docker.io` package may not.
+
+Check what a host actually exposes with `docker ps` — every container on the host, where `docker compose ps` covers one project. The PORTS column shows `0.0.0.0:` for an all-interfaces publish and `127.0.0.1:` for loopback. `ss -tlnp` on the host is a second opinion, but it lists only host sockets, so it misses NAT-only publishes when `userland-proxy` is turned off.
+
### Required Environment Variables
| Variable | Description | Example |
diff --git a/docs/developer/deployment/environment_variables.mdx b/docs/developer/deployment/environment_variables.mdx
index 308f6cb591..ff8fa20961 100644
--- a/docs/developer/deployment/environment_variables.mdx
+++ b/docs/developer/deployment/environment_variables.mdx
@@ -166,7 +166,7 @@ Optional. When configured, Spree uses [Meilisearch](/integrations/search/meilise
| 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`. |
+| `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:
diff --git a/docs/developer/upgrades/5.6-to-6.0.mdx b/docs/developer/upgrades/5.6-to-6.0.mdx
index a4d3924462..290982c025 100644
--- a/docs/developer/upgrades/5.6-to-6.0.mdx
+++ b/docs/developer/upgrades/5.6-to-6.0.mdx
@@ -47,6 +47,37 @@ Before running `bundle update`, update your `Gemfile`: the Rails admin (`spree_a
gem 'spree_dashboard'
```
+### Check the ports your compose files publish
+
+`spree upgrade` updates gems, packages and the database. It does **not** rewrite `docker-compose.yml` or `docker-compose.dev.yml`, so a project keeps the port bindings it was created with — and the compose files that shipped with spree-starter 5.4.0 through 5.5.1 published Meilisearch, and in the dev compose also Postgres, on every interface:
+
+```yaml
+ postgres:
+ ports:
+ - "${SPREE_DB_PORT:-5433}:5432" # dev compose: passwordless (trust auth) Postgres
+ meilisearch:
+ ports:
+ - "7700:7700" # both composes: Meilisearch with no master key
+```
+
+On a Linux host that is a real exposure, not a theoretical one: Docker's `iptables` rules publish these ports straight past `ufw` or `firewalld`, so `ufw default deny incoming` does nothing for them, and scanners find an open Postgres within minutes. Projects created from 4.x templates published `5432:5432` and `6379:6379` the same way. Bind them to loopback (what spree-starter has done since 5.5.2), or drop the `ports:` entries entirely — the app reaches both services over the compose network:
+
+```yaml
+ postgres:
+ ports:
+ - "127.0.0.1:${SPREE_DB_PORT:-5433}:5432"
+ meilisearch:
+ ports:
+ - "127.0.0.1:${SPREE_MEILISEARCH_PORT:-7700}:7700"
+ redis: # only if the project still runs one
+ ports:
+ - "127.0.0.1:6379:6379"
+```
+
+Either fix isolates the container only on Docker Engine 28.0.1 or newer. Older engines can leak container ports, published on loopback or not published at all, to hosts on the same LAN, so update the engine as part of the same change.
+
+The quick-start compose publishes the app itself as `"${SPREE_PORT:-3000}:3000"`, which is intended — but on an internet-facing host put a proxy in front and don't publish `web` at all. [Published ports and firewalls](/developer/deployment/docker#published-ports-and-firewalls) covers the setup; the EC2 guide shows it with Caddy.
+
### The TypeScript packages share the Spree version
From 6.0, the packages that talk to the Spree API are released with Spree and carry its version: `@spree/[email protected]` is the Store API client for Spree 6.0.0. The same applies to `@spree/admin-sdk`, `@spree/seller-sdk`, `@spree/core`, `@spree/dashboard`, `@spree/dashboard-core`, `@spree/dashboard-ui` and `@spree/seller-dashboard`. `@spree/cli` and `create-spree-app` keep their own versions.