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
---
title: Docker
description: Build a production Docker image of your Spree project, or run the official prebuilt image.
---
## Building Your Project's Image
Every [create-spree-app](/developer/create-spree-app/quickstart) project builds into a single production image: the web server and background jobs run in one container, and the only dependency is a PostgreSQL database (the [single-node topology](/developer/deployment/quickstart#single-node-vs-distributed)).
If you haven't ejected yet, do that first:
```bash
spree eject
```
This generates the app source — including its production `Dockerfile` — in `server/`. Make your customizations, then build:
```bash
spree build --production # → <project>-spree:latest
spree build --production --tag registry.example.com/my-store:v42
```
Or with plain Docker, from the project root:
```bash
docker build . -f server/Dockerfile -t my-store
```
Both produce the same image — and it's exactly what Render and Railway build from your repository. Migrations run automatically on boot.
## Running the Image
One app container plus Postgres is a complete deployment:
```yaml docker-compose.yml
services:
postgres:
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:
test: pg_isready -h 127.0.0.1 -U postgres
interval: 5s
timeout: 5s
retries: 5
web:
image: my-store # or ghcr.io/spree/spree:latest for the stock image
depends_on:
postgres:
condition: service_healthy
environment:
DATABASE_URL: postgres://postgres@postgres:5432/spree_production
SECRET_KEY_BASE: change-me-to-a-real-secret
# Active Record encryption — generate with `spree encryption init --print`
# or `bin/rails db:encryption:init`; never change them once data is encrypted
ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY: change-me
ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY: change-me
ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT: change-me
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.
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
interval: 10s
timeout: 5s
retries: 10
start_period: 30s
volumes:
postgres_data:
```
Start everything:
```bash
docker compose up -d
```
The database is created and migrated on first boot. The app is available at [http://localhost:3000](http://localhost:3000).
<Note>
PostgreSQL 18 images keep data in a version-specific directory under `/var/lib/postgresql`, so the volume above must be empty on first boot. If you already have a volume with PostgreSQL 17 (or older) data, migrate it first — dump and restore into a fresh PostgreSQL 18 volume, or use `pg_upgrade`.
</Note>
### Scaling out the worker
Background jobs run inside the web container by default. When job load deserves its own process, split it out — same image, no rebuild: set `SOLID_QUEUE_IN_PUMA: "false"` on `web` and add a worker service:
```yaml
worker:
image: my-store
depends_on:
postgres:
condition: service_healthy
environment:
DATABASE_URL: postgres://postgres@postgres:5432/spree_production
SECRET_KEY_BASE: change-me-to-a-real-secret
# the same encryption keys as web
ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY: change-me
ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY: change-me
ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT: change-me
SPREE_HOST: localhost:3000
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 |
| --- | --- | --- |
| `DATABASE_URL` | PostgreSQL connection URL | `postgres://user:pass@host:5432/spree` |
| `SECRET_KEY_BASE` | Secret key for session encryption | Generate with `bin/rails secret` |
| `ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY`, `ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY`, `ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT` | Keys Spree encrypts secrets at rest with — see [Active Record encryption](/developer/deployment/environment_variables#active-record-encryption). Never change them once data is encrypted | Generate with `spree encryption init --print` or `bin/rails db:encryption:init` |
| `SPREE_HOST` | Public host used in generated URLs — image/attachment URLs in API responses, email links | `store.example.com` |
| `SOLID_QUEUE_IN_PUMA` | Run background jobs inside the web container (default `true`); set `false` when running a dedicated worker | `true` |
See [Environment Variables](/developer/deployment/environment_variables) for the full list.
## Official Docker Image
To run Spree without any customizations, pull the prebuilt multi-arch image (`linux/amd64` and `linux/arm64`) published to the GitHub Container Registry on every release:
```bash
docker pull ghcr.io/spree/spree:latest
```
| Tag | Description |
|-----|-------------|
| `latest` | Latest stable release |
| `6.0.0` | Specific version |
Browse all tags on the [GitHub Packages page](https://github.com/spree/spree/pkgs/container/spree). The image drops into the compose file above in place of your custom tag.