Support self-contained Docker Compose builds from a remote Git context

[Skyline-23]

Area

Installation or packaging

What are you trying to accomplish?

Deploy and update OpenCodex through a deployment dashboard's Raw Compose configuration, using the official repository as a remote Git build context and pull_policy: build.

An operator should be able to press Deploy without maintaining a custom Dockerfile, embedding dockerfile_inline, creating a deployment fork, or manually preparing a source checkout on the server. Docker/BuildKit should handle the build from the selected official Git ref.

What prevents this today?

The official source-build support exists, but its build context must be prepared outside Docker first:

• The Dockerfile verifies a pre-existing compatibility manifest before building.
• It also copies src/generated/compatibility-version.json from the build context.
• That generated file is intentionally untracked, and the documented workflow requires running bun scripts/generate-compatibility-version.ts on the host before docker compose build.

Consequently, a clean remote Git context does not contain an input required by the Dockerfile. The operator needs host-side preparation or a custom build recipe even though the repository already provides an official Dockerfile. pull_policy: build does not supply that missing preparation step.

This limitation was checked against v2.49.0 / main commit 2f3f736299dca38861f8fb9c4326a4b4d7c664bc.

What should OpenCodex do?

Make the official Docker build self-contained, so it can prepare the required compatibility manifest as part of the build from a clean supported Git context.

Expected outcomes:

• A clean remote Git-context build succeeds without installing Bun on the host or running a separate preparation command.
• Operators can use the official Dockerfile through Raw Compose without maintaining an additional file, inline Dockerfile, or fork.
• Redeploying with pull_policy: build builds the selected Git ref and retains the existing persistent-state contract.
• Compatibility identity remains derived from the correct source snapshot, and existing source-integrity checks remain enforced. Removing validation or substituting a placeholder manifest would not satisfy the request.
• The documentation includes a supported remote-context Compose example and any required BuildKit options.

Example usage or interface

Desired build configuration within an otherwise configured Compose service:

services:
  opencodex:
    image: opencodex:local
    pull_policy: build
    build:
      context: https://github.com/lidge-jun/opencodex.git#main
      target: runtime

The operator keeps the normal state volumes and runtime settings, then presses Deploy in Dokploy. A release tag or commit can replace main when a fixed version is preferred. This example describes the requested workflow; it is not a claim that the current Dockerfile already supports it.

Alternatives or workarounds

• A custom Dockerfile can fetch the repository and generate the manifest before building. Keeping it in a dashboard File Mount works, but duplicates upstream packaging and creates another file for each operator to maintain.
• Manually cloning the repository, running the generator, and building from that checkout follows today's documented process, but leaves dashboard-managed deployments dependent on separate server-side maintenance.
• Publishing an official container image would offer another deployment path, but is not required for this request. Source builds with pull_policy: build are acceptable.

Additional context

This is a focused follow-up to #3449, which delivered the official source-build container workflow. The remaining request is to make that workflow usable directly from a clean remote Git context in Raw Compose.

Reference: Remote Hub — Docker Compose.

Checks

• I searched existing issues and documentation.
• This request describes a concrete OpenCodex workflow rather than merely naming a desired technology.
• I removed secrets and personal data.

[Ingwannu]

Confirmed against current dev f94dd88: the Dockerfile runs docker/verify-compatibility.ts against the build context before copying/installing source, and later explicitly copies src/generated/compatibility-version.json. That manifest is generated outside the tracked Git tree; .dockerignore also excludes the generator and Git metadata. A clean remote Git context therefore does not satisfy the current documented source-build inputs. pull_policy: build cannot generate that missing input.

This is a real packaging limitation, not evidence that the existing prepared-checkout build is broken. A fix should generate the manifest from the selected immutable source snapshot in a build stage, then retain the existing source/hash and non-symlink verification before creating the runtime image. Simply deleting the verifier or copying a placeholder would weaken the existing contract.

The design must specify how the generator obtains the canonical tracked-file list in a Git context, and keep any build-only Git metadata out of the runtime. Required checks are a clean remote-ref build, an unchanged prepared-checkout build, and rejection of missing/stale/mismatched manifest inputs where validation still applies. State volumes and foreground lifecycle should stay unchanged. I have not run a Docker deployment or changed an operator's Compose configuration; keeping this open for that scoped packaging work.

[lidge-jun]

리뷰 · 우선순위 48 / 80

이 이슈는 「공식 Dockerfile로 Docker Compose Raw 빌드」를 원격 Git 컨텍스트만으로 끝내고 싶다는 요청입니다. 운영자가 Dokploy 같은 대시보드에서 build.context: https://github.com/lidge-jun/opencodex.git#main과 pull_policy: build만 넣고 Deploy를 누르면, 호스트에 Bun을 깔거나 bun scripts/generate-compatibility-version.ts를 미리 돌리거나, 커스텀 Dockerfile/dockerfile_inline/배포 포크를 유지하지 않아도 되게 하자는 뜻입니다. #3449가 공식 소스 빌드·Compose 경로를 연 뒤에도, 호스트에서 호환성 매니페스트를 먼저 만드는 전제 때문에 원격 Git만으로는 막혀 있다는 후속입니다.

지금 dev(f94dd88f1) Dockerfile을 보면 이유가 분명합니다. build 스테이지 초반 docker/verify-compatibility.ts가 빌드 컨텍스트를 bind로 검사하고, runtime 스테이지는 .gitignore된 src/generated/compatibility-version.json을 명시적으로 COPY합니다. 주석도 「호스트에서 generate를 먼저 실행하라」고 적혀 있습니다. 생성 스크립트 scripts/generate-compatibility-version.ts는 git ls-files로 추적 파일 바이트를 해시해 매니페스트를 만듭니다. 원격 Git 컨텍스트의 워킹 트리에는 보통 그 생성 파일이 없고, 이미지 안에서 git·생성 단계를 공식으로 보장하지도 않습니다. 그래서 「검증을 빼거나 placeholder를 넣자」는 해결이 될 수 없고, 이슈가 요구한 대로 올바른 소스 스냅샷에서 정체성을 유지한 채 빌드 안으로 생성을 옮겨야 합니다.

현재 dev는 Lane B 랜딩·스크린샷 게이트 웨이버 문서 tip이고, 패키징 열차와는 별개입니다. 미리보기/메인 promote나 버전 bump도 이 이슈 범위가 아닙니다. 설치·패키징 enhancement로 가치는 있으나, 호환성 계약(CL-00)과 Docker 빌드 그래프를 건드리므로 「바로 작은 PR 하나」보다는 설계가 먼저인 편입니다.

경로 Dockerfile runtime COPY src/generated/compatibility-version.json - 파일이 컨텍스트에 없으면 빌드가 실패하도록 일부러 막아 둔 장치입니다. 원격 Git만 쓰는 Compose에서는 이 줄이 바로 막힘입니다. 해결은 COPY를 없애는 것이 아니라, 그 전에 공식 빌드 그래프 안에서 같은 규칙으로 파일을 만드는 쪽이어야 합니다.

경로 scripts/generate-compatibility-version.ts git ls-files - 생성기가 Git 인덱스에 묶여 있습니다. BuildKit 원격 컨텍스트에 .git이 오더라도 oven/bun 이미지에 git 바이너리가 없을 수 있고, .git을 컨텍스트에서 빼는 설정도 흔합니다. 「이미지에 git 추가 + 빌드 중 generate」인지, 「git 없이 추적 파일 목록을 다른 정본으로 해시」인지 먼저 정해야 합니다.

경로 docker/verify-compatibility.ts - 매니페스트 스키마와 소스 해시를 빌드 초입에 검사합니다. 생성 단계를 넣으면 verify 순서(생성 → verify → install/build)와, runtime의 두 번째 verify/readOpenCodexCompatibilityVersion 검사가 같은 스냅샷을 보는지 설계에 포함해야 합니다.

경로 문서 Remote Hub — Docker Compose - 이슈가 원하는 예시는 가이드에 「지원되는 원격 컨텍스트 + 필요 BuildKit 옵션」으로 남아야 합니다. 구현 PR은 코드만 바꾸고 가이드를 안 고치면 운영자가 다시 호스트 준비로 돌아갈 수 있습니다.

메인테이너의 판단이 필요한 지점

• 원격 Git 컨텍스트를 1급 지원 경로로 공식화할지, 당분간 호스트 generate + 로컬 컨텍스트만 지원하고 공식 이미지를 대안으로 둘지
• 빌드 중 생성 시 Git 의존을 유지할지, git 없는 해시 정본으로 생성기를 나눌지(호환성 정체성 의미가 달라질 수 있음)
• Dokploy Raw Compose 예시·BuildKit 버전/옵션을 최소 지원 매트릭스에 넣을지
• 이 작업이 [Feature]: Add first-class Docker / Docker Compose deployment support #3449 잔여로 install 라벨 열차에 남는지, 별도 design 이슈로 쪼갤지

너의 추천
enhancement로 열어 두고, 바로 구현 PR을 급히 받지 마세요. 먼저 「빌드 스테이지에서 매니페스트 생성 + 기존 verify 유지 + 원격 context Compose 예시」설계를 짧게 고정한 뒤 PR을 받는 편이 안전합니다. 검증 삭제·placeholder 매니페스트·운영자 포크 Dockerfile은 이 이슈의 성공 조건이 아닙니다. 현재 dev 방향(Lane B 런타임)과 충돌하지 않으니 백로그에 두되, 우선순위는 세션/쿼타 급버그보다 낮게 두면 됩니다.

이 댓글은 grok-bot이 작성했습니다

[lidge-jun]

Shipped on dev by #5030, squashed as a2c6a8f1d4a0e6cda2050b7ce2c033e7527d1ec7.

A build-only manifest stage now takes two inputs: a host-generated manifest, which still wins and leaves the existing workflow unchanged, or a clean Git context. With neither it fails loudly rather than substituting a placeholder, and both verification passes are preserved.

The evidence that matters for your request is that docker smoke is green on the merged head. That job builds the image, so on this change it built from the clean Git context — the self-contained path you asked for, exercised rather than asserted.

One detail worth knowing if you adapt this. The .dockerignore re-include is deliberately .git/index and .git/HEAD only, not .git wholesale: git ls-files reads the index and never opens an object or a ref, and a wholesale allowlist would have pulled this repository's 1.3 GB object store into every local build context. Those two files plus empty objects/ and refs/ directories return the full inventory. Docker cannot carry empty directories, so the stage assembles them into a scratch GIT_DIR it owns, which also sidesteps git's dubious-ownership refusal on a context-owned .git.

Three limitations are stated in the PR rather than worked around: BUILDKIT_CONTEXT_KEEP_GIT_DIR passthrough depends on the Compose version, apt-get git must resolve on the pinned digest for both platforms, and building from a git worktree hits the failure branch because .git is a file there rather than a directory.

Shipping in the next release off dev.