feat: support local mode using dedicated localmode image

[tkkhq]

Local Image Refactor CLI Plan

This document tracks CLI-side work needed to support the hosting repository split into separate local and cloud server images.

Goal

The CLI should run the local development stack against the local-only server image.

• Local server image: kong/volcano:local-nightly
• Cloud server image: kong/volcano:cloud-nightly

The CLI should continue to support VOLCANO_IMAGE overrides so developers and CI can pin a digest or test image.

Current Behavior

• internal/localmode/service.go defaults defaultVolcanoImage to kong/volcano:nightly.
• internal/localmode/compose.go resolves the final image in this order: default, .env.local, process VOLCANO_IMAGE.
• internal/localmode/assets/docker-compose.template.yml has a fallback ${VOLCANO_IMAGE:-kong/volcano:latest}, but Go injects a resolved VOLCANO_IMAGE, so the template fallback is rarely used.
• internal/localmode/info.go expects /app/volcano-hosting local info --format json inside the volcano-server container.
• No version handshake exists between CLI and server image.

Supported Local Feature Set

The local image must support the command surface currently exposed under local mode:

• volcano start, volcano status, volcano stop, volcano restart
• volcano databases
• volcano functions
• volcano functions schedulers
• volcano storage
• volcano variables
• volcano config deploy
• volcano migrations
• volcano reset

Not currently exposed as local commands:

• Frontends
• Billing, credits, add-ons, plans, Stripe webhooks

Note: Cloud commands are explicitly namespaced under volcano cloud ... (e.g. volcano cloud databases list). Local commands are the default.

Checklist

• Update internal/localmode/service.go default image to kong/volcano:local-nightly.
• Update internal/cmd/localmode/localmode.go help text to show VOLCANO_IMAGE=kong/volcano:local-nightly volcano start.
• Update internal/localmode/assets/docker-compose.template.yml fallback image to kong/volcano:local-nightly for consistency.
• Confirm the asset generation source, if any, is updated before editing generated assets.
• Update local-mode tests that assert or default the old image tag.
• Update e2e defaults in tests/e2e/localmode/localmode_test.go from kong/volcano:nightly to kong/volcano:local-nightly.
• Update .github/workflows/check.yml pinned image tag/digest once the new local image is published. CI remains pinned to the last published image until hosting publishes kong/volcano:local-nightly.
• Document VOLCANO_IMAGE override in command help and project docs.
• Keep .env.local override behavior unchanged.
• Keep process VOLCANO_IMAGE taking precedence over .env.local.
• Keep container names unchanged: volcano-server, volcano-postgres, volcano-redis.
• Keep compose project name unchanged: volcano.
• Keep server binary path unchanged: /app/volcano-hosting.
• Keep local info --format json contract unchanged.
• Consider adding a future compatibility field to local info JSON, but do not require it for the image split unless the server contract changes.

Verification Checklist

• go test ./internal/localmode/...
• go test ./internal/cmd/localmode/...
• go test ./...
• VOLCANO_IMAGE=kong/volcano:local-nightly volcano start
• volcano status
• volcano databases list
• volcano functions list
• volcano storage bucket list
• volcano stop

Coordination With Hosting

• The hosting repo must publish kong/volcano:local-nightly from Dockerfile built with go build -tags local.
• The hosting repo must publish kong/volcano:cloud-nightly from Dockerfile.server built without local tags.
• The local image must not contain AWS SDK or Stripe SDK dependencies.
• The local image must keep /app/volcano-hosting local info --format json stable.
• If hosting changes local info JSON, add CLI-side compatibility handling in internal/localmode/info.go.

[Copilot]

Pull request overview

Updates Volcano CLI local-mode defaults to use the new dedicated local server image tag (kong/volcano:local-nightly) instead of the shared nightly tag, and aligns unit/e2e expectations accordingly.

Changes:

• Switch local-mode default server image to kong/volcano:local-nightly and update related unit/e2e tests.
• Update docker-compose template fallback image to kong/volcano:local-nightly.
• Adjust local-mode start command help text and add workflow commentary around CI image pinning.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/e2e/localmode/localmode_test.go	Updates e2e default VOLCANO_IMAGE to local-nightly when unset.
internal/localmode/start_test.go	Updates unit test assertions and env stubs to local-nightly.
internal/localmode/service.go	Changes local-mode default image constant to local-nightly.
internal/localmode/compose_test.go	Updates compose environment tests to expect local-nightly.
internal/localmode/assets/docker-compose.template.yml	Updates compose template fallback image to local-nightly.
internal/cmd/localmode/localmode.go	Updates start command help example image tag.
.github/workflows/check.yml	Adds commentary for CI image pinning in localmode-e2e job.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[swkeever]

Found 1 review finding.

[swkeever]

[P1] Use a published image tag for local-mode

With the current registry state, kong/volcano:local-nightly does not resolve (docker manifest inspect returns no such manifest), so every localmode-e2e workflow run will fail at this new check before tests start. The same tag is also now the CLI default, so users running volcano start without VOLCANO_IMAGE will hit the same pull failure; publish this tag before merging or keep the default/CI on an existing published image.

Suggested fix: Address this review finding.