Local Development: Change VS Code to use Goreman

[d2burkhalter]

What type of PR is this?

Enhancement for VS Code launch configurations that will align its debugger to use processes launched from Goreman with configs and docker compose in /_local to consolidate how we do local development. Also adds launch configurations for starting Armada with authorization and prometheus.

What this PR does / why we need it

• add launch config for running with Prometheus
• add launch config for running with Authorization
• add launch config for running with Prometheus and Authorization
• fix race condition of migration task running before Postgres is ready
• add task for full teardown of local development resources
• consolidate local development to use /_local

[greptile-apps]

Greptile Summary

This PR overhauls the VS Code local development experience for Armada, replacing direct-launch debug configs with Goreman-backed dlv-DAP attach configs and adding six compound launch profiles (no-auth, auth, fake-executor — each with and without Prometheus). It also adds a Prometheus service to the Docker Compose stack, fixes a metrics config key in the scheduler ingester, and introduces helper scripts for port checking, service pre-building, and DAP readiness polling.

• New VS Code launch/task graph: launch.json now attaches to pre-built dlv dap listeners on ports 2345–2353; tasks.json orchestrates a pre-build → port-check → goreman-start → wait-for-dlv sequence for each variant.
• Goreman DAP Procfiles: four new Procfiles (no-auth-dap, auth-dap, fake-executor-dap) build services to ./dist/ and open dlv DAP ports, letting VS Code attach with auth- or no-auth-specific configs.
• Prometheus support: new compose service under the prometheus profile, new _local/prometheus.yml targeting all Armada metrics ports, and corresponding dev:up/dev:down wiring in magefiles/dev.go.

Confidence Score: 4/5

Safe to merge for non-DAP workflows; the new Goreman DAP debugging path needs one fix before it works end-to-end.

The Dev.Up function accepts dap *bool but every tasks.json invocation passes the string -dap as that argument. Mage resolves typed target arguments with strconv.ParseBool, which rejects -dap and exits with a parse error before the function body runs. All six new compound VS Code configurations depend on a pre-launch task that hits this code path, so the entire new DAP debugging workflow is non-functional until the parameter type or the call sites are changed.

magefiles/dev.go (the dap *bool parameter) and .vscode/tasks.json (all six mage dev:up ... -dap invocations) need to be reconciled before the new debugging workflows will start successfully.

Important Files Changed

Filename	Overview
magefiles/dev.go	Adds optional dap *bool parameter to Dev.Up for DAP procfile selection; adds prometheus compose profile support in Dev.Down. The *bool parameter is incompatible with the -dap flag syntax used in tasks.json.
.vscode/tasks.json	Replaces old single-task setup with a rich task graph (pre-build, port check, start deps, wait-for-dlv). All six new background dependency tasks call mage dev:up ... -dap which is broken due to the *bool parameter issue in dev.go.
.vscode/launch.json	Replaces direct-launch configs with dlv-dap attach configs covering all services on dedicated ports (2345–2353). Auth and no-auth variants provided; port assignments consistent with Procfiles and wait-for-dlv.sh.
_local/scripts/prebuild-services.sh	New script compiling all Go services in parallel for cache warming and early error detection, but builds to /dev/null rather than dist/, so goreman still does a full rebuild per service.
_local/scripts/wait-for-dlv.sh	New script that polls dlv DAP listener ports sequentially (60s timeout each); handles standard and fake-executor modes correctly.
_local/compose/stack.yaml	Adds a Prometheus service under the prometheus compose profile with healthcheck and host.docker.internal networking; correctly scoped and does not affect the default stack.
_local/prometheus.yml	New Prometheus scrape config targeting all Armada services via host.docker.internal on ports 9000–9008; port assignments consistent with service metric port configs.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant User as VS Code User
    participant Task as preLaunchTask
    participant PB as prebuild-services.sh
    participant Goreman as goreman (DAP Procfile)
    participant DLV as dlv dap listeners
    participant Wait as wait-for-dlv.sh
    participant VSCode as VS Code Debuggers

    User->>Task: Launch compound config (e.g. Armada no-auth)
    Task->>PB: Pre-build Go services (parallel, cache warm)
    PB-->>Task: All services compile OK
    Task->>Task: Check for port conflicts
    Task->>Goreman: mage dev:up [profiles] -dap
    Goreman->>Goreman: docker compose up (redis/postgres/pulsar)
    Goreman->>DLV: "go build → dlv dap --listen=:2345 (server)"
    Goreman->>DLV: "go build → dlv dap --listen=:2346 (scheduler)"
    Goreman->>DLV: "go build → dlv dap --listen=:234x (...)"
    Task->>Wait: wait-for-dlv.sh standard
    Wait-->>Task: All dlv ports ready
    Task-->>User: preLaunchTask complete
    User->>VSCode: Attach debuggers (ports 2345–2353)
    VSCode->>DLV: DAP attach with config file args
    DLV-->>VSCode: Debugging session active

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant User as VS Code User
    participant Task as preLaunchTask
    participant PB as prebuild-services.sh
    participant Goreman as goreman (DAP Procfile)
    participant DLV as dlv dap listeners
    participant Wait as wait-for-dlv.sh
    participant VSCode as VS Code Debuggers

    User->>Task: Launch compound config (e.g. Armada no-auth)
    Task->>PB: Pre-build Go services (parallel, cache warm)
    PB-->>Task: All services compile OK
    Task->>Task: Check for port conflicts
    Task->>Goreman: mage dev:up [profiles] -dap
    Goreman->>Goreman: docker compose up (redis/postgres/pulsar)
    Goreman->>DLV: "go build → dlv dap --listen=:2345 (server)"
    Goreman->>DLV: "go build → dlv dap --listen=:2346 (scheduler)"
    Goreman->>DLV: "go build → dlv dap --listen=:234x (...)"
    Task->>Wait: wait-for-dlv.sh standard
    Wait-->>Task: All dlv ports ready
    Task-->>User: preLaunchTask complete
    User->>VSCode: Attach debuggers (ports 2345–2353)
    VSCode->>DLV: DAP attach with config file args
    DLV-->>VSCode: Debugging session active

Loading

_{Reviews (24): Last reviewed commit: "fix: pre build go services and have IDE ..." | Re-trigger Greptile}

[greptile-apps]

Want your agent to iterate on Greptile's feedback? Try greploops.

[d2burkhalter]

@greptileai

[d2burkhalter]

@greptileai

[dejanzele]

host.docker.internal is a very OSX-specific feature, can we use something which would work on both Linux and OSX?

[d2burkhalter]

I think the extra_hosts property here should allow it to work the same on osx and linux

  prometheus:
    container_name: prometheus
    image: ${PROMETHEUS_IMAGE:-prom/prometheus:v3.11.3}
    extra_hosts:
      - "host.docker.internal:host-gateway"

[dejanzele]

We might have many sections in the README.md which could go in this docs/developer_guide.md, could you debloat the README also?

[d2burkhalter]

I think we should have large doc changes in a separate PR. Want to try and get a consensus for what we want to do with README.md, docs/ and website/ and go from there

[greptile-apps]

*bool parameter incompatible with -dap flag syntax in every task

Mage parses typed target arguments using strconv.ParseBool for *bool parameters. Every tasks.json command that calls mage dev:up <profiles> -dap will fail at argument parsing because "-dap" is not a valid bool string ("true" / "false"). The isDAP := dap != nil check is never reached — mage exits with a parse error before the function runs. All six new compound VS Code configurations use a pre-launch task with this flag, so none of them would work.

The simplest fix is to replace *bool with a string parameter and check whether it equals "-dap", or rename the check to dap != "" / dap == "-dap", preserving the existing call syntax in tasks.json. Alternatively, keep *bool and change all tasks.json invocations to pass true instead of -dap.

[d2burkhalter]

From https://magefile.org/targets/

For *bool parameters, you can use the shorthand -name without a value, which is equivalent to -name=true

[greptile-apps]

You're right — I was wrong. The Mage docs explicitly document that shorthand, so -dap is valid syntax for a *bool parameter and will be parsed correctly. My concern about a parse error was unfounded. The implementation is correct as-is.

Tip: You can customize Greptile's behavior for this repo with .greptile/rules.md and .greptile/config.json.