Developer Guide

This guide walks you through setting up a local Armada development environment using Goreman, our recommended approach for contributing to Armada.

Prerequisites

Before you begin, make sure you have the following installed:

Go — go.dev
gcc — C compiler required by some Go packages
mage — magefile.org
Docker — docs.docker.com
kubectl — kubernetes.io
protobuf — Protocol buffer compiler
kind — kind.sigs.k8s.io
yarn — yarnpkg.com — required for Lookout UI development

Additional tools are automatically installed via mage BootstrapTools from tools.yaml, including golangci-lint, sqlc, go-swagger, and others.

Goreman is a Go-based clone of Foreman that manages Procfile-based applications, allowing you to run multiple processes with a single command. Components are built from source and run on the host, so iteration is fast and debuggers attach directly.

Clone the repository

git clone https://github.com/armadaproject/armada.git
cd armada

Create a local Kind cluster

mage kind
export KUBECONFIG=.kube/external/config

This is a one-time setup step.

Start all Armada services

mage dev:up

This starts Redis, PostgreSQL, and Pulsar in containers, then runs the Armada server, scheduler, executor, Lookout, and all ingesters as local processes via Goreman.

Verify everything is running

goreman run status

Running processes are prefixed with *: *server
*scheduler
*scheduleringester
*eventingester
*executor
*lookout
*lookoutingester
*binoculars
*lookoutui

Restart individual processes without stopping everything:

  goreman restart server

Useful mage commands

mage dev:up        # start dependencies + Armada components via Goreman
mage dev:full      # run the entire stack in containers against Kind (what CI uses)
mage dev:down      # stop dependency containers (after mage dev:up)
mage dev:fullDown  # stop containerised stack and tear down Kind (after mage dev:full)
mage -l            # list all available mage commands

Use mage dev:full to replicate what CI runs. Use mage dev:up for day-to-day development. It's faster since components run as host processes.

Running with authentication

Start dependencies with the auth profile

docker compose -f _local/compose/stack.yaml --profile auth up -d

This starts Redis, PostgreSQL, Pulsar, and Keycloak with a pre-configured realm.

Initialise databases and Kubernetes resources

_local/scripts/init.sh

Start Armada components with auth configuration

goreman -f _local/procfiles/auth.Procfile start

The first run compiles all Armada components from source which can take several minutes. Subsequent runs are faster as Go caches build artifacts.

Use armadactl with OIDC authentication

armadactl --config _local/.armadactl.yaml --context auth-oidc get queues

Default Keycloak credentials — Admin: admin / admin · User: user / password

Running without a Kubernetes cluster

For testing Armada without a real Kubernetes cluster, use the fake executor which simulates a Kubernetes environment:

goreman -f _local/procfiles/fake-executor.Procfile start

The fake executor simulates:

2 virtual nodes with 8 CPUs and 32Gi memory each
Pod lifecycle management without actual container execution
Resource allocation and job state transitions

Useful for testing scheduling logic, development when Kubernetes is unavailable, and integration testing of job flows.

Testing your setup

Run the full test suite:

mage testsuite

Or manually:

go run cmd/armadactl/main.go create queue e2e-test-queue
export ARMADA_EXECUTOR_INGRESS_URL="http://localhost"
export ARMADA_EXECUTOR_INGRESS_PORT=5001
go run cmd/testsuite/main.go test --tests "testsuite/testcases/basic/*" --junit junit.xml

Profiling with pprof

Enable profiling in your component config:

profiling:
  port: 6060

Then connect:

go tool pprof http://localhost:6060/debug/pprof/profile

Debug port mappings

Component	Debug host
`server`	`localhost:4000`
`executor`	`localhost:4001`
`binoculars`	`localhost:4002`
`eventingester`	`localhost:4003`
`lookoutui`	`localhost:4004`
`lookout`	`localhost:4005`
`lookoutingester`	`localhost:4007`

Troubleshooting

Port 6443 already in use

Modify _local/kind/cluster.yaml to use a different port:

- containerPort: 6443
  hostPort: 6444
  protocol: TCP

Arm/M1 Mac issues

export PULSAR_IMAGE=richgross/pulsar:2.11.0

See Arm issue #2493 and Windows issue #2492 for more details.

Need help?

Ask in the Armada Slack channel or find us on Github!

Join #armada on Slack

GitHub Issues