# How to Install Argo CD Locally for Development > Install Argo CD locally for development by setting up a Kind cluster and running `make start` to launch the API server, repo server, and UI on your workstation. Get started quickly! - Repository: [Argo Project/argo-cd](https://github.com/argoproj/argo-cd) - Tags: getting-started - Published: 2026-07-09 --- **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. ```bash kind create cluster --name argocd-cluster ``` ## Step 2: Deploy Argo CD CRDs and Manifests Apply the official install manifest located at [`manifests/install.yaml`](https://github.com/argoproj/argo-cd/blob/main/manifests/install.yaml). This file contains all required Custom Resource Definitions (CRDs), Deployments, Services, and RBAC objects. ```bash 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. ```bash 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: ```bash make start ``` For Podman users: ```bash 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: ```bash make start-local ARGOCD_GPG_ENABLED=false ``` Alternatively, use `make run` or `goreman` directly: ```bash make run ARGOCD_GPG_ENABLED=false ``` Or using goreman: ```bash 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: ```bash 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: ```bash kubectl -n argocd get secret argocd-initial-admin-secret \ -o jsonpath='{.data.password}' | base64 -d ``` Then log in via the CLI: ```bash argocd login localhost:8080 --username admin --password \ --insecure --plaintext ``` ## Iterating on Code Changes After modifying source code, restart individual components to pick up changes. For example, to restart the repo server: ```bash goreman run restart repo-server ``` This workflow is documented in [`docs/developer-guide/running-locally.md`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/docs/try_argo_cd_locally.md)** – Step-by-step tutorial for installing Kind and applying the install manifest. - **[`docs/developer-guide/running-locally.md`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/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 `** 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.