From f610ca1e06e9d7dfcd799068b41438dd1f92376d Mon Sep 17 00:00:00 2001 From: JW Date: Fri, 27 Mar 2026 12:32:09 +0800 Subject: [PATCH 1/3] chore: ignore local worktrees --- .gitignore | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) 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 From f5348133cd7ceec932e93cb4f52fa596df374d04 Mon Sep 17 00:00:00 2001 From: JW Date: Fri, 27 Mar 2026 12:51:42 +0800 Subject: [PATCH 2/3] 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 00000000..aa66c234 --- /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 7822aa07..4e2d1570 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 00000000..57558a29 --- /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 00000000..d6fca3de --- /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 00000000..87abd1b0 --- /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 From 49f28bd30ed0ba32754f94fd8efcd5ddd3d3de68 Mon Sep 17 00:00:00 2001 From: JW Date: Fri, 27 Mar 2026 13:43:42 +0800 Subject: [PATCH 3/3] docs: narrow local deployment guidance --- .env.local.example | 2 +- README.md | 3 +- UPGRADE.md | 78 -------------------------------------------- compose.local.yaml | 2 +- docs/local-deploy.md | 3 +- 5 files changed, 6 insertions(+), 82 deletions(-) delete mode 100644 UPGRADE.md diff --git a/.env.local.example b/.env.local.example index aa66c234..af9518e9 100644 --- a/.env.local.example +++ b/.env.local.example @@ -1,7 +1,7 @@ CONVERTX_CONTAINER_NAME=convertx CONVERTX_PORT=3000 CONVERTX_DATA_DIR=./data -CONVERTX_IMAGE_REF=ghcr.io/c4illin/convertx@sha256:e1f85be04bbaf8a55ead9261194c3ae0fa0957d303ea537127154860b2552afd +CONVERTX_IMAGE=ghcr.io/c4illin/convertx JWT_SECRET=change-this-to-a-long-random-string HTTP_ALLOWED=true AUTO_DELETE_EVERY_N_HOURS=24 diff --git a/README.md b/README.md index 4e2d1570..0b9cff09 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,6 @@ Any missing converter? Open an issue or pull request! 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 @@ -84,6 +83,8 @@ 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 deleted file mode 100644 index 57558a29..00000000 --- a/UPGRADE.md +++ /dev/null @@ -1,78 +0,0 @@ -# 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 index d6fca3de..2a4500d6 100644 --- a/compose.local.yaml +++ b/compose.local.yaml @@ -1,6 +1,6 @@ services: convertx: - image: ${CONVERTX_IMAGE_REF:-ghcr.io/c4illin/convertx@sha256:e1f85be04bbaf8a55ead9261194c3ae0fa0957d303ea537127154860b2552afd} + image: ${CONVERTX_IMAGE:-ghcr.io/c4illin/convertx} container_name: ${CONVERTX_CONTAINER_NAME:-convertx} restart: unless-stopped ports: diff --git a/docs/local-deploy.md b/docs/local-deploy.md index 87abd1b0..06057704 100644 --- a/docs/local-deploy.md +++ b/docs/local-deploy.md @@ -35,6 +35,7 @@ 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 @@ -66,4 +67,4 @@ docker compose --env-file .env.local -f compose.local.yaml restart - 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 +- `CONVERTX_IMAGE` defaults to the published release image and can be overridden if you need a different tag