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_REF=ghcr.io/c4illin/convertx@sha256:e1f85be04bbaf8a55ead9261194c3ae0fa0957d303ea537127154860b2552afd
+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

README.md

@@ -57,6 +57,11 @@ 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)
+- [`UPGRADE.md`](UPGRADE.md)
+
 ```yml
 # docker-compose.yml
 services:
@@ -79,8 +84,6 @@ or
 docker run -p 3000:3000 -v ./data:/app/data ghcr.io/c4illin/convertx
 ```
 
-Then visit `http://localhost:3000` in your browser and create your account. Don't leave it unconfigured and open, as anyone can register the first account.
-
 If you get unable to open database file run `chown -R $USER:$USER path` on the path you choose.
 
 ### Environment variables

UPGRADE.md

@@ -0,0 +1,78 @@
+# Upgrading From Upstream
+
+This repository is easiest to maintain long-term if you treat upstream and local customizations separately.
+
+## Recommended remote layout
+
+Use a fork and keep the original project as `upstream`:
+
+```bash
+git remote rename origin upstream
+git remote add origin <your-fork-url>
+git fetch --all --tags
+```
+
+Expected result:
+
+- `origin`: your fork
+- `upstream`: `https://github.com/C4illin/ConvertX.git`
+
+## Keep local changes low-conflict
+
+Prefer keeping local operational changes in additive files instead of editing upstream-heavy files:
+
+- `compose.local.yaml`
+- `.env.local.example`
+- `docs/local-deploy.md`
+- `UPGRADE.md`
+
+That keeps future merges simpler than carrying large changes in `README.md`, `Dockerfile`, or runtime code.
+
+## Upgrade workflow
+
+1. Fetch upstream changes:
+
+```bash
+git fetch upstream --tags
+```
+
+2. Create a dedicated upgrade branch from your mainline:
+
+```bash
+git switch main
+git pull --ff-only origin main
+git switch -c codex/upgrade-convertx-<target-version>
+```
+
+3. Merge the upstream release you want to adopt:
+
+```bash
+git merge upstream/main
+```
+
+If you are tracking a specific release tag, merge or inspect that tag explicitly before continuing.
+
+4. Resolve conflicts, keeping local deployment files unless upstream introduces a better replacement
+5. Decide whether to bump `CONVERTX_IMAGE_REF` in `.env.local.example`
+6. Re-run verification:
+
+```bash
+bun run build
+bun test
+docker compose --env-file .env.local -f compose.local.yaml config
+docker compose --env-file .env.local -f compose.local.yaml up -d
+curl -fsS http://127.0.0.1:3000/healthcheck
+```
+
+7. Smoke-test the UI in a browser and verify at least one conversion path you rely on
+8. Commit the upgrade and open a PR
+
+## When to bump the pinned image reference
+
+Upstream currently documents floating image tags such as `latest` and `main`. For local stability, pin the deployed image by digest and update `CONVERTX_IMAGE_REF` only after:
+
+- you have reviewed upstream release notes
+- the new image starts cleanly
+- your required conversions still work
+
+This keeps rollback simple and makes production state inspectable from the env file.

compose.local.yaml

@@ -0,0 +1,23 @@
+services:
+  convertx:
+    image: ${CONVERTX_IMAGE_REF:-ghcr.io/c4illin/convertx@sha256:e1f85be04bbaf8a55ead9261194c3ae0fa0957d303ea537127154860b2552afd}
+    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,69 @@
+# 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`
+
+## 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
+- The image reference is pinned through `CONVERTX_IMAGE_REF`, using an immutable digest instead of the floating `latest` tag