mirror of https://github.com/nexu-io/open-design.git synced 2026-06-01 03:14:35 +07:00

fix(docker): fix container startup crash due to missing OD_API_TOKEN (#2928 )

* fix(docker): fix container startup crash due to missing OD_API_TOKEN

* fix(docker): forward OD_API_TOKEN to fix docker container boot loop

* fix(docker): enforce non-empty OD_API_TOKEN for docker-compose

* fix(deploy): automate OD_API_TOKEN generation in installer and close compose loop

* docs(readme): guide manual deployment users to configure OD_API_TOKEN

* docs(readme): align working directory paths for manual deployment instructions

* docs(readme): align working directory paths for manual deployment instructions

* docs(readme): restore git clone context for first-time users

2026-05-26 06:15:48 +00:00

4.8 KiB

Raw Blame History

Docker deployment

This deployment ships Open Design as a single Alpine-based runtime image. The daemon serves both the API and the built Next.js static export, so there is no separate nginx container.

Local compose

Before starting:

Copy the environment template:
```
cp .env.example .env
```
Generate a secure token:
```
openssl rand -hex 32
```
Open .env in your editor, find OD_API_TOKEN=, and paste the generated token there.

Then pull and start the service:

OPEN_DESIGN_IMAGE=docker.io/vanjayak/open-design:latest docker compose pull
OPEN_DESIGN_IMAGE=docker.io/vanjayak/open-design:latest docker compose up -d --no-build

Defaults:

Host port: 127.0.0.1:7456 (OPEN_DESIGN_PORT=8080 to publish on 127.0.0.1:8080)
Runtime data volume: open_design_data mounted at /app/.od
Node heap cap: --max-old-space-size=192
Compose memory cap: 384m (OPEN_DESIGN_MEM_LIMIT=256m to override)

Do not publish the daemon directly on a public or shared LAN interface. The API is unauthenticated for non-browser clients, so remote deployments should keep Compose bound to localhost and put an authenticated reverse proxy, SSH tunnel, or VPN in front of it.

When exposing the service through an authenticated public IP, domain, or reverse proxy, set OPEN_DESIGN_ALLOWED_ORIGINS to the browser origins that should be allowed to call /api:

OPEN_DESIGN_ALLOWED_ORIGINS=https://od.example.com,http://203.0.113.10:7456 docker compose up -d --no-build

Pin a specific published image with a digest instead of the mutable latest tag:

OPEN_DESIGN_IMAGE=docker.io/vanjayak/open-design@sha256:<digest> docker compose up -d --no-build

The image intentionally does not bundle Claude/Codex/Gemini CLI binaries. Keep those outside the image, or build a separate private runtime layer if a server deployment needs local code-agent CLIs installed in the container.

Publish to Docker Hub

deploy/scripts/publish-images.sh --image_tag latest

Useful overrides:

IMAGE_NAMESPACE=your-dockerhub-user deploy/scripts/publish-images.sh --arch arm64
deploy/scripts/publish-images.sh --image docker.io/your-user/open-design:0.1.0

The script defaults to:

docker.io/vanjayak/open-design:<tag>
linux/amd64,linux/arm64
skopeo push strategy with Docker credentials read from ~/.docker/config.json
preloading base images through skopeo to reduce Docker Hub pull flakiness

If 127.0.0.1:7890 is available and no proxy is already set, the script uses it for registry access and passes host.docker.internal:7890 into Docker builds. The host-gateway alias is only added for builds that need this local proxy mapping.

Colima swap helper for Apple Silicon

deploy/scripts/prepare-colima-build-swap.sh is for manual Docker image publishing from an Apple Silicon macOS host that uses Colima as the Docker VM. The helper is intentionally Apple Silicon-only because the failure mode it covers is local arm64 Colima builds exhausting a small Linux VM while preparing multi-arch images. It exits before touching Colima on non-macOS or non-Apple-Silicon hosts.

Low-memory Colima VMs can run out of RAM during multi-arch image builds. The helper checks the VM memory and swap status, then creates and enables a temporary swap file only when the VM has no swap and less than 4 GiB of RAM. The 4 GiB threshold is a conservative default for short-lived manual publishes on small Colima profiles; raise COLIMA_BUILD_SWAP_MEMORY_THRESHOLD_KIB if larger builds still OOM, or lower it if you only want swap for very small VMs.

Prefer increasing the Colima VM memory (colima start --memory <GiB> or the profile config) when you want a persistent build machine. Use this helper when you need a temporary, reversible boost for one manual publish without resizing or recreating the VM.

Run it before a manual publish if Docker builds fail with out-of-memory errors, or if status shows a small Colima VM with no swap. The swap remains active until cleanup or VM restart, so use a shell trap for one-off sessions:

deploy/scripts/prepare-colima-build-swap.sh status
deploy/scripts/prepare-colima-build-swap.sh
trap 'deploy/scripts/prepare-colima-build-swap.sh cleanup' EXIT
deploy/scripts/publish-images.sh --image_tag latest