diff --git a/.env.local.example b/.env.local.example
new file mode 100644
index 00000000..af9518e9
--- /dev/null
+++ b/.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
diff --git a/.gitignore b/.gitignore
index 6fb8d4d6..cd66d285 100644
--- a/.gitignore
+++ b/.gitignore
@@ -49,4 +49,5 @@ package-lock.json
 /dist
 /Bruno
 /tsconfig.tsbuildinfo
-/public/generated.css
+/public/generated.css
+/.worktrees
diff --git a/README.md b/README.md
index 7822aa07..0b9cff09 100644
--- a/README.md
+++ b/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:
diff --git a/compose.local.yaml b/compose.local.yaml
new file mode 100644
index 00000000..2a4500d6
--- /dev/null
+++ b/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
diff --git a/docs/local-deploy.md b/docs/local-deploy.md
new file mode 100644
index 00000000..06057704
--- /dev/null
+++ b/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