docs: add local deployment and upgrade guides

.env.local.example

@@ -0,0 +1,11 @@
+CONVERTX_CONTAINER_NAME=convertx
+CONVERTX_PORT=3000
+CONVERTX_DATA_DIR=./data
+CONVERTX_IMAGE=ghcr.io/c4illin/convertx
+JWT_SECRET=change-this-to-a-long-random-string
+HTTP_ALLOWED=true
+AUTO_DELETE_EVERY_N_HOURS=24
+TZ=Asia/Shanghai
+ACCOUNT_REGISTRATION=false
+ALLOW_UNAUTHENTICATED=false
+MAX_CONVERT_PROCESS=0

.gitignore

@@ -49,4 +49,5 @@ package-lock.json
 /dist
 /Bruno
 /tsconfig.tsbuildinfo
-/public/generated.css
+/public/generated.css
+/.worktrees

README.md

@@ -57,6 +57,10 @@ Any missing converter? Open an issue or pull request!
 > [!WARNING]
 > If you can't login, make sure you are accessing the service over localhost or https otherwise set HTTP_ALLOWED=true
 
+For repository-specific local usage and upgrade workflow, see:
+
+- [`docs/local-deploy.md`](docs/local-deploy.md)
+
 ```yml
 # docker-compose.yml
 services:

compose.local.yaml

@@ -0,0 +1,23 @@
+services:
+  convertx:
+    image: ${CONVERTX_IMAGE:-ghcr.io/c4illin/convertx}
+    container_name: ${CONVERTX_CONTAINER_NAME:-convertx}
+    restart: unless-stopped
+    ports:
+      - "${CONVERTX_PORT:-3000}:3000"
+    environment:
+      JWT_SECRET: ${JWT_SECRET:?set JWT_SECRET in .env.local}
+      HTTP_ALLOWED: ${HTTP_ALLOWED:-true}
+      AUTO_DELETE_EVERY_N_HOURS: ${AUTO_DELETE_EVERY_N_HOURS:-24}
+      TZ: ${TZ:-UTC}
+      ACCOUNT_REGISTRATION: ${ACCOUNT_REGISTRATION:-false}
+      ALLOW_UNAUTHENTICATED: ${ALLOW_UNAUTHENTICATED:-false}
+      MAX_CONVERT_PROCESS: ${MAX_CONVERT_PROCESS:-0}
+    volumes:
+      - ${CONVERTX_DATA_DIR:-./data}:/app/data
+    healthcheck:
+      test: ["CMD", "curl", "-fsS", "http://127.0.0.1:3000/healthcheck"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 20s

docs/local-deploy.md

@@ -0,0 +1,70 @@
+# Local Docker Deployment
+
+This repository includes a dedicated Compose file for normal local usage without rebuilding the image from source.
+
+## Why use this instead of `compose.yaml`
+
+- `compose.local.yaml` pulls the published ConvertX image
+- `compose.yaml` builds from the local checkout and is intended for development and testing
+- Keeping them separate makes upgrades easier and avoids accidentally coupling local usage to repository state
+
+## Prerequisites
+
+- Docker Desktop or a compatible Docker Engine
+
+## First-time setup
+
+1. Copy the example environment file:
+
+```bash
+cp .env.local.example .env.local
+```
+
+2. Set a long random `JWT_SECRET` in `.env.local`
+3. Start the service:
+
+```bash
+docker compose --env-file .env.local -f compose.local.yaml up -d
+```
+
+4. Verify the service is healthy:
+
+```bash
+docker compose --env-file .env.local -f compose.local.yaml ps
+curl -fsS http://127.0.0.1:3000/healthcheck
+```
+
+5. Open `http://localhost:3000`
+6. Create the first account before exposing the service to anyone else
+
+## Useful operations
+
+Start or update the container:
+
+```bash
+docker compose --env-file .env.local -f compose.local.yaml up -d
+```
+
+Stop the container:
+
+```bash
+docker compose --env-file .env.local -f compose.local.yaml down
+```
+
+View logs:
+
+```bash
+docker compose --env-file .env.local -f compose.local.yaml logs -f
+```
+
+Restart after changing configuration:
+
+```bash
+docker compose --env-file .env.local -f compose.local.yaml restart
+```
+
+## Notes
+
+- The persistent database and job files are stored in `./data`
+- `HTTP_ALLOWED=true` is appropriate for localhost usage
+- `CONVERTX_IMAGE` defaults to the published release image and can be overridden if you need a different tag