diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..04b134d
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,32 @@
+# --- HangmanLab backend / frontend ---
+BACKEND_PORT=8000
+FRONTEND_PORT=80
+
+# --- MySQL (shared by hangmanlab-backend and HarborForge) ---
+DB_PORT=3306
+DB_NAME=hangmanlab
+DB_USER=hangmanlab
+DB_PASSWORD=change_me
+MYSQL_ROOT_PASSWORD=change_me_root
+
+# --- HarborForge ---
+HF_BACKEND_PORT=8001
+HF_FRONTEND_PORT=3000
+HF_FRONTEND_DEV_MODE=0
+HF_SECRET_KEY=change_me_in_production
+HF_LOG_LEVEL=INFO
+
+# Database name used by HarborForge (created automatically by hf_db_init on every up).
+HF_DB_NAME=harborforge
+
+# Browser-facing origin of the HarborForge frontend. Used as the AbstractWizard
+# CORS allow-list. Must match the scheme/host/port the user types in their
+# browser. Examples:
+#   http://localhost:3000
+#   https://harborforge.example.com
+# Multiple origins can be comma-separated.
+HF_FRONTEND_HOST=http://localhost:3000
+
+# AbstractWizard SSH-tunnel port (server-side bind). The setup wizard in the
+# browser will ask the user to enter the matching local port.
+WIZARD_PORT=8080
diff --git a/docker-compose.yml b/docker-compose.yml
index 225dd1f..c74906c 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -37,6 +37,29 @@ services:
       - mysql_data:/var/lib/mysql
     networks:
       - app-network
+    healthcheck:
+      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-p${MYSQL_ROOT_PASSWORD}"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 20s
+
+  hf_db_init:
+    image: mysql:8.0
+    restart: "no"
+    environment:
+      MYSQL_HOST: mysql
+      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
+      DB_USER: ${DB_USER}
+      HF_DB_NAME: ${HF_DB_NAME:-harborforge}
+    volumes:
+      - ./mysql-init/10-harborforge.sh:/init/10-harborforge.sh:ro
+    entrypoint: ["/bin/sh", "/init/10-harborforge.sh"]
+    depends_on:
+      mysql:
+        condition: service_healthy
+    networks:
+      - app-network
 
   hf_backend:
     image: git.hangman-lab.top/zhi/harborforge-backend:multi-stage
@@ -50,9 +73,10 @@ services:
       CONFIG_FILE: harborforge.json
       SECRET_KEY: ${HF_SECRET_KEY:-change_me_in_production}
       LOG_LEVEL: ${HF_LOG_LEVEL:-INFO}
+      DATABASE_URL: mysql+pymysql://${DB_USER}:${DB_PASSWORD}@mysql:3306/${HF_DB_NAME:-harborforge}
     depends_on:
-      mysql:
-        condition: service_healthy
+      hf_db_init:
+        condition: service_completed_successfully
     networks:
       - app-network
 
@@ -66,7 +90,7 @@ services:
       CONFIG_DIR: /config
       LISTEN_ADDR: "0.0.0.0:8080"
       MAX_BACKUPS: "5"
-      CORS_ORIGINS: http://hf_frontend:${HF_FRONTEND_PORT:-3000},http://127.0.0.1:${HF_FRONTEND_PORT:-3000},http://localhost:${HF_FRONTEND_PORT:-3000}
+      CORS_ORIGINS: ${HF_FRONTEND_HOST}
     networks:
       - app-network
 
@@ -75,12 +99,11 @@ services:
     ports:
       - "$HF_FRONTEND_PORT:3000"
     environment:
-      VITE_API_BASE: http://hf_backend:${HF_BACKEND_PORT:-8000}
-      VITE_WIZARD_PORT: ${WIZARD_PORT:-8082}
       FRONTEND_DEV_MODE: ${HF_FRONTEND_DEV_MODE:-0}
       NODE_ENV: production
     depends_on:
       - wizard
+      - hf_backend
     networks:
       - app-network
 
diff --git a/mysql-init/10-harborforge.sh b/mysql-init/10-harborforge.sh
new file mode 100755
index 0000000..9a08af4
--- /dev/null
+++ b/mysql-init/10-harborforge.sh
@@ -0,0 +1,22 @@
+#!/bin/sh
+# Idempotent HarborForge DB bootstrap. Runs on every `compose up` via the
+# hf_db_init sidecar service: waits for mysql to accept connections, then
+# ensures the HarborForge database exists and the shared app user can use it.
+set -e
+
+HF_DB_NAME="${HF_DB_NAME:-harborforge}"
+MYSQL_HOST="${MYSQL_HOST:-mysql}"
+
+echo "hf_db_init: waiting for mysql at ${MYSQL_HOST}..."
+until mysql -h"${MYSQL_HOST}" -uroot -p"${MYSQL_ROOT_PASSWORD}" -e "SELECT 1" >/dev/null 2>&1; do
+  sleep 2
+done
+
+echo "hf_db_init: ensuring database '${HF_DB_NAME}' exists and granting access to '${DB_USER}'"
+mysql -h"${MYSQL_HOST}" -uroot -p"${MYSQL_ROOT_PASSWORD}" <<EOSQL
+CREATE DATABASE IF NOT EXISTS \`${HF_DB_NAME}\` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+GRANT ALL PRIVILEGES ON \`${HF_DB_NAME}\`.* TO '${DB_USER}'@'%';
+FLUSH PRIVILEGES;
+EOSQL
+
+echo "hf_db_init: done"