Skip to content

Self-hosted workflows for coding-agent delivery. Orchestrate CodeBuddy, Codex and Claude Code with scripts and human approval gates. Includes Local workflows for coding assistants.

docs: pull the platform image through the NJU GHCR cache (#213)

cocofhu0ccfde7e181b
diff --git a/.env.example b/.env.example
index a6ea9efd..0b17daf7 100644
--- a/.env.example
+++ b/.env.example
@@ -1,5 +1,6 @@
# ./start.sh (or bash scripts/configure.sh) generates .env with unique local database/session secrets.
# Platform image: empty uses the GHCR release pinned in compose.yaml. Prefer an @sha256: digest when overriding.
+# Slow ghcr.io links: MIRROR=ghcr.nju.edu.cn ./start.sh replaces the ghcr.io host and tags the image back. See README.zh-CN.md.
LOOPFORGE_IMAGE=
# Source build of this checkout (./start.sh dev writes this line; ./start.sh release removes it):
# COMPOSE_FILE=compose.yaml:compose.dev.yaml
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 38882f81..3ee3f648 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -24,13 +24,6 @@ jobs:
release:
runs-on: ubuntu-latest
timeout-minutes: 45
- outputs:
- digest: ${{ steps.push.outputs.digest }}
- tag: ${{ steps.release.outputs.tag }}
- version: ${{ steps.release.outputs.version }}
- sha: ${{ steps.release.outputs.sha }}
- image: ${{ steps.release.outputs.image }}
- prerelease: ${{ steps.release.outputs.prerelease }}
steps:
- uses: actions/[email protected]
with:
@@ -94,29 +87,6 @@ jobs:
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- # Personal TCR. TCR_REGISTRY is the host only, for example
- # ccr.ccs.tencentyun.com. The namespace and repository are loopforge/loopforge.
- - name: Check TCR credentials
- id: tcr
- env:
- TCR_REGISTRY: ${{ secrets.TCR_REGISTRY }}
- TCR_USERNAME: ${{ secrets.TCR_USERNAME }}
- TCR_PASSWORD: ${{ secrets.TCR_PASSWORD }}
- run: |
- if [[ -z "${TCR_USERNAME}" || -z "${TCR_PASSWORD}" ]]; then
- echo "TCR_USERNAME and TCR_PASSWORD repository secrets are required" >&2
- exit 1
- fi
- registry="$(printf '%s' "${TCR_REGISTRY}" | tr -d '[:space:]')"
- if [[ ! "${registry}" =~ ^[a-z0-9]([a-z0-9.-]*[a-z0-9])?(:[0-9]+)?$ ]]; then
- echo "TCR_REGISTRY must be the registry host, for example ccr.ccs.tencentyun.com" >&2
- exit 1
- fi
- {
- echo "registry=${registry}"
- echo "image=${registry}/loopforge/loopforge"
- } >> "$GITHUB_OUTPUT"
-
- uses: docker/metadata-action@v5
id: metadata
with:
@@ -151,71 +121,15 @@ jobs:
- if: failure()
run: docker compose logs platform | tail -200
- mirror:
- needs: release
- runs-on: ubuntu-latest
- timeout-minutes: 30
- steps:
- - uses: actions/[email protected]
- with:
- fetch-depth: 0
- ref: ${{ needs.release.outputs.tag }}
-
- - uses: docker/login-action@v4
- with:
- registry: ghcr.io
- username: ${{ github.actor }}
- password: ${{ secrets.GITHUB_TOKEN }}
-
- - uses: docker/login-action@v4
- with:
- registry: ${{ secrets.TCR_REGISTRY }}
- username: ${{ secrets.TCR_USERNAME }}
- password: ${{ secrets.TCR_PASSWORD }}
-
- # Keep the registry host in this job. Job outputs that contain a secret
- # are dropped before the next job starts.
- - name: Mirror the published image to TCR
- env:
- TCR_REGISTRY: ${{ secrets.TCR_REGISTRY }}
- SRC_IMAGE: ${{ needs.release.outputs.image }}
- DIGEST: ${{ needs.release.outputs.digest }}
- VERSION: ${{ needs.release.outputs.version }}
- SHA: ${{ needs.release.outputs.sha }}
- PRERELEASE: ${{ needs.release.outputs.prerelease }}
- run: |
- sudo apt-get update -qq
- sudo apt-get install -y skopeo
- registry="$(printf '%s' "${TCR_REGISTRY}" | tr -d '[:space:]')"
- if [[ ! "${registry}" =~ ^[a-z0-9]([a-z0-9.-]*[a-z0-9])?(:[0-9]+)?$ ]]; then
- echo "TCR_REGISTRY must be the registry host, for example ccr.ccs.tencentyun.com" >&2
- exit 1
- fi
- tcr_image="${registry}/loopforge/loopforge"
- echo "TCR_IMAGE=${tcr_image}" >> "$GITHUB_ENV"
- src="docker://${SRC_IMAGE}@${DIGEST}"
- auth="${HOME}/.docker/config.json"
- copy() {
- echo "mirroring ${src} -> ${tcr_image}:$1"
- skopeo copy --all --retry-times 3 \
- --src-authfile "${auth}" --dest-authfile "${auth}" \
- "${src}" "docker://${tcr_image}:$1"
- }
- copy "${VERSION}"
- copy "sha-${SHA}"
- if [[ "${PRERELEASE}" != "true" ]]; then
- copy "${VERSION%.*}"
- copy latest
- fi
-
- name: Create or update GitHub Release
shell: bash
env:
GH_TOKEN: ${{ github.token }}
- TAG: ${{ needs.release.outputs.tag }}
- VERSION: ${{ needs.release.outputs.version }}
- IMAGE: ${{ needs.release.outputs.image }}
- PRERELEASE: ${{ needs.release.outputs.prerelease }}
+ TAG: ${{ steps.release.outputs.tag }}
+ VERSION: ${{ steps.release.outputs.version }}
+ IMAGE: ${{ steps.release.outputs.image }}
+ DIGEST: ${{ steps.push.outputs.digest }}
+ PRERELEASE: ${{ steps.release.outputs.prerelease }}
run: |
notes="$(cat <<EOF
## Install
@@ -226,7 +140,11 @@ jobs:
./start.sh
\`\`\`
- Platform image: \`${IMAGE}:${VERSION}\` (pinned in \`compose.yaml\`). Tencent Cloud mirror: \`${TCR_IMAGE}:${VERSION}\`. Existing installations: check out \`${TAG}\`, run \`./start.sh\`, and apply the new files under \`migrations/\` listed in [CHANGELOG.md](https://github.com/${GITHUB_REPOSITORY}/blob/${TAG}/CHANGELOG.md).
+ Platform image: \`${IMAGE}:${VERSION}\` (pinned in \`compose.yaml\`).
+
+ Digest: \`${IMAGE}@${DIGEST}\`.
+
+ Where \`ghcr.io\` is slow, set \`MIRROR\` to a registry host that replaces it (for example \`MIRROR=ghcr.nju.edu.cn ./start.sh\`). This trusts that host: the download is tagged as the pinned name. Check it with \`docker image inspect --format '{{index .RepoDigests 0}}' ${IMAGE}:${VERSION}\` and compare the digest after \`@\`. Existing installations: check out \`${TAG}\`, run \`./start.sh\`, and apply the new files under \`migrations/\` listed in [CHANGELOG.md](https://github.com/${GITHUB_REPOSITORY}/blob/${TAG}/CHANGELOG.md).
EOF
)"
if gh release view "${TAG}" >/dev/null 2>&1; then
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 08f1f451..2680d3bf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,11 @@
# Changelog
-Platform releases use `vX.Y.Z` tags and publish `ghcr.io/tencent/loopforge`, mirrored to `ccr.ccs.tencentyun.com/loopforge/loopforge`. LoopForge Local packages use `local-vX.Y.Z` tags and are published by manually running the `release-local` workflow.
+Platform releases use `vX.Y.Z` tags and publish `ghcr.io/tencent/loopforge`. LoopForge Local packages use `local-vX.Y.Z` tags and are published by manually running the `release-local` workflow.
+
+## Unreleased
+
+- `MIRROR=<host> ./start.sh` pulls `<host>/tencent/loopforge:<version>` and tags it back to the name pinned in `compose.yaml`. `ghcr.nju.edu.cn` is one such host. Unset `MIRROR` still pulls `ghcr.io` directly. `MIRROR=<host> ./start.sh pull` refreshes through the same host. Setting `MIRROR` trusts that host. The published image stays on GHCR, and the GitHub Release records its digest. `registry-mirrors` such as `https://docker.nju.edu.cn` only accelerates Docker Hub. The existing `v0.3.7` tag does not include this script.
+- The release workflow publishes GHCR only. It no longer copies the image to `ccr.ccs.tencentyun.com`.
## 0.3.7 — Tencent Cloud image mirror
diff --git a/README.md b/README.md
index 3c61b7da..cb3b66e1 100644
--- a/README.md
+++ b/README.md
@@ -77,6 +77,12 @@ cd LoopForge
`./start.sh` pulls the GHCR release image pinned in `compose.yaml` without building locally (`bash scripts/install.sh` does the same). It creates the MySQL and platform services, generates configuration and session secrets, and installs the built-in sandboxes, starter SOPs and welcome project. Host Go and Node.js installations are not required. Configure model API keys and GitHub authorization after startup. Use `./start.sh logs`, `stop`, `restart` or `pull` to manage it, and `./start.sh dev` to build the checkout from source.
+If downloads from `ghcr.io` stall, set `MIRROR` to a registry host that can stand in for `ghcr.io`. `./start.sh` pulls from that host and tags the image back to the name pinned in `compose.yaml`. Setting `MIRROR` trusts that host, because the download is tagged with the official name. The GitHub Release records the digest; `docker image inspect --format '{{index .RepoDigests 0}}' ghcr.io/tencent/loopforge:<pin>` should show the same digest after `@`. Without `MIRROR`, `./start.sh` still pulls `ghcr.io` directly, and `compose.yaml` stays unchanged. Upgrade with the same variable and `./start.sh pull`. [ghcr.nju.edu.cn](https://doc.nju.edu.cn/books/e1654/page/ghcr) is one such host. A Docker `registry-mirrors` entry such as `https://docker.nju.edu.cn` only accelerates Docker Hub and is not a value for `MIRROR`. The published `v0.3.7` tag does not include this script; until the next release tag, use the default branch, which still pins `0.3.7`.
+
+```bash
+MIRROR=ghcr.nju.edu.cn ./start.sh
+```
+
Open the address printed by the installer and create your account; the first one becomes the administrator. The service listens on `0.0.0.0:8090` by default. On a cloud host, the installer reads the public IP from the provider's metadata service and prints it; allow the port in your security group, or put an HTTPS reverse proxy in front. Restrict access to your own IP until the administrator account exists. The home page's quick-access guide walks you through adding a model key, connecting a repository and choosing an SOP.
### Try it without an API key
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 3b5f7be7..078fb547 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -77,6 +77,12 @@ cd LoopForge
`./start.sh` 直接拉取 `compose.yaml` 中 pin 的 GHCR 发布镜像,不在本地构建(`bash scripts/install.sh` 效果相同)。安装流程会创建 MySQL 和平台服务,生成配置与会话密钥,并导入内置沙箱、通用 SOP 和体验项目;无需在宿主机安装 Go 或 Node.js。模型 API Key 和 GitHub 授权在启动后由用户配置。用 `./start.sh logs`、`stop`、`restart`、`pull` 管理服务;需要从源码构建时用 `./start.sh dev`。
+国内拉取 `ghcr.io` 经常中断。把 `MIRROR` 设成可以替换 `ghcr.io` 的镜像站主机名,`./start.sh` 会用它拉取,再改回 `compose.yaml` 里的原名。设置 `MIRROR` 表示信任该主机,因为下载结果会被标成官方镜像名。发布说明里有 digest,可用 `docker image inspect --format '{{index .RepoDigests 0}}' ghcr.io/tencent/loopforge:<pin>` 核对,`@` 后面的摘要应一致。不设置时仍直接从 `ghcr.io` 拉取。`compose.yaml` 不用改。升级时带上同一个变量执行 `./start.sh pull`。南京大学的 GHCR 镜像站是 [ghcr.nju.edu.cn](https://doc.nju.edu.cn/books/e1654/page/ghcr)。Docker 引擎里的 `registry-mirrors`(包括 `https://docker.nju.edu.cn`)只加速 Docker Hub,不能填在这里。已发布的 `v0.3.7` 标签里没有这个脚本;下一个版本标签出来之前,使用默认分支,其中的镜像 pin 仍是 `0.3.7`。
+
+```bash
+MIRROR=ghcr.nju.edu.cn ./start.sh
+```
+
打开安装脚本输出的地址创建账号,第一个账号自动成为管理员。服务默认监听 `0.0.0.0:8090`;在云主机上,安装脚本会从云厂商的元数据服务读取公网 IP 并直接打印出来,放通安全组端口即可访问,或配置 HTTPS 反向代理;管理员账号创建前,建议只允许你的 IP 访问。首页的「快速接入」会带你配置模型凭据、绑定仓库并选好默认 SOP。
### 免 API Key 体验
diff --git a/docs/deployment.md b/docs/deployment.md
index 3623d937..ed0f9803 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -27,6 +27,7 @@ Use `AGENTFLOW_MYSQL_DSN` for your own MySQL deployment. A fresh account command
./start.sh stop # stop; ./start.sh down removes containers but keeps data volumes
./start.sh restart # restart the platform container
./start.sh pull # refresh images and recreate changed containers
+MIRROR=ghcr.nju.edu.cn ./start.sh # same install; replace the ghcr.io host with this registry
./start.sh dev # build this checkout instead (compose.dev.yaml)
./start.sh release # switch a source build back to the published image
```
@@ -35,11 +36,18 @@ The installer checks Docker, Compose, Python 3 and curl. It offers to install mi
Run it as the installation owner, including an ordinary Linux user. If that user cannot access Docker directly, the installer validates sudo and uses `sudo -n docker` consistently for Compose, schema installation and seeds. Before each operation it checks whether sudo credentials expired during a long build, prompting again in a terminal or failing with instructions in unattended mode. It does not require adding the user to the Docker group or logging out. For unattended installations run `sudo -v` first; `LOOPFORGE_YES=1` accepts installation prompts but does not bypass operating-system permissions. Without sudo or Docker access it fails immediately with instructions. Rootless Docker uses its active context's Unix socket; remote Docker contexts need a separately configured deployment because sandbox workspaces are local bind mounts.
-`compose.yaml` is the published-image stack and never builds: `./start.sh`, `scripts/install.sh` and a plain `docker compose --profile platform up` all pull the GHCR release pinned there (currently `ghcr.io/tencent/loopforge:0.3.7`). The pin matches the checkout's migrations and seeds, so check out a release tag when you install. Set `LOOPFORGE_IMAGE` (for example to an `@sha256:` digest, or to `ccr.ccs.tencentyun.com/loopforge/loopforge:0.3.7`) only to override it; a value saved in `.env` takes precedence over later pin changes.
+`compose.yaml` is the published-image stack and never builds: `./start.sh`, `scripts/install.sh` and a plain `docker compose --profile platform up` all pull the GHCR release pinned there (currently `ghcr.io/tencent/loopforge:0.3.7`). The pin matches the checkout's migrations and seeds, so check out a release tag when you install. Set `LOOPFORGE_IMAGE` (for example to an `@sha256:` digest) only to override it; a value saved in `.env` takes precedence over later pin changes.
+
+Where `ghcr.io` downloads stall, set `MIRROR` to the registry host that replaces `ghcr.io`. `./start.sh` and `./start.sh pull` pull that reference and tag it back to the name in `compose.yaml`. Setting `MIRROR` trusts that host, because the result is tagged with the official name. The GitHub Release for the next version records the image digest; `docker image inspect --format '{{index .RepoDigests 0}}' ghcr.io/tencent/loopforge:<pin>` should show the same digest after `@`. The pull policy stays `missing` on install, so a local image is kept; `./start.sh pull` refreshes it from the same host. Leaving `MIRROR` unset preserves the direct `ghcr.io` pull. [ghcr.nju.edu.cn](https://doc.nju.edu.cn/books/e1654/page/ghcr) is one compatible host. Docker's `registry-mirrors` setting, including `https://docker.nju.edu.cn`, only applies to Docker Hub and cannot be used as `MIRROR`. A `LOOPFORGE_IMAGE` value that is not a `ghcr.io` name:tag is left unchanged. `MIRROR` is not in the `v0.3.7` tag. Until the next release tag, use the default branch; that checkout still pins `ghcr.io/tencent/loopforge:0.3.7`.
+
+```bash
+MIRROR=ghcr.nju.edu.cn ./start.sh
+MIRROR=ghcr.nju.edu.cn ./start.sh pull
+```
`./start.sh dev` (or `LOOPFORGE_BUILD_FROM_SOURCE=1 bash scripts/install.sh`) builds this checkout as `loopforge-platform:local` from `compose.dev.yaml`. It saves `COMPOSE_FILE=compose.yaml:compose.dev.yaml` in `.env`, so later runs and plain `docker compose` commands keep using the source build until `./start.sh release`. Source builds reuse npm, Go module and Go compiler caches.
-Pushing a `vX.Y.Z` tag on `main` runs the `release` workflow once the `platform` workflow has passed on that commit. The tagged `compose.yaml` must already pin `loopforge:X.Y.Z`. It publishes `ghcr.io/<owner>/loopforge` and the same tags on `ccr.ccs.tencentyun.com/loopforge/loopforge` (`X.Y.Z`, `X.Y`, `latest` and `sha-<commit>`), smoke-tests the pushed GHCR digest with `./start.sh`, and creates the GitHub Release. Forks publish under their own owner; set the GHCR package visibility/access for your team before distributing the image. Images are pulled only when missing by default; use an immutable tag/digest, or set `LOOPFORGE_PULL_POLICY=always` when updating a mutable tag. Existing `.env` values take precedence; change the saved image or URL there when updating an installation. Compose waits for the API's health check with a bounded timeout before installing schema extensions and seeds.
+Pushing a `vX.Y.Z` tag on `main` runs the `release` workflow once the `platform` workflow has passed on that commit. The tagged `compose.yaml` must already pin `loopforge:X.Y.Z`. It publishes `ghcr.io/<owner>/loopforge` as `X.Y.Z`, `X.Y`, `latest` and `sha-<commit>`, smoke-tests the pushed digest with `./start.sh`, and creates the GitHub Release. Forks publish under their own owner; set the GHCR package visibility/access for your team before distributing the image. Images are pulled only when missing by default; use an immutable tag/digest, or set `LOOPFORGE_PULL_POLICY=always` when updating a mutable tag. Existing `.env` values take precedence; change the saved image or URL there when updating an installation. Compose waits for the API's health check with a bounded timeout before installing schema extensions and seeds.
Open the platform and create the first account in the browser; it receives platform administration. Until that account exists the login page only offers this setup step.
diff --git a/scripts/ghcr-mirror.sh b/scripts/ghcr-mirror.sh
new file mode 100644
index 00000000..287090dc
--- /dev/null
+++ b/scripts/ghcr-mirror.sh
@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# Optional pull path for a slow ghcr.io link. Sourced by start.sh and install.sh.
+# MIRROR is unset: callers keep their existing pull. MIRROR=<host> replaces the
+# ghcr.io host, for example MIRROR=ghcr.nju.edu.cn, then tags the image back
+# so compose.yaml and the default pull policy stay unchanged.
+
+mirror_published_ghcr() {
+ local policy="${1:-missing}"
+ [[ -n "${MIRROR:-}" ]] || return 1
+ local mirror_host
+ mirror_host=$(printf '%s' "$MIRROR" | tr '[:upper:]' '[:lower:]')
+ mirror_host="${mirror_host#"${mirror_host%%[![:space:]]*}"}"
+ mirror_host="${mirror_host%"${mirror_host##*[![:space:]]}"}"
+ mirror_host=${mirror_host%/}
+ # The upstream host is the normal pull. Any other registry host replaces ghcr.io.
+ if [[ "$mirror_host" == ghcr.io || "$mirror_host" == ghcr.io:443 ]]; then
+ return 1
+ fi
+ if [[ ! "$mirror_host" =~ ^(localhost|[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+)(:[0-9]{1,5})?$ ]]; then
+ printf '\n✗ MIRROR must be the registry host that replaces ghcr.io, for example ghcr.nju.edu.cn.\n' >&2
+ exit 1
+ fi
+
+ local decision
+ if ! decision=$(python3 - <<'PY'
+import os, re, pathlib, sys
+
+def quoted(value):
+ value = value.strip()
+ if len(value) >= 2 and value[0] == value[-1] and value[0] in "'\"":
+ return value[1:-1]
+ return value
+
+def stored(name):
+ current = os.environ.get(name)
+ if current is not None and current.strip():
+ return quoted(current)
+ path = pathlib.Path('.env')
+ if path.is_file():
+ matches = re.findall(r'(?m)^%s=(.*)$' % re.escape(name), path.read_text())
+ if matches:
+ return quoted(matches[-1])
+ return ''
+
+if stored('COMPOSE_FILE') == 'compose.yaml:compose.dev.yaml':
+ print('skip')
+ raise SystemExit(0)
+
+image = stored('LOOPFORGE_IMAGE')
+if not image:
+ compose = pathlib.Path('compose.yaml')
+ if not compose.is_file():
+ sys.stderr.write('MIRROR needs compose.yaml to find the pinned image.\n')
+ raise SystemExit(1)
+ match = re.search(r'(?m)^[ \t]*image:[ \t]*\$\{LOOPFORGE_IMAGE:-([^}]+)\}[ \t]*$', compose.read_text())
+ if not match:
+ sys.stderr.write('MIRROR could not find the pinned image in compose.yaml.\n')
+ raise SystemExit(1)
+ image = match.group(1).strip()
+
+if not image.startswith('ghcr.io/') or '@' in image:
+ print('skip')
+ raise SystemExit(0)
+if not re.fullmatch(r'ghcr\.io/[A-Za-z0-9._/-]+:[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}', image):
+ sys.stderr.write('MIRROR cannot rewrite this image reference: %s\n' % image)
+ raise SystemExit(1)
+print('mirror ' + image)
+PY
+ ); then
+ exit 1
+ fi
+ [[ "$decision" == skip ]] && return 1
+ [[ "$decision" == mirror\ * ]] || {
+ printf '\n✗ Could not resolve the image for MIRROR=%s.\n' "$mirror_host" >&2
+ exit 1
+ }
+
+ local image="${decision#mirror }"
+ local mirror_image="${mirror_host}/${image#ghcr.io/}"
+ if [[ "$policy" != always ]] && docker_access image inspect "$image" >/dev/null 2>&1; then
+ printf '\n▸ Using local image %s\n' "$image"
+ return 0
+ fi
+ printf '\n▸ Pulling %s and tagging it %s\n' "$mirror_image" "$image"
+ # Called from `if`, so a failing docker command does not exit on its own.
+ # Exit rather than return: a return would make the caller pull ghcr.io directly.
+ if ! docker_access pull "$mirror_image"; then
+ printf '\n✗ Could not pull %s. Stopped without retagging the previous image.\n' "$mirror_image" >&2
+ exit 1
+ fi
+ if ! docker_access tag "$mirror_image" "$image"; then
+ printf '\n✗ Could not tag %s as %s. Stopped without starting.\n' "$mirror_image" "$image" >&2
+ exit 1
+ fi
+}
diff --git a/scripts/install.sh b/scripts/install.sh
index b9465cd1..f754432c 100755
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -10,6 +10,7 @@ cd "$(dirname "$0")/.."
fail() { printf '\n✗ %s\n' "$1" >&2; exit 1; }
step() { printf '\n▸ %s\n' "$1"; }
source scripts/docker-access.sh
+source scripts/ghcr-mirror.sh
confirm() {
[[ "${LOOPFORGE_YES:-}" == 1 ]] && return 0
@@ -161,8 +162,20 @@ PY
fi
if [[ "${COMPOSE_FILE:-}" != "$dev_compose" ]]; then
- step "Pulling the published LoopForge image ${LOOPFORGE_IMAGE:-pinned in compose.yaml}"
- docker_access compose --profile platform pull --policy "${LOOPFORGE_PULL_POLICY:-missing}" platform mysql
+ pull_policy="${LOOPFORGE_PULL_POLICY:-missing}"
+ if mirror_published_ghcr "$pull_policy"; then
+ # The platform name is already local. Pull it with missing so Compose does
+ # not contact ghcr.io; MySQL keeps the requested policy.
+ if [[ "$pull_policy" == always ]]; then
+ docker_access compose --profile platform pull --policy missing platform
+ docker_access compose --profile platform pull --policy always mysql
+ else
+ docker_access compose --profile platform pull --policy "$pull_policy" platform mysql
+ fi
+ else
+ step "Pulling the published LoopForge image ${LOOPFORGE_IMAGE:-pinned in compose.yaml}"
+ docker_access compose --profile platform pull --policy "$pull_policy" platform mysql
+ fi
docker_access compose --profile platform up -d --no-build --wait --wait-timeout 180
else
step 'Building LoopForge from source (first install takes several minutes; frontend, Go and runtime stages build in parallel)'
diff --git a/scripts/test-install-live.sh b/scripts/test-install-live.sh
index 4b647ddd..02ecbf8d 100644
--- a/scripts/test-install-live.sh
+++ b/scripts/test-install-live.sh
@@ -21,7 +21,7 @@ actors=(root nonroot without-compose)
for actor in "${actors[@]}"; do
fixture="$task_dir/$actor"
mkdir -p "$fixture/scripts" "$fixture/migrations/seed" "$fixture/user-home"
- cp scripts/{install.sh,configure.sh,docker-access.sh,install-address.py,install-compose.py,install-observability-schema.sh} "$fixture/scripts/"
+ cp scripts/{install.sh,configure.sh,docker-access.sh,ghcr-mirror.sh,install-address.py,install-compose.py,install-observability-schema.sh} "$fixture/scripts/"
cp migrations/001_run_obs_generated_columns.sql "$fixture/migrations/"
cp migrations/seed/*.sql "$fixture/migrations/seed/"
cp compose.yaml "$fixture/"
diff --git a/scripts/test-install.py b/scripts/test-install.py
index c6deec0b..131fddf5 100644
--- a/scripts/test-install.py
+++ b/scripts/test-install.py
@@ -32,7 +32,7 @@ class InstallerTests(unittest.TestCase):
self.root = Path(self.temp.name)
(self.root / 'scripts').mkdir()
(self.root / 'migrations/seed').mkdir(parents=True)
- for name in ('install.sh', 'configure.sh', 'docker-access.sh', 'install-address.py', 'install-compose.py', 'install-observability-schema.sh'):
+ for name in ('install.sh', 'configure.sh', 'docker-access.sh', 'ghcr-mirror.sh', 'install-address.py', 'install-compose.py', 'install-observability-schema.sh'):
shutil.copyfile(ROOT / 'scripts' / name, self.root / 'scripts' / name)
shutil.copyfile(ROOT / 'start.sh', self.root / 'start.sh')
(self.root / 'migrations/seed/001_test.sql').write_text('SELECT 1;\n')
@@ -43,6 +43,9 @@ if [[ "$1" == info ]]; then
[[ "${MOCK_USER:-0}" == 0 || "${MOCK_PRIVILEGED:-0}" == 1 || "${MOCK_DIRECT:-0}" == 1 ]]
exit
fi
+if [[ "$1" == image && "$2" == inspect && "${MOCK_IMAGE_PRESENT:-0}" != 1 ]]; then exit 1; fi
+if [[ "$1" == pull && "${MOCK_PULL_FAIL:-0}" == 1 ]]; then exit 42; fi
+if [[ "$1" == tag && "${MOCK_TAG_FAIL:-0}" == 1 ]]; then exit 1; fi
if [[ "$*" == 'compose version' && "${MOCK_COMPOSE_MISSING:-0}" == 1 && ! -f "$MOCK_COMPOSE_INSTALLED" ]]; then exit 1; fi
if [[ "$*" == *'ps --status running'* ]]; then echo platform; fi
if [[ "${MOCK_EXPIRE_AFTER_BUILD:-0}" == 1 && "$*" == *'build platform'* ]]; then touch "$MOCK_SUDO_EXPIRED_FILE"; fi
@@ -62,7 +65,7 @@ export MOCK_PRIVILEGED=1
exec "$@"
''')
self.environ = dict(os.environ, PATH=str(self.root / 'mock') + ':' + os.environ['PATH'], MOCK_LOG=str(self.root / 'docker.log'), AGENTFLOW_HTTP_PORT='18765', LOOPFORGE_PUBLIC_URL='https://team.example.test', LOOPFORGE_BIND='0.0.0.0')
- for name in ('LOOPFORGE_DOCKER_USE_SUDO', 'LOOPFORGE_DATA_DIR', 'LOOPFORGE_IMAGE', 'COMPOSE_FILE', 'LOOPFORGE_BUILD_FROM_SOURCE', 'MOCK_USER', 'MOCK_DIRECT', 'MOCK_SUDO_DENIED'):
+ for name in ('LOOPFORGE_DOCKER_USE_SUDO', 'LOOPFORGE_DATA_DIR', 'LOOPFORGE_IMAGE', 'COMPOSE_FILE', 'LOOPFORGE_BUILD_FROM_SOURCE', 'LOOPFORGE_PULL_POLICY', 'MIRROR', 'MOCK_USER', 'MOCK_DIRECT', 'MOCK_SUDO_DENIED', 'MOCK_IMAGE_PRESENT', 'MOCK_PULL_FAIL', 'MOCK_TAG_FAIL'):
self.environ.pop(name, None)
def executable(self, name, contents):
@@ -109,13 +112,153 @@ exec "$@"
self.assertIn('sudo -v', result.stderr)
self.assertNotIn('up -d --no-build', (self.root / 'docker.log').read_text())
+ def pinned_image(self):
+ text = (ROOT / 'compose.yaml').read_text()
+ import re
+ return re.search(r'image:\s*\$\{LOOPFORGE_IMAGE:-([^}]+)\}', text).group(1).strip()
+
+ def use_compose_file(self):
+ shutil.copyfile(ROOT / 'compose.yaml', self.root / 'compose.yaml')
+
def test_default_install_pulls_pinned_release(self):
self.assert_success(self.install())
log = (self.root / 'docker.log').read_text()
self.assertIn('pull --policy missing platform mysql', log)
self.assertNotIn('build platform', log)
+ self.assertNotIn('ghcr.nju.edu.cn', log)
self.assertIn("LOOPFORGE_IMAGE=''", (self.root / '.env').read_text())
+ def test_mirror_host_replaces_ghcr_and_tags_the_pinned_name(self):
+ self.use_compose_file()
+ image = self.pinned_image()
+ for mirror_env, host in (('GHCR.NJU.EDU.CN', 'ghcr.nju.edu.cn'), ('mirror.example.test:5000', 'mirror.example.test:5000')):
+ with self.subTest(host=host):
+ if (self.root / 'docker.log').exists():
+ (self.root / 'docker.log').unlink()
+ mirror = host + '/' + image[len('ghcr.io/'):]
+ self.assert_success(self.install(MIRROR=mirror_env))
+ log = (self.root / 'docker.log').read_text()
+ self.assertLess(log.index(f'pull {mirror}'), log.index(f'tag {mirror} {image}'))
+ self.assertLess(log.index(f'tag {mirror} {image}'), log.index('pull --policy missing platform mysql'))
+ self.assertNotIn('MIRROR=', (self.root / '.env').read_text())
+
+ def test_mirror_keeps_a_local_image(self):
+ self.use_compose_file()
+ result = self.install(MIRROR='ghcr.nju.edu.cn', MOCK_IMAGE_PRESENT='1')
+ self.assert_success(result)
+ log = (self.root / 'docker.log').read_text()
+ self.assertNotIn('ghcr.nju.edu.cn', log)
+ self.assertIn('pull --policy missing platform mysql', log)
+ self.assertIn('Using local image', result.stdout)
+
+ def test_mirror_always_refreshes_from_the_configured_host(self):
+ self.use_compose_file()
+ self.assert_success(self.install(MIRROR='mirror.example.test', LOOPFORGE_PULL_POLICY='always', MOCK_IMAGE_PRESENT='1'))
+ log = (self.root / 'docker.log').read_text()
+ image = self.pinned_image()
+ mirror = 'mirror.example.test/' + image[len('ghcr.io/'):]
+ self.assertIn(f'pull {mirror}', log)
+ self.assertIn('pull --policy missing platform', log)
+ self.assertIn('pull --policy always mysql', log)
+ self.assertNotIn('pull --policy always platform', log)
+
+ def test_upstream_mirror_host_keeps_the_direct_pull(self):
+ self.use_compose_file()
+ self.assert_success(self.install(MIRROR='ghcr.io'))
+ log = (self.root / 'docker.log').read_text()
+ self.assertIn('pull --policy missing platform mysql', log)
+ self.assertNotIn(' tag ', log)
+
+ def test_invalid_mirror_fails_before_pull(self):
+ self.use_compose_file()
+ for mirror in ('NJU', 'https://ghcr.nju.edu.cn', 'ghcr.nju.edu.cn/tencent'):
+ with self.subTest(mirror=mirror):
+ if (self.root / 'docker.log').exists():
+ (self.root / 'docker.log').unlink()
+ result = self.install(MIRROR=mirror)
+ self.assertNotEqual(result.returncode, 0)
+ self.assertIn('ghcr.nju.edu.cn', result.stderr)
+ self.assertNotIn('pull --policy', (self.root / 'docker.log').read_text())
+
+ def test_start_pull_without_mirror_is_unchanged(self):
+ self.assert_success(self.install())
+ (self.root / 'docker.log').unlink()
+ result = subprocess.run(['bash', 'start.sh', 'pull'], cwd=self.root, env=self.environ, text=True, capture_output=True, stdin=subprocess.DEVNULL, timeout=15)
+ self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+ log = (self.root / 'docker.log').read_text()
+ self.assertIn('pull --ignore-buildable --policy always', log)
+ self.assertNotIn('ghcr.nju.edu.cn', log)
+
+ def test_start_pull_with_nju_mirror_does_not_contact_ghcr_for_platform(self):
+ self.use_compose_file()
+ self.assert_success(self.install())
+ (self.root / 'docker.log').unlink()
+ result = subprocess.run(['bash', 'start.sh', 'pull'], cwd=self.root, env=dict(self.environ, MIRROR='ghcr.nju.edu.cn'), text=True, capture_output=True, stdin=subprocess.DEVNULL, timeout=15)
+ self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+ image = self.pinned_image()
+ mirror = 'ghcr.nju.edu.cn/' + image[len('ghcr.io/'):]
+ log = (self.root / 'docker.log').read_text()
+ self.assertIn(f'pull {mirror}', log)
+ self.assertIn(f'tag {mirror} {image}', log)
+ self.assertIn('pull --policy always mysql', log)
+ self.assertNotIn('pull --ignore-buildable --policy always', log)
+
+ def test_mirror_uses_the_last_image_assignment_in_env(self):
+ self.use_compose_file()
+ self.assert_success(self.install())
+ env = self.root / '.env'
+ env.write_text(env.read_text() + 'LOOPFORGE_IMAGE=ghcr.io/example/ignored:1\nLOOPFORGE_IMAGE=ghcr.io/example/chosen:9\n')
+ (self.root / 'docker.log').unlink()
+ result = subprocess.run(['bash', 'start.sh', 'pull'], cwd=self.root, env=dict(self.environ, MIRROR='ghcr.nju.edu.cn'), text=True, capture_output=True, stdin=subprocess.DEVNULL, timeout=15)
+ self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+ log = (self.root / 'docker.log').read_text()
+ self.assertIn('pull ghcr.nju.edu.cn/example/chosen:9', log)
+ self.assertIn('tag ghcr.nju.edu.cn/example/chosen:9 ghcr.io/example/chosen:9', log)
+ self.assertNotIn('example/ignored', log)
+ self.assertNotIn('ghcr.nju.edu.cn/tencent/loopforge', log)
+
+ def test_failed_mirror_pull_does_not_retag_or_start(self):
+ self.use_compose_file()
+ result = self.install(MIRROR='ghcr.nju.edu.cn', MOCK_PULL_FAIL='1')
+ self.assertNotEqual(result.returncode, 0)
+ self.assertIn('Could not pull', result.stderr)
+ log = (self.root / 'docker.log').read_text()
+ self.assertIn('pull ghcr.nju.edu.cn/tencent/loopforge:', log)
+ self.assertNotIn(' tag ', log)
+ self.assertNotIn('up -d --no-build', log)
+
+ def test_failed_mirror_refresh_does_not_retag_a_cached_image(self):
+ self.use_compose_file()
+ self.assert_success(self.install())
+ (self.root / 'docker.log').unlink()
+ result = subprocess.run(
+ ['bash', 'start.sh', 'pull'], cwd=self.root,
+ env=dict(self.environ, MIRROR='ghcr.nju.edu.cn', MOCK_PULL_FAIL='1', MOCK_IMAGE_PRESENT='1'),
+ text=True, capture_output=True, stdin=subprocess.DEVNULL, timeout=15)
+ self.assertNotEqual(result.returncode, 0, result.stdout + result.stderr)
+ self.assertIn('Could not pull', result.stderr)
+ log = (self.root / 'docker.log').read_text()
+ self.assertIn('pull ghcr.nju.edu.cn/tencent/loopforge:', log)
+ self.assertNotIn(' tag ', log)
+ self.assertNotIn('up -d --no-build', log)
+
+ def test_failed_mirror_tag_stops_before_startup(self):
+ self.use_compose_file()
+ result = self.install(MIRROR='ghcr.nju.edu.cn', MOCK_TAG_FAIL='1')
+ self.assertNotEqual(result.returncode, 0)
+ self.assertIn('Could not tag', result.stderr)
+ log = (self.root / 'docker.log').read_text()
+ self.assertIn('pull ghcr.nju.edu.cn/tencent/loopforge:', log)
+ self.assertIn(' tag ', log)
+ self.assertNotIn('up -d --no-build', log)
+
+ def test_source_build_ignores_nju_mirror(self):
+ self.use_compose_file()
+ self.assert_success(self.install(LOOPFORGE_BUILD_FROM_SOURCE='1', MIRROR='ghcr.nju.edu.cn'))
+ log = (self.root / 'docker.log').read_text()
+ self.assertIn('build platform', log)
+ self.assertNotIn('ghcr.nju.edu.cn', log)
+
def test_source_build_persists_dev_compose_file(self):
self.assert_success(self.install(LOOPFORGE_BUILD_FROM_SOURCE='1'))
self.assertIn('build platform', (self.root / 'docker.log').read_text())
diff --git a/start.sh b/start.sh
index f8d4e7c6..27e37eff 100755
--- a/start.sh
+++ b/start.sh
@@ -12,9 +12,12 @@
# ./start.sh pull refresh images and recreate changed containers
# ./start.sh dev build this checkout (compose.dev.yaml) and start it
# ./start.sh release switch a source-built installation back to GHCR
+# MIRROR=ghcr.nju.edu.cn ./start.sh
+# pull ghcr.io images from that host and tag them back
set -euo pipefail
cd "$(dirname "${BASH_SOURCE[0]}")"
source scripts/docker-access.sh
+source scripts/ghcr-mirror.sh
compose() {
[[ -f .env ]] || docker_access_fail 'Not installed yet. Run ./start.sh first.'
@@ -36,7 +39,17 @@ PY
COMPOSE_FILE=compose.yaml bash scripts/install.sh
;;
pull)
- compose pull --ignore-buildable --policy always
+ # An empty MIRROR keeps the original refresh. A registry host pulls the pinned
+ # ghcr.io tag from that host and tags it back before MySQL is refreshed.
+ if [[ -n "${MIRROR:-}" ]]; then
+ [[ -f .env ]] || docker_access_fail 'Not installed yet. Run ./start.sh first.'
+ select_docker_access || docker_access_fail 'Docker is not running, or this user cannot access it.'
+ fi
+ if mirror_published_ghcr always; then
+ compose pull --policy always mysql
+ else
+ compose pull --ignore-buildable --policy always
+ fi
compose up -d --no-build --wait --wait-timeout 180
;;
logs) compose logs -f "${@:-platform}" ;;