> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/argoproj/argo-cd/llms.txt
> Use this file to discover all available pages before exploring further.

# Development Environment Setup

> Set up your local development environment for Argo CD

## Required Tools

You'll need these tools installed with the specified minimum versions:

<CardGroup cols={2}>
  <Card title="Git" icon="git-alt">
    v2.0.0+
  </Card>

  <Card title="Go" icon="golang">
    Version from go.mod
  </Card>

  <Card title="Docker/Podman" icon="docker">
    v20.10.0+ / v3.0.0+
  </Card>

  <Card title="Kubernetes Cluster" icon="dharmachakra">
    Kind, Minikube, or K3d
  </Card>
</CardGroup>

## Installation Steps

### Install Git

You'll need a Git client for pulling source code and pushing changes.

<Card title="Git Installation Guide" icon="git-alt" href="https://github.com/git-guides/install-git">
  Official Git installation instructions
</Card>

### Install Go

<Steps>
  <Step title="Download Go SDK">
    Visit the [official Go download page](https://go.dev/doc/install/) and install Go.
  </Step>

  <Step title="Match go.mod Version">
    Install Go with a version equal to or greater than the version listed in `go.mod`.
  </Step>

  <Step title="Verify Installation">
    ```bash theme={null}
    go version
    ```
  </Step>
</Steps>

<Note>
  We assume your Go workspace is at `~/go`.
</Note>

### Install Docker or Podman

<Tabs>
  <Tab title="Docker">
    Install Docker following the [official documentation](https://docs.docker.com/engine/install/).

    Argo CD uses multi-stage builds, so you'll need a working Docker runtime environment.

    **Verify installation:**

    ```bash theme={null}
    docker version
    ```
  </Tab>

  <Tab title="Podman">
    Install Podman following the [official documentation](https://podman.io/docs/installation).

    **Verify installation:**

    ```bash theme={null}
    podman version
    ```
  </Tab>
</Tabs>

### Install a Local Kubernetes Cluster

You'll need a local Kubernetes cluster for development. Choose one:

<Tabs>
  <Tab title="Kind">
    **Installation**: [Kind Quick Start](https://kind.sigs.k8s.io/docs/user/quick-start)

    **Start the cluster:**

    ```bash theme={null}
    kind create cluster
    ```

    Kind runs Kubernetes inside Docker containers, making it lightweight and fast.
  </Tab>

  <Tab title="Minikube">
    **Installation**: [Minikube Start Guide](https://minikube.sigs.k8s.io/docs/start)

    **Start the cluster:**

    ```bash theme={null}
    minikube start
    ```

    **With Podman driver:**

    ```bash theme={null}
    minikube start --driver=podman
    ```
  </Tab>

  <Tab title="K3d">
    **Installation**: [K3d Quick Start](https://k3d.io/stable/#quick-start)

    K3d runs K3s (lightweight Kubernetes) in Docker containers.
  </Tab>
</Tabs>

**Verify cluster installation:**

```bash theme={null}
kubectl version
```

## Fork and Clone the Repository

<Steps>
  <Step title="Fork the Repository">
    Fork the [Argo CD repository](https://github.com/argoproj/argo-cd) to your personal GitHub account.
  </Step>

  <Step title="Clone Your Fork">
    ```bash theme={null}
    git clone https://github.com/YOUR-USERNAME/argo-cd.git
    ```

    <Warning>
      The local build process uses GOPATH. Don't clone the repository directly into your GOPATH unless intended.
    </Warning>
  </Step>

  <Step title="Add Upstream Remote">
    Create a remote pointing to the original repository for easy updates:

    ```bash theme={null}
    cd argo-cd
    git remote add upstream https://github.com/argoproj/argo-cd.git
    ```

    Keep your local branches up-to-date:

    ```bash theme={null}
    git pull upstream master
    ```
  </Step>
</Steps>

## Install Development Tools

Install required Go tools and code generation tools:

```bash theme={null}
make install-go-tools-local
make install-codegen-tools-local
```

## Install Argo CD on Your Cluster

Deploy Argo CD to your local cluster:

```bash theme={null}
kubectl create namespace argocd && \
kubectl apply -n argocd --server-side --force-conflicts \
  -f https://raw.githubusercontent.com/argoproj/argo-cd/master/manifests/install.yaml
```

**Set default namespace:**

```bash theme={null}
kubectl config set-context --current --namespace=argocd
```

## Toolchain Options

Argo CD provides two development toolchains:

### Virtualized Toolchain

<Accordion title="Using Docker Containers">
  The virtualized toolchain runs builds and tests inside Docker containers using the test tools image. This provides:

  * Same runtime environment as production
  * Easy to keep up-to-date
  * Repeatable builds

  **Requirements:**

  * Your Kubernetes API server must listen on your local machine interface (not `127.0.0.1` only)
  * Your `~/.kube/config` must not use `localhost`, `127.0.0.1`, or `0.0.0.0`

  **Build the test tools image:**

  ```bash theme={null}
  make test-tools-image
  ```

  **Using Podman instead of Docker:**

  ```bash theme={null}
  DOCKER=podman make start
  ```

  **Test cluster connectivity:**

  ```bash theme={null}
  make verify-kube-connect
  ```
</Accordion>

### Local Toolchain

<Accordion title="Running Natively">
  The local toolchain provides a faster development cycle, especially on macOS where Docker runs in a VM.

  **Additional requirements:**

  * [Node.js](https://nodejs.org/en/download)
  * [Yarn](https://classic.yarnpkg.com/lang/en/docs/install/)
  * [Goreman](https://github.com/mattn/goreman#getting-started)
  * Git LFS plugin
  * GnuPG version 2

  **Install tools:**

  ```bash theme={null}
  BIN=~/go/bin make install-tools-local
  ```

  <Tip>
    Set `BIN=~/go/bin` and add `~/go/bin` to your PATH to avoid requiring root privileges.
  </Tip>
</Accordion>

## Next Steps

<CardGroup cols={2}>
  <Card title="Running Locally" icon="play" href="https://argo-cd.readthedocs.io/en/latest/developer-guide/running-locally/">
    Start Argo CD services locally
  </Card>

  <Card title="Tilt Development" icon="rotate" href="https://argo-cd.readthedocs.io/en/latest/developer-guide/tilt/">
    Use Tilt for rapid development
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/developers/architecture">
    Understand the component architecture
  </Card>

  <Card title="Contributing" icon="code-pull-request" href="/developers/contributing">
    Learn how to contribute code
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection refused to Kubernetes API">
    If you see errors like "connection refused to 127.0.0.1:6443":

    1. Edit your `~/.kube/config`
    2. Replace `127.0.0.1` or `localhost` with your machine's IP address
    3. For K3d, follow the specific network configuration steps
  </Accordion>

  <Accordion title="Docker permission denied">
    If your user lacks Docker privileges:

    ```bash theme={null}
    SUDO=sudo make start
    ```

    Or export permanently:

    ```bash theme={null}
    export SUDO=sudo
    ```
  </Accordion>

  <Accordion title="Minikube with virtualized toolchain">
    Minikube with the Docker driver is not compatible with the virtualized toolchain because it hard-codes the API server to 127.0.0.1.

    Start Minikube with embedded certificates:

    ```bash theme={null}
    minikube start --embed-certs
    ```
  </Accordion>
</AccordionGroup>