BanManagement
diff --git a/‎.env.example‎
Lines changed: 17 additions & 6 deletions b/‎.env.example‎
Lines changed: 17 additions & 6 deletions
diff --git a/‎.github/workflows/build.yaml‎
Lines changed: 124 additions & 0 deletions b/‎.github/workflows/build.yaml‎
Lines changed: 124 additions & 0 deletions
diff --git a/‎.github/workflows/deploy_docker.yaml‎
Lines changed: 11 additions & 2 deletions b/‎.github/workflows/deploy_docker.yaml‎
Lines changed: 11 additions & 2 deletions
diff --git a/‎.gitignore‎
Lines changed: 2 additions & 0 deletions b/‎.gitignore‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎CHECKS‎
Lines changed: 1 addition & 1 deletion b/‎CHECKS‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎Dockerfile‎
Lines changed: 3 additions & 1 deletion b/‎Dockerfile‎
Lines changed: 3 additions & 1 deletion
diff --git a/‎README.md‎
Lines changed: 70 additions & 9 deletions b/‎README.md‎
Lines changed: 70 additions & 9 deletions
@@ -1,5 +1,13 @@
 # BanManager WebUI - Environment Configuration
-# Copy this file to .env and update values as needed
+# Copy this file to .env and update values as needed.
+#
+# You usually don't need to fill this in by hand:
+#   - Docker:  the entrypoint generates missing keys automatically.
+#   - CLI:     run `npx bmwebui setup` for an interactive wizard.
+#   - Web:     start the server with no keys and finish setup at http://your-host:3000/setup
+#
+# To verify your configuration at any time:
+#   npx bmwebui doctor
 
 # Server display name (shown in footer)
 SERVER_FOOTER_NAME=BanManagement
@@ -15,12 +23,15 @@ DB_PASSWORD=password
 DB_NAME=bm_local_dev
 DB_CONNECTION_LIMIT=5
 
-# Security keys (generate unique values for production)
-# Generate with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
-ENCRYPTION_KEY=b097b390a68441cc3bb151dd0171f25c3aabc688c50eeb26dc5e13254b333911
-SESSION_KEY=a73545a5f08d2906e39a4438014200303f9269f3ade9227525ffb141294f1b62
+# Security keys
+# Leave blank to have setup (CLI/Docker/web installer) generate fresh values for you.
+# To generate manually: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+# These MUST be unique 64-character hex strings in production.
+ENCRYPTION_KEY=
+SESSION_KEY=
 
-# Push notification VAPID keys (generate with: npx web-push generate-vapid-keys)
+# Push notification VAPID keys
+# Leave blank to have setup generate them, or run: npx web-push generate-vapid-keys
 NOTIFICATION_VAPID_PUBLIC_KEY=
 NOTIFICATION_VAPID_PRIVATE_KEY=
 
 
@@ -96,12 +96,136 @@ jobs:
           flag-name: run-${{ matrix.test_number }}
           parallel: true
 
+  setup_e2e:
+    runs-on: ubuntu-latest
+    name: Setup wizard E2E
+
+    env:
+      DB_HOST: 127.0.0.1
+      DB_PORT: 3306
+      DB_USER: root
+      DB_PASSWORD: root
+      SETUP_PORT: 3001
+      SETUP_DOTENV_PATH: /tmp/bm-setup-test.env
+      SETUP_DB_NAME: bm_e2e_setup
+      SETUP_BM_DB_NAME: bm_e2e_setup_bm
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Node.js 22
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+      - name: Cache Node.js modules
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-setup-e2e-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-setup-e2e-
+      - run: npm ci
+      - name: Set up MySQL
+        run: |
+          sudo systemctl start mysql.service
+          sleep 5 && mysql -e "ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY '';" -u${{ env.DB_USER }} -p${{ env.DB_PASSWORD }}
+          mysql -e "SET GLOBAL sql_require_primary_key = ON;" -uroot
+      - name: Cypress run (setup wizard)
+        uses: cypress-io/github-action@v6
+        env:
+          DB_HOST: 127.0.0.1
+          DB_PORT: 3306
+          DB_USER: root
+          DB_PASSWORD:
+          SETUP_PORT: 3001
+          SETUP_DOTENV_PATH: /tmp/bm-setup-test.env
+          SETUP_DB_NAME: bm_e2e_setup
+          SETUP_BM_DB_NAME: bm_e2e_setup_bm
+          LOG_LEVEL: warn
+          CYPRESS_setup_db_password: ''
+          CYPRESS_setup_db_host: 127.0.0.1
+          CYPRESS_setup_db_port: '3306'
+          CYPRESS_setup_db_user: root
+          CYPRESS_setup_dotenv_path: /tmp/bm-setup-test.env
+          CYPRESS_setup_db_name: bm_e2e_setup
+        with:
+          install: false
+          start: npm run e2e:setup:server
+          wait-on: "http://127.0.0.1:3001/health"
+          wait-on-timeout: 60
+          command: npm run e2e:setup:run
+
   build_docker:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - run: docker build . # TODO cache
 
+  smoke_docker:
+    name: Docker compose smoke test
+    runs-on: ubuntu-latest
+    needs: build_docker
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build webui image (load locally)
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          load: true
+          tags: banmanagement/webui:smoke
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Start docker compose stack
+        env:
+          MYSQL_ROOT_PASSWORD: rootpassword
+          MYSQL_PASSWORD: webuipassword
+          WEBUI_PORT: 3000
+        run: |
+          # Use the locally built image instead of pulling
+          sed -i 's|image: banmanagement/webui:latest|image: banmanagement/webui:smoke|' docker-compose.prod.yml
+          docker compose -f docker-compose.prod.yml up -d
+
+      - name: Wait for /health to report setup_required
+        env:
+          MYSQL_ROOT_PASSWORD: rootpassword
+          MYSQL_PASSWORD: webuipassword
+          WEBUI_PORT: 3000
+        run: |
+          set -e
+          for attempt in $(seq 1 60); do
+            response=$(curl -fsS http://127.0.0.1:3000/health || true)
+            echo "attempt $attempt: $response"
+            if echo "$response" | grep -q '"status":"setup_required"' || echo "$response" | grep -q '"status":"ok"'; then
+              echo "Health endpoint is responding"
+              exit 0
+            fi
+            sleep 2
+          done
+          echo "Health endpoint never responded"
+          echo "===== docker ps ====="
+          docker ps -a
+          echo "===== webui logs ====="
+          docker logs banmanager-webui 2>&1 | tail -200 || true
+          echo "===== mysql logs ====="
+          docker logs banmanager-webui-mysql 2>&1 | tail -80 || true
+          exit 1
+
+      - name: Confirm setup mode signal
+        run: |
+          curl -fsS http://127.0.0.1:3000/health | tee /tmp/health.json
+          grep -q 'setup_required\|"status":"ok"' /tmp/health.json
+
+      - name: Stop docker compose stack
+        if: always()
+        env:
+          MYSQL_ROOT_PASSWORD: rootpassword
+          MYSQL_PASSWORD: webuipassword
+        run: docker compose -f docker-compose.prod.yml down -v
+
   finish:
     needs: test
     runs-on: ubuntu-latest
 
@@ -13,6 +13,12 @@ jobs:
       - name: Check out the repo
         uses: actions/checkout@v4
 
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
       - name: Log in to Docker Hub
         uses: docker/login-action@v3
         with:
@@ -25,12 +31,15 @@ jobs:
         with:
           images: banmanagement/webui
 
-      - name: Build and push Docker image
+      - name: Build and push multi-platform Docker image
         uses: docker/build-push-action@v6
         with:
           context: .
+          platforms: linux/amd64,linux/arm64
           push: true
           tags: |
             banmanagement/webui:${{ github.sha }}
             banmanagement/webui:latest
-          labels: ${{ steps.meta.outputs.labels }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
@@ -5,6 +5,8 @@ npm-debug.log
 typings*
 .sync
 .env
+.env.*
+!.env.example
 .nyc_output/
 .next
 bundles
 
@@ -1 +1 @@
-/  BanManager-WebUI
+/health  ok
@@ -37,12 +37,14 @@ RUN adduser --system --uid 1001 nextjs
 
 RUN mkdir -p /app/.next/cache/images && chown nextjs:nodejs /app/.next/cache/images
 RUN mkdir -p /app/uploads/documents && chown nextjs:nodejs /app/uploads/documents
+RUN mkdir -p /app/config && chown nextjs:nodejs /app/config
 
 COPY --from=builder --chown=nextjs:nodejs /app ./
 
 VOLUME /app/.next/cache/images
 VOLUME /app/public/images/opengraph/cache
 VOLUME /app/uploads/documents
+VOLUME /app/config
 
 USER nextjs
 
@@ -52,4 +54,4 @@ EXPOSE 3000
 
 ENV PORT 3000
 
-CMD ["node", "server.js"]
+CMD ["node", "docker-entrypoint.js"]
@@ -54,24 +54,85 @@ To learn more about configuration, usage and features of BanManager, take a look
 
 ## Installation (Production)
 
-For deploying BanManager WebUI on your own server, see the **[full installation guide](https://banmanagement.com/docs/webui/install)**.
+Pick the path that matches your environment. Each one ends with a working WebUI you can sign in to.
+
+For more depth (BanManager plugin install, advanced topics), see the **[full installation guide](https://banmanagement.com/docs/webui/install)**.
 
 ### Requirements
 
-- [Node.js](https://nodejs.org/) LTS (v20 or v22)
-- MySQL v5+ or MariaDB v10+
-- Minecraft server with [BanManager](https://github.com/BanManagement/BanManager) & [BanManager-WebEnhancer](https://ci.frostcast.net/job/BanManager-WebEnhancer/) plugins configured to [use MySQL or MariaDB](https://banmanagement.com/docs/banmanager/install#setup-shared-database-optional)
+- MySQL v5+ or MariaDB v10+ (shared with the BanManager plugin)
+- A Minecraft server with [BanManager](https://github.com/BanManagement/BanManager) & [BanManager-WebEnhancer](https://ci.frostcast.net/job/BanManager-WebEnhancer/) configured to [use MySQL or MariaDB](https://banmanagement.com/docs/banmanager/install#setup-shared-database-optional)
+- For non-Docker installs: [Node.js](https://nodejs.org/) LTS (v20 or v22)
+
+### Path A — Docker Compose (recommended)
+
+Includes the WebUI and a MySQL database in one command. Already have MySQL? Use [`docker-compose.prod-no-db.yml`](docker-compose.prod-no-db.yml) instead.
+
+```bash
+curl -O https://raw.githubusercontent.com/BanManagement/BanManager-WebUI/master/docker-compose.prod.yml
+
+cat > .env <<'EOF'
+MYSQL_ROOT_PASSWORD=$(openssl rand -hex 24)
+MYSQL_PASSWORD=$(openssl rand -hex 24)
+EOF
+
+docker compose -f docker-compose.prod.yml up -d
+```
+
+The Compose file refuses to start without `MYSQL_ROOT_PASSWORD` and `MYSQL_PASSWORD` set — generate long random values (the snippet above does this for you) and keep them in a `.env` file alongside the compose file. The container generates encryption/session/VAPID keys, runs migrations, and persists state to a `webui_config` volume on first boot. Open `http://your-host:3000/setup` to finish setup in your browser, or attach a shell and run `docker compose exec webui npx bmwebui setup` for the CLI wizard.
+
+To check things look right at any time:
+
+```bash
+docker compose exec webui npx bmwebui doctor
+```
 
-### Quick Install
+### Path B — Web installer (any host)
+
+Useful if you want a one-shot install with no terminal interaction after the server is up.
 
 ```bash
 git clone https://github.com/BanManagement/BanManager-WebUI.git
 cd BanManager-WebUI
-npm ci --production
-npm run setup
+npm ci --omit=dev
+npm run build
+node server.js   # starts in setup mode if no .env exists yet
 ```
 
-The setup wizard will guide you through configuring your database connection and creating an admin account.
+Then visit `http://your-host:3000/setup` and follow the wizard. The web installer writes a `.env` file, runs migrations, and creates the first admin account. After it finishes, restart the server (`Ctrl+C`, `node server.js`).
+
+> **⚠ Security model.** The setup endpoint is open by default — whoever loads `/setup` first becomes the admin (same model as WordPress/Ghost). If your install host is reachable from the internet, set `SETUP_TOKEN=$(openssl rand -hex 24)` before starting and share that token only with the person doing the install. The setup screen will require it as the first step. Once an admin user exists the setup routes return 404.
+>
+> **Behind a reverse proxy?** Set `TRUST_PROXY=true` so the WebUI uses `X-Forwarded-For` / `X-Forwarded-Proto` to detect the real client IP and HTTPS status. Without it, every request looks like it came from `127.0.0.1` and the "you're on a secure local connection" banner can be misleading.
+
+### Path C — CLI wizard (terminal-only)
+
+Best when you have shell access and want everything done before the server starts.
+
+```bash
+git clone https://github.com/BanManagement/BanManager-WebUI.git
+cd BanManager-WebUI
+npm ci --omit=dev
+npm run setup       # interactive wizard, writes .env
+npm run build
+npm start
+```
+
+The wizard auto-detects database settings and the console UUID from your BanManager `plugins/BanManager` folder when it can.
+
+### Verify and run as a service
+
+After any path:
+
+- `npx bmwebui doctor` — runs preflight checks (env, DB, migrations, admin user, plugin tables) and tells you exactly what's wrong if anything is.
+- `npx bmwebui setup systemd` — registers the WebUI as a `systemd` service.
+- `npx bmwebui setup nginx` / `setup caddy` / `setup apache` — drops in a reverse-proxy template for your web server of choice (existing nginx setups are unchanged).
+
+Need to add another account later?
+
+```bash
+npx bmwebui account create
+```
 
 ---
 
@@ -137,7 +198,7 @@ Copy `.env.example` to `.env` and adjust as needed. Key variables:
 
 - `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME` - Database connection
 - `ADMIN_USERNAME`, `ADMIN_PASSWORD` - Admin account credentials (also used by Cypress)
-- `ENCRYPTION_KEY`, `SESSION_KEY` - Security keys (generate unique values for production)
+- `ENCRYPTION_KEY`, `SESSION_KEY` - Security keys (leave blank and `npm run dev:setup` will generate + persist them, or set your own)
 
 ### Resetting the Database