docker compose version
# 实测输出：
# Docker Compose version v5.6.1

ss -ltn | grep 8140 || echo 'port 8140 free'
# 实测输出（空闲时）：
# port 8140 free

mkdir -p /opt/puter/caddy && cd /opt/puter
wget -O docker-compose.yml https://raw.githubusercontent.com/HeyPuter/puter/main/install/docker-compose.yml
wget -O caddy/Caddyfile https://raw.githubusercontent.com/HeyPuter/puter/main/install/caddy/Caddyfile
# 实测输出（wget 两行进度条省略，退出码均为 0）

name: puter-26.10.1-stack

services:
  valkey:
    image: valkey/valkey:8-alpine
    container_name: puter-26.10.1-valkey
    restart: unless-stopped
    command:
      - sh
      - -c
      - |
        valkey-server \
          --port 6379 \
          --cluster-enabled yes \
          --cluster-config-file /data/nodes.conf \
          --cluster-node-timeout 5000 \
          --cluster-require-full-coverage no \
          --cluster-announce-ip valkey \
          --cluster-announce-port 6379 \
          --cluster-announce-bus-port 16379 \
          --appendonly yes \
          --save "60 1" &
        SERVER_PID=$$!
        until valkey-cli -p 6379 PING > /dev/null 2>&1; do sleep 0.5; done
        if ! valkey-cli -p 6379 CLUSTER NODES | grep -q '0-16383'; then
          valkey-cli -p 6379 CLUSTER ADDSLOTSRANGE 0 16383
        fi
        wait $$SERVER_PID
    volumes:
      - ./puter/data/valkey:/data:z
    healthcheck:
      test: ["CMD-SHELL", "valkey-cli -p 6379 cluster info | grep -q cluster_state:ok"]
      interval: 5s
      timeout: 3s
      retries: 20
      start_period: 10s

  mariadb:
    image: mariadb:11
    container_name: puter-26.10.1-mariadb
    restart: unless-stopped
    environment:
      MARIADB_ROOT_PASSWORD: ${MARIADB_ROOT_PASSWORD}
      MARIADB_DATABASE: ${MARIADB_DATABASE:-puter}
      MARIADB_USER: ${MARIADB_USER:-puter}
      MARIADB_PASSWORD: ${MARIADB_PASSWORD}
    volumes:
      - ./puter/data/mariadb:/var/lib/mysql:z
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 5s
      timeout: 5s
      retries: 20
      start_period: 30s

  dynamo:
    image: amazon/dynamodb-local:latest
    container_name: puter-26.10.1-dynamo
    restart: unless-stopped
    user: "1000:1000"
    working_dir: /home/dynamodblocal
    command: ["-jar", "DynamoDBLocal.jar", "-sharedDb", "-dbPath", "/home/dynamodblocal/data"]
    volumes:
      - ./puter/data/dynamo:/home/dynamodblocal/data:z

  s3:
    image: rustfs/rustfs:latest
    container_name: puter-26.10.1-s3
    restart: unless-stopped
    environment:
      RUSTFS_ACCESS_KEY: ${S3_ACCESS_KEY:-puter}
      RUSTFS_SECRET_KEY: ${S3_SECRET_KEY}
    volumes:
      - ./puter/data/s3:/data:z
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- --tries=1 --timeout=2 http://localhost:9000/health || exit 1"]
      interval: 5s
      timeout: 3s
      retries: 20
      start_period: 5s

  s3-init:
    image: amazon/aws-cli:latest
    container_name: puter-26.10.1-s3-init
    depends_on:
      s3:
        condition: service_healthy
    environment:
      AWS_ACCESS_KEY_ID: ${S3_ACCESS_KEY:-puter}
      AWS_SECRET_ACCESS_KEY: ${S3_SECRET_KEY}
      AWS_DEFAULT_REGION: us-east-1
    entrypoint:
      - /bin/sh
      - -c
      - |
        set -e
        endpoint=http://s3:9000
        bucket=${S3_BUCKET:-puter-local}
        if aws --endpoint-url "$$endpoint" s3api head-bucket --bucket "$$bucket" 2>/dev/null; then
          echo "bucket $$bucket already exists"
        else
          echo "creating bucket $$bucket"
          aws --endpoint-url "$$endpoint" s3 mb "s3://$$bucket"
        fi
        cat > /tmp/cors.json <<'EOF'
        {
          "CORSRules": [
            {
              "AllowedOrigins": ["*"],
              "AllowedMethods": ["GET", "HEAD", "PUT", "POST", "DELETE"],
              "AllowedHeaders": ["*"],
              "ExposeHeaders": ["ETag", "x-amz-request-id"],
              "MaxAgeSeconds": 3600
            }
          ]
        }
        EOF
        aws --endpoint-url "$$endpoint" s3api put-bucket-cors \
          --bucket "$$bucket" --cors-configuration file:///tmp/cors.json
        echo "bucket CORS configured"
    restart: "no"

  puter:
    image: puter-26.10.1-fixed:local
    pull_policy: never
    container_name: puter-26.10.1-app
    restart: unless-stopped
    depends_on:
      valkey:
        condition: service_healthy
      mariadb:
        condition: service_healthy
      dynamo:
        condition: service_started
      s3-init:
        condition: service_completed_successfully
    expose:
      - "4100"
    environment:
      PUID: 1000
      PGID: 1000
    volumes:
      - ./puter/config:/etc/puter:z
      - ./puter/data/puter:/var/puter:z
    healthcheck:
      test: wget --no-verbose --tries=1 --spider http://localhost:4100/ || exit 1
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 30s

  caddy:
    image: caddy:2.11-alpine
    container_name: puter-26.10.1-caddy
    restart: unless-stopped
    depends_on:
      puter:
        condition: service_started
    ports:
      - "${HTTP_PORT:-80}:80"
    volumes:
      - ./caddy/Caddyfile:/etc/caddy/Caddyfile:ro,z
      - ./puter/tls:/etc/caddy/tls:ro,z
      - ./puter/data/caddy:/data:z
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- --tries=1 --timeout=2 http://127.0.0.1:2019/config/ >/dev/null || exit 1"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 5s

networks:
  default:
    name: puter-26.10.1-net
    ipam:
      config:
        - subnet: 10.89.65.0/24

MARIADB_ROOT_PASSWORD=$(openssl rand -hex 32)
MARIADB_PASSWORD=$(openssl rand -hex 32)
S3_SECRET_KEY=$(openssl rand -hex 32)
JWT_SECRET_V2=$(openssl rand -hex 64)
URL_SIGNATURE_SECRET=$(openssl rand -hex 64)

cat > .env <<EOF
HTTP_PORT=8140
MARIADB_ROOT_PASSWORD=$MARIADB_ROOT_PASSWORD
MARIADB_DATABASE=puter
MARIADB_USER=puter
MARIADB_PASSWORD=$MARIADB_PASSWORD
S3_ACCESS_KEY=puter
S3_SECRET_KEY=$S3_SECRET_KEY
S3_BUCKET=puter-local
EOF

mkdir -p caddy puter/config puter/data puter/tls

cat > puter/config/config.json <<EOF
{
    "domain": "puter.localhost",
    "protocol": "http",
    "pub_port": 8140,
    "env": "prod",

    "static_hosting_domain": "site.puter.localhost",
    "static_hosting_domain_alt": "host.puter.localhost",
    "private_app_hosting_domain": "app.puter.localhost",
    "private_app_hosting_domain_alt": "dev.puter.localhost",

    "jwt_secret_v2": "$JWT_SECRET_V2",
    "url_signature_secret": "$URL_SIGNATURE_SECRET",

    "database": {
        "engine": "mysql",
        "host": "mariadb",
        "port": 3306,
        "user": "puter",
        "password": "$MARIADB_PASSWORD",
        "database": "puter",
        "migrationPaths": ["/opt/puter/dist/src/backend/clients/database/migrations/mysql"]
    },

    "redis": {
        "startupNodes": [{ "host": "valkey", "port": 6379 }],
        "tls": false
    },

    "dynamo": {
        "endpoint": "http://dynamo:8000",
        "bootstrapTables": true,
        "aws": {
            "access_key": "fake",
            "secret_key": "fake",
            "region": "us-east-1"
        }
    },

    "s3": {
        "s3Config": {
            "endpoint": "http://s3:9000",
            "publicEndpoint": "http://s3.puter.localhost",
            "accessKeyId": "puter",
            "secretAccessKey": "$S3_SECRET_KEY",
            "region": "us-east-1",
            "forcePathStyle": true
        }
    },
    "s3_bucket": "puter-local",
    "s3_region": "us-east-1",

    "providers": {
        "ollama": { "enabled": false }
    },

    "meteringEnforcement": {
        "subscriptions": false
    },

    "trust_proxy": 1
}
EOF
chmod 600 .env

cat > Dockerfile.patch <<'EOF'
FROM ghcr.io/heyputer/puter:main
# 修复 26.10.1 官方镜像缺失 sharp 原生依赖导致启动崩溃的问题
RUN cd /opt/puter && npm install sharp --no-audit --no-fund
EOF

docker build -f Dockerfile.patch -t puter-26.10.1-fixed:local .

[+] Building 96.7s (7/7) FINISHED
 => [internal] load build definition from Dockerfile.patch
 => [1/3] FROM ghcr.io/heyputer/puter:main
 => [2/3] RUN cd /opt/puter && npm install sharp --no-audit --no-fund
 => [3/3] exporting to image
 => => naming to docker.io/library/puter-26.10.1-fixed:local

mkdir -p puter/data/{mariadb,dynamo,s3,valkey,caddy,puter}
chown -R 1000:1000 puter/data/dynamo

docker compose up -d
# 实测输出：
# [+] Running 8/8
#  ✔ Network puter-26.10.1-net          Created
#  ✔ Container puter-26.10.1-valkey     Healthy
#  ✔ Container puter-26.10.1-mariadb    Healthy
#  ✔ Container puter-26.10.1-s3         Healthy
#  ✔ Container puter-26.10.1-s3-init    Exited
#  ✔ Container puter-26.10.1-dynamo     Started
#  ✔ Container puter-26.10.1-app        Started
#  ✔ Container puter-26.10.1-caddy      Started

docker compose logs -f puter

[config] defaults from /opt/puter/config.default.json
[config] override from /etc/puter/config.json
connecting to redis from config
[redis] cluster transport connected
[redis] cluster ready
[mysql] connected to primary
[mysql] running migrations from /opt/puter/dist/src/backend/clients/database/migrations/mysql: 49 file(s)
[mysql] applied mysql_mig_1.sql (501 statements)
[mysql] applied mysql_mig_2.sql (10 statements)
...
[mysql] applied mysql_mig_48.sql (1 statements)
[mysql] applied mysql_mig_49.sql (6 statements)
[email] no email transport configured — send() will fail until configured
[s3] configured with remote endpoint
[prelude] no apiKey configured — SMS phone verification is disabled
************************************************************
* Puter is now live at: http://puter.localhost:8140
************************************************************
PuterServer has fully booted.

# 1. 全部服务健康（s3-init 为正常退出态）
docker compose ps --format 'table {{.Name}}\t{{.Image}}\t{{.Status}}'
# 实测输出：
# NAME                    IMAGE                          STATUS
# puter-26.10.1-app       puter-26.10.1-fixed:local      Up 12 minutes (healthy)
# puter-26.10.1-caddy     caddy:2.11-alpine              Up 35 minutes (healthy)
# puter-26.10.1-dynamo    amazon/dynamodb-local:latest   Up 12 minutes
# puter-26.10.1-mariadb   mariadb:11                     Up 35 minutes (healthy)
# puter-26.10.1-s3        rustfs/rustfs:latest           Up 35 minutes (healthy)
# puter-26.10.1-valkey    valkey/valkey:8-alpine         Up 35 minutes (healthy)

# 2. Web 入口返回 200
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8140/
# 实测输出：
# 200

# 3. 数据库 46 张业务表就绪
docker exec puter-26.10.1-mariadb sh -c "mariadb -uputer -p\$MARIADB_PASSWORD puter -e 'SHOW TABLES;'" | wc -l
# 实测输出：
# 46

# 注册 admin 账号（演示口令 q1w2e3r4）
curl -s -X POST http://localhost:8140/signup \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","email":"admin@puter.localhost","password":"q1w2e3r4"}'
# 实测输出（首次注册成功时返回用户对象；用户名已存在时返回）：
# {"error":"This username is not available.","message":"This username is not available.","code":"username_already_in_use"}

# 登录拿会话令牌
curl -s -X POST http://localhost:8140/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}' -o /tmp/login.json -w '%{http_code}\n'
# 实测输出：
# 200
python3 -c "import json;d=json.load(open('/tmp/login.json'));print(sorted(d.keys()),d['next_step'])"
# 实测输出：
# ['next_step', 'proceed', 'token', 'user'] complete

puter/data/:
caddy
dynamo
mariadb
puter
s3
valkey

docker compose restart puter
# 主应用重启约 30~60 秒（健康检查 start_period 30s），期间 Web 不可访问

# 主应用（前置：mariadb/valkey/dynamo/s3 已按各自官方镜像启动且网络互通）
docker run -d --name puter-26.10.1-app \
  --network puter-26.10.1-net \
  -e PUID=1000 -e PGID=1000 \
  -v /opt/puter/puter/config:/etc/puter \
  -v /opt/puter/puter/data/puter:/var/puter \
  puter-26.10.1-fixed:local

# Caddy 反代（对外 8140 → 容器 80）
docker run -d --name puter-26.10.1-caddy \
  --network puter-26.10.1-net \
  -p 8140:80 \
  -v /opt/puter/caddy/Caddyfile:/etc/caddy/Caddyfile:ro \
  -v /opt/puter/puter/data/caddy:/data \
  caddy:2.11-alpine

cd /opt/puter

# 查看整体状态
docker compose ps
# 实测输出（六服务一 exited，详见 4.5 节）

# 跟踪/查看主应用日志
docker compose logs -f puter
docker compose logs --since 10m puter

# 重启单个服务（改 config.json 后）
docker compose restart puter

# 整栈停止（保数据）与再启动
docker compose stop
docker compose up -d

# 整栈更新（拉官方新镜像后重建主应用）
docker compose pull puter
docker compose up -d puter

node:internal/modules/cjs/loader:1145
  throw err;
  ^
Error: Cannot find module 'sharp'
Require stack:
- /opt/puter/dist/src/backend/src/services/drivers/thumb.js
    at Module._resolveFilename (node:internal/modules/cjs/loader:1142:15)

uncaughtException (unhandledRejection) Error [TimeoutError]: Connection timed out after 5000 ms
    at ClientRequest.<anonymous> (/opt/puter/node_modules/@smithy/node-http-handler/dist-cjs/index.js:97:26)
...
  '$metadata': { attempts: 3, totalRetryDelay: 74 }

WARNING: [sqlite] cannot open DB[436]: com.almworks.sqlite4java.SQLiteException: [14] unable to open database file
SEVERE: [sqlite] SQLiteQueue[shared-local-instance.db]: error running job queue