From 1aa72b6d09c702c3c30304603b5220e161a04b0a Mon Sep 17 00:00:00 2001
From: hahalolo <74804820+RoverKai@users.noreply.github.com>
Date: Tue, 26 May 2026 14:15:48 +0800
Subject: [PATCH] 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
---
 QUICKSTART.md             | 30 ++++++++++++++++++++++++++++--
 README.md                 | 22 +++++++++++++++++++---
 deploy/.env.example       |  6 ++++++
 deploy/README.md          | 19 ++++++++++++++++++-
 deploy/docker-compose.yml |  1 +
 deploy/scripts/install.sh |  3 +++
 6 files changed, 75 insertions(+), 6 deletions(-)

diff --git a/QUICKSTART.md b/QUICKSTART.md
index e5672616f..0985dd95f 100644
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@@ -55,8 +55,24 @@ docker compose version
 
 From the repository root:
 
+1. Change to the deploy directory and copy the environment template:
+
+   ```bash
+   cd deploy
+   cp .env.example .env
+   ```
+
+2. Generate a secure token:
+
+   ```bash
+   openssl rand -hex 32
+   ```
+
+3. Open `.env` in your editor, find `OD_API_TOKEN=`, and paste the generated token there.
+
+Then start the service:
+
 ```bash
-cd deploy
 docker compose up -d
 ```
 
@@ -107,7 +123,13 @@ docker compose down -v
 
 ## Environment Configuration
 
-Create a `deploy/.env` file to override the default configuration:
+Create a `deploy/.env` file to override the default configuration. Start from the provided example:
+
+```bash
+cp deploy/.env.example deploy/.env
+```
+
+Edit `deploy/.env` to set your own token and adjust other values as needed:
 
 ```env
 # Port exposed on the host
@@ -121,6 +143,10 @@ OPEN_DESIGN_ALLOWED_ORIGINS=https://yourdomain.com
 
 # Docker image tag
 OPEN_DESIGN_IMAGE=docker.io/vanjayak/open-design:latest
+
+# Required API token for daemon security
+# Generate one with: openssl rand -hex 32
+OD_API_TOKEN=
 ```
 
 ---
diff --git a/README.md b/README.md
index d61c01951..0052f41a1 100644
--- a/README.md
+++ b/README.md
@@ -338,9 +338,25 @@ docker compose version
 
 #### Start Open Design
 
-```bash id="m9w43w"
-git clone https://github.com/nexu-io/open-design.git
-cd open-design/deploy
+1. Clone the repository, change to the deploy directory, and copy the environment template:
+
+   ```bash
+   git clone https://github.com/nexu-io/open-design.git
+   cd open-design/deploy
+   cp .env.example .env
+   ```
+
+2. Generate a secure token:
+
+   ```bash
+   openssl rand -hex 32
+   ```
+
+3. Open `.env` in your editor, find `OD_API_TOKEN=`, and paste the generated token there.
+
+Then start the service:
+
+```bash
 docker compose up -d
 ```
 
diff --git a/deploy/.env.example b/deploy/.env.example
index 1fc754b03..788be0ce8 100644
--- a/deploy/.env.example
+++ b/deploy/.env.example
@@ -10,9 +10,15 @@ OPEN_DESIGN_PORT=7456
 # domain, public IP, or reverse proxy, e.g. http://203.0.113.10:7456,https://od.example.com.
 OPEN_DESIGN_ALLOWED_ORIGINS=
 
+# REQUIRED. 
+# The daemon binds to 0.0.0.0 inside the container and strictly requires an API token for security.
+# Generate a secure 32-byte hex token by running `openssl rand -hex 32` and paste it below.
+OD_API_TOKEN=
+
 # Container memory limit. The idle service has been verified around 18-22 MiB.
 # Raise this for large exports, concurrent agent runs, or heavy upload workflows.
 OPEN_DESIGN_MEM_LIMIT=384m
 
 # Node.js heap cap inside the container.
 NODE_OPTIONS=--max-old-space-size=192
+
diff --git a/deploy/README.md b/deploy/README.md
index d202d319c..1983779b7 100644
--- a/deploy/README.md
+++ b/deploy/README.md
@@ -6,8 +6,25 @@ separate nginx container.
 
 ## Local compose
 
+Before starting:
+
+1. Copy the environment template:
+
+   ```bash
+   cp .env.example .env
+   ```
+
+2. Generate a secure token:
+
+   ```bash
+   openssl rand -hex 32
+   ```
+
+3. Open `.env` in your editor, find `OD_API_TOKEN=`, and paste the generated token there.
+
+Then pull and start the service:
+
 ```bash
-cd deploy
 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
 ```
diff --git a/deploy/docker-compose.yml b/deploy/docker-compose.yml
index 26fcd4178..c999cd873 100644
--- a/deploy/docker-compose.yml
+++ b/deploy/docker-compose.yml
@@ -15,6 +15,7 @@ services:
       OD_ALLOWED_ORIGINS: ${OPEN_DESIGN_ALLOWED_ORIGINS:-}
       OD_PORT: 7456
       OD_WEB_PORT: ${OPEN_DESIGN_PORT:-7456}
+      OD_API_TOKEN: ${OD_API_TOKEN:?Please run 'openssl rand -hex 32' to generate one, and set it in your .env file.}
     ports:
       - "127.0.0.1:${OPEN_DESIGN_PORT:-7456}:7456"
     volumes:
diff --git a/deploy/scripts/install.sh b/deploy/scripts/install.sh
index 6f0384022..73a91ace6 100755
--- a/deploy/scripts/install.sh
+++ b/deploy/scripts/install.sh
@@ -383,6 +383,8 @@ if [ -f "$ENV_FILE" ]; then
   cp "$ENV_FILE" "$BACKUP"
 fi
 
+GENERATED_TOKEN=$(openssl rand -hex 32 2>/dev/null || od -vAn -N32 -tx1 /dev/urandom | tr -d ' \n' 2>/dev/null)
+
 cat > "$ENV_FILE" << ENVFILE
 # Generated by install.sh on $(date -u +%Y-%m-%dT%H:%M:%SZ)
 OPEN_DESIGN_IMAGE=${IMAGE}
@@ -390,6 +392,7 @@ OPEN_DESIGN_PORT=${PORT}
 OPEN_DESIGN_ALLOWED_ORIGINS=${ALLOWED_ORIGINS}
 OPEN_DESIGN_MEM_LIMIT=${MEM_LIMIT}
 NODE_OPTIONS=--max-old-space-size=192
+OD_API_TOKEN=${GENERATED_TOKEN}
 ENVFILE
 
 ok "Written ${ENV_FILE}"