From f5348133cd7ceec932e93cb4f52fa596df374d04 Mon Sep 17 00:00:00 2001 From: JW Date: Fri, 27 Mar 2026 12:51:42 +0800 Subject: [PATCH] docs: add local deployment and upgrade guides --- .env.local.example | 11 +++++++ README.md | 7 ++-- UPGRADE.md | 78 ++++++++++++++++++++++++++++++++++++++++++++ compose.local.yaml | 23 +++++++++++++ docs/local-deploy.md | 69 +++++++++++++++++++++++++++++++++++++++ 5 files changed, 186 insertions(+), 2 deletions(-) create mode 100644 .env.local.example create mode 100644 UPGRADE.md create mode 100644 compose.local.yaml create mode 100644 docs/local-deploy.md diff --git a/.env.local.example b/.env.local.example new file mode 100644 index 0000000..aa66c23 --- /dev/null +++ b/.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 diff --git a/README.md b/README.md index 7822aa0..4e2d157 100644 --- a/README.md +++ b/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 diff --git a/UPGRADE.md b/UPGRADE.md new file mode 100644 index 0000000..57558a2 --- /dev/null +++ b/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 +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- +``` + +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. diff --git a/compose.local.yaml b/compose.local.yaml new file mode 100644 index 0000000..d6fca3d --- /dev/null +++ b/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 diff --git a/docs/local-deploy.md b/docs/local-deploy.md new file mode 100644 index 0000000..87abd1b --- /dev/null +++ b/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