How to Install Argo CD Locally for Development

Install Argo CD locally by creating a Kind cluster, applying the official install manifest, scaling down the in-cluster controllers, and running make start to launch the API server, repo server, and UI on your workstation.

Argo CD is a declarative, GitOps continuous delivery tool for Kubernetes. Setting up a local development environment allows you to iterate quickly on the codebase without pushing images to remote registries. This guide walks you through installing Argo CD locally for development using the official repository structure and Makefile targets defined in argoproj/argo-cd.

Prerequisites

Before you begin, ensure you have the following tools installed:

• Kind (Kubernetes in Docker) for creating a local cluster
• kubectl for interacting with the cluster
• Docker or Podman for running containerized services
• Go (optional) if you prefer running binaries directly instead of Docker

Step 1: Create a Local Kubernetes Cluster

Create a lightweight Kind cluster to host the Argo CD CRDs and configuration. This provides a realistic Kubernetes environment without the overhead of a full remote cluster.

kind create cluster --name argocd-cluster

Step 2: Deploy Argo CD CRDs and Manifests

Apply the official install manifest located at manifests/install.yaml. This file contains all required Custom Resource Definitions (CRDs), Deployments, Services, and RBAC objects.

kubectl create namespace argocd
kubectl apply -n argocd \
  --server-side --force-conflicts \
  -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

Step 3: Scale Down In-Cluster Controllers

To prevent the in-cluster controllers from interfering with your local development instances, scale them to zero. This step is crucial because you will run the API server, repo server, and controller locally on your machine.

kubectl -n argocd scale statefulset/argocd-application-controller --replicas 0
kubectl -n argocd scale deployment/argocd-dex-server --replicas 0
kubectl -n argocd scale deployment/argocd-repo-server --replicas 0
kubectl -n argocd scale deployment/argocd-server --replicas 0
kubectl -n argocd scale deployment/argocd-redis --replicas 0
kubectl -n argocd scale deployment/argocd-applicationset-controller --replicas 0
kubectl -n argocd scale deployment/argocd-notifications-controller --replicas 0

Step 4: Start Argo CD Services Locally

Navigate to the repository root and use the Makefile targets to start the services. You have two options: the virtualized Docker toolchain or the local Go toolchain.

Option A: Docker Toolchain (Recommended)

Run all components using Docker containers with pre-built images:

make start

For Podman users:

DOCKER=podman make start

This exposes the following ports:

• API server on localhost:8080
• UI server on localhost:4000
• Helm registry on localhost:5000

Option B: Local Go Toolchain

Run the binaries directly on your host machine for faster iteration:

make start-local ARGOCD_GPG_ENABLED=false

Alternatively, use make run or goreman directly:

make run ARGOCD_GPG_ENABLED=false

Or using goreman:

goreman start

The Procfile in the repository root defines how each component is launched and provides the environment variables used by these targets.

Step 5: Access the UI and API

Open your browser and navigate to http://localhost:4000 to access the Argo CD web UI.

If you are using the Kind-only install without local services running, expose the API server manually:

kubectl port-forward svc/argocd-server -n argocd 8080:443

Step 6: Authenticate with the Admin Account

Retrieve the auto-generated admin password from the cluster secret:

kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath='{.data.password}' | base64 -d

Then log in via the CLI:

argocd login localhost:8080 --username admin --password <token> \
  --insecure --plaintext

Iterating on Code Changes

After modifying source code, restart individual components to pick up changes. For example, to restart the repo server:

goreman run restart repo-server

This workflow is documented in docs/developer-guide/running-locally.md, which details the "scale-down → make start" workflow and environment variable shortcuts.

Key Files for Local Development

Understanding these core files helps you navigate the development environment:

• manifests/install.yaml – Contains the full set of CRDs, Deployments, Services, and RBAC objects required to run Argo CD in any Kubernetes cluster.
• docs/try_argo_cd_locally.md – Step-by-step tutorial for installing Kind and applying the install manifest.
• docs/developer-guide/running-locally.md – Details the local development workflow, Makefile targets, and component architecture.
• Procfile – Defines how each component is launched (Docker vs. local binary) and specifies environment variables.
• Makefile – Central entry point for building binaries, running tests, and starting the full development stack.

Summary

• Kind provides a lightweight, disposable Kubernetes cluster for local development that mimics production environments.
• The manifests/install.yaml file contains all necessary CRDs and RBAC configurations; apply it first, then scale down in-cluster controllers to prevent conflicts.
• Use make start for Docker-based development or make start-local to run Go binaries directly on your host.
• Access the UI at localhost:4000 and the API at localhost:8080 after starting services.
• Retrieve the initial admin password from the argocd-initial-admin-secret to authenticate via CLI.

Frequently Asked Questions

What is the difference between make start and make start-local?

make start launches Argo CD components using Docker containers based on the Procfile definitions, which is ideal for testing the full stack without compiling locally. make start-local compiles and runs the Go binaries directly on your host machine, offering faster iteration when you are actively modifying source code.

Why do I need to scale down the in-cluster controllers?

Scaling the controllers (such as argocd-application-controller and argocd-server) to zero replicas prevents the in-cluster instances from conflicting with your local development instances. Since you will run these same components locally via make start or make run, the cluster only needs to maintain the CRDs and Redis state while your local machine handles the active reconciliation logic.

How do I restart a specific component after making code changes?

Use the goreman run restart <component> command. For example, goreman run restart repo-server rebuilds and restarts only the repository server, allowing you to test changes without restarting the entire stack. This target is defined in the Procfile and invoked through the Makefile.

Can I use Podman instead of Docker for the virtualized toolchain?

Yes. Set the DOCKER environment variable to podman before running the make command: DOCKER=podman make start. This instructs the build system to use Podman for pulling and running container images instead of the Docker daemon.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}