> ## 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.

# Quickstart Guide

> Get started with Argo CD in minutes - install, deploy your first application, and sync manifests from Git

## Overview

Argo CD is a declarative, GitOps continuous delivery tool for Kubernetes. This quickstart guide will walk you through installing Argo CD, accessing the UI and CLI, and deploying your first application from a Git repository.

<Note>
  This guide assumes you have:

  * A running Kubernetes cluster
  * `kubectl` installed and configured
  * A kubeconfig file (default location: `~/.kube/config`)
  * CoreDNS enabled (for microk8s: `microk8s enable dns && microk8s stop && microk8s start`)
</Note>

## Installation

<Steps>
  <Step title="Install Argo CD">
    Create the `argocd` namespace and install Argo CD using the official manifests:

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

    This creates all Argo CD services and application resources in the `argocd` namespace.

    <Info>
      **Why `--server-side --force-conflicts`?**

      The `--server-side` flag is required because some Argo CD CRDs (like ApplicationSet) exceed the 262KB annotation size limit imposed by client-side `kubectl apply`. Server-side apply avoids this limitation by not storing the `last-applied-configuration` annotation.

      The `--force-conflicts` flag allows the apply operation to take ownership of fields that may have been previously managed by other tools.
    </Info>

    <Warning>
      The installation manifests include `ClusterRoleBinding` resources that reference the `argocd` namespace. If you're installing into a different namespace, update the namespace reference in the manifests.
    </Warning>

    For production use, pin to a specific version:

    ```bash theme={null}
    kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/argo-cd/v3.2.0/manifests/install.yaml
    ```
  </Step>

  <Step title="Install Argo CD CLI">
    Download and install the Argo CD CLI to interact with Argo CD from your terminal.

    <CodeGroup>
      ```bash macOS (Homebrew) theme={null}
      brew install argocd
      ```

      ```bash Linux (Homebrew) theme={null}
      brew install argocd
      ```

      ```bash Linux (curl) theme={null}
      VERSION=$(curl -L -s https://raw.githubusercontent.com/argoproj/argo-cd/stable/VERSION)
      curl -sSL -o argocd-linux-amd64 https://github.com/argoproj/argo-cd/releases/download/v$VERSION/argocd-linux-amd64
      sudo install -m 555 argocd-linux-amd64 /usr/local/bin/argocd
      rm argocd-linux-amd64
      ```

      ```bash macOS (curl - Apple Silicon) theme={null}
      VERSION=$(curl --silent "https://api.github.com/repos/argoproj/argo-cd/releases/latest" | grep '"tag_name"' | sed -E 's/.*"([^"]+)".*/\1/')
      curl -sSL -o argocd https://github.com/argoproj/argo-cd/releases/download/$VERSION/argocd-darwin-arm64
      sudo install -m 555 argocd /usr/local/bin/argocd
      rm argocd
      ```

      ```powershell Windows (PowerShell) theme={null}
      $version = (Invoke-RestMethod https://api.github.com/repos/argoproj/argo-cd/releases/latest).tag_name
      $url = "https://github.com/argoproj/argo-cd/releases/download/" + $version + "/argocd-windows-amd64.exe"
      Invoke-WebRequest -Uri $url -OutFile argocd.exe
      # Add to PATH: [Environment]::SetEnvironmentVariable("Path", "$env:Path;C:\Path\To\ArgoCD-CLI", "User")
      ```
    </CodeGroup>

    Verify the installation:

    ```bash theme={null}
    argocd version --client
    ```
  </Step>

  <Step title="Access Argo CD">
    By default, the Argo CD API server is not exposed externally. Choose one of the following methods to access it:

    <Accordion title="Port Forwarding (Recommended for Testing)">
      Use kubectl port-forward to access the API server locally:

      ```bash theme={null}
      kubectl port-forward svc/argocd-server -n argocd 8080:443
      ```

      Access the UI at: [https://localhost:8080](https://localhost:8080)
    </Accordion>

    <Accordion title="Service Type LoadBalancer">
      Expose the service with a LoadBalancer (requires cloud provider support):

      ```bash theme={null}
      kubectl patch svc argocd-server -n argocd -p '{"spec": {"type": "LoadBalancer"}}'
      ```

      Get the external IP:

      ```bash theme={null}
      kubectl get svc argocd-server -n argocd -o=jsonpath='{.status.loadBalancer.ingress[0].ip}'
      ```
    </Accordion>

    <Accordion title="Ingress">
      For production environments, configure an Ingress resource. See the [Argo CD Ingress documentation](https://argo-cd.readthedocs.io/en/stable/operator-manual/ingress/) for detailed configuration.
    </Accordion>
  </Step>

  <Step title="Login to Argo CD">
    Retrieve the initial admin password:

    ```bash theme={null}
    argocd admin initial-password -n argocd
    ```

    The password is auto-generated and stored in the `argocd-initial-admin-secret` secret.

    Login using the CLI:

    ```bash theme={null}
    argocd login <ARGOCD_SERVER>
    ```

    Use username `admin` and the password from the previous command.

    <Warning>
      Delete the `argocd-initial-admin-secret` after changing your password:

      ```bash theme={null}
      kubectl delete secret argocd-initial-admin-secret -n argocd
      ```

      The secret serves no purpose after the initial login and can be safely deleted.
    </Warning>

    Change the admin password:

    ```bash theme={null}
    argocd account update-password
    ```

    <Info>
      If the CLI can't directly access the API server, use port forwarding:

      * Add `--port-forward-namespace argocd` to each command, or
      * Set `ARGOCD_OPTS` environment variable: `export ARGOCD_OPTS='--port-forward-namespace argocd'`
    </Info>
  </Step>

  <Step title="Create Your First Application">
    Deploy the example guestbook application from the Argo CD demo repository.

    Set the default namespace:

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

    Create the application using the CLI:

    ```bash theme={null}
    argocd app create guestbook \
      --repo https://github.com/argoproj/argocd-example-apps.git \
      --path guestbook \
      --dest-server https://kubernetes.default.svc \
      --dest-namespace default
    ```

    Or create using a declarative YAML manifest:

    ```yaml theme={null}
    apiVersion: argoproj.io/v1alpha1
    kind: Application
    metadata:
      name: guestbook
      namespace: argocd
    spec:
      project: default
      source:
        repoURL: https://github.com/argoproj/argocd-example-apps.git
        targetRevision: HEAD
        path: guestbook
      destination:
        server: https://kubernetes.default.svc
        namespace: default
    ```

    Apply the manifest:

    ```bash theme={null}
    kubectl apply -f application.yaml
    ```
  </Step>

  <Step title="Sync the Application">
    View the application status:

    ```bash theme={null}
    argocd app get guestbook
    ```

    Output:

    ```
    Name:               guestbook
    Server:             https://kubernetes.default.svc
    Namespace:          default
    URL:                https://10.97.164.88/applications/guestbook
    Repo:               https://github.com/argoproj/argocd-example-apps.git
    Target:             HEAD
    Path:               guestbook
    Sync Policy:        <none>
    Sync Status:        OutOfSync from (1ff8a67)
    Health Status:      Missing

    GROUP  KIND        NAMESPACE  NAME          STATUS     HEALTH
    apps   Deployment  default    guestbook-ui  OutOfSync  Missing
           Service     default    guestbook-ui  OutOfSync  Missing
    ```

    The application is initially `OutOfSync` because resources haven't been deployed yet.

    Sync (deploy) the application:

    ```bash theme={null}
    argocd app sync guestbook
    ```

    This retrieves manifests from Git and performs a `kubectl apply`. View the deployed resources:

    ```bash theme={null}
    argocd app get guestbook
    ```

    <Info>
      You can also sync from the UI:

      1. Navigate to the Applications page
      2. Click the **Sync** button on the guestbook application
      3. Click **Synchronize** in the panel
    </Info>
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Core Concepts" icon="book" href="/core-concepts">
    Learn about Applications, sync status, health checks, and GitOps principles
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/architecture">
    Understand Argo CD's component architecture and how they work together
  </Card>

  <Card title="Configure Auto-Sync" icon="rotate" href="https://argo-cd.readthedocs.io/en/stable/user-guide/auto_sync/">
    Enable automated synchronization for continuous deployment
  </Card>

  <Card title="Multi-Cluster Setup" icon="server" href="https://argo-cd.readthedocs.io/en/stable/getting_started/#5-register-a-cluster-to-deploy-apps-to-optional">
    Register external clusters for multi-cluster deployments
  </Card>
</CardGroup>

## Optional: Register External Clusters

To deploy applications to external clusters (not the cluster where Argo CD is running):

```bash theme={null}
# List available contexts
kubectl config get-contexts -o name

# Register a cluster
argocd cluster add docker-desktop
```

This installs a ServiceAccount (`argocd-manager`) in the target cluster's `kube-system` namespace and binds it to an admin-level ClusterRole.

<Note>
  When deploying to the same cluster where Argo CD runs, use `https://kubernetes.default.svc` as the destination server. No cluster registration is needed.
</Note>