docker.recipes

Argo CD GitOps Stack

advanced

Declarative GitOps continuous delivery tool for Kubernetes with UI and CLI.

Overview

Argo CD is a declarative GitOps continuous delivery tool that revolutionizes Kubernetes application deployment by treating Git repositories as the single source of truth. Originally developed by Intuit and later donated to the CNCF, Argo CD has become the de facto standard for GitOps workflows, enabling teams to manage application lifecycle through Git commits rather than manual kubectl commands or CI/CD pipeline scripts. This comprehensive stack combines the core Argo CD components with Redis for state management and Dex for enterprise authentication, creating a production-ready GitOps platform that can manage thousands of applications across multiple Kubernetes clusters. This multi-component architecture separates concerns effectively: argocd-server provides the web UI and API gateway, argocd-repo-server handles Git repository operations and manifest generation, argocd-controller continuously monitors and synchronizes application state, while Redis serves as the shared cache and session store. Dex integration enables SSO authentication through LDAP, SAML, OIDC, and other enterprise identity providers, eliminating the need for manual user management. Together, these services create a robust GitOps control plane that automatically detects configuration drift, provides detailed application health monitoring, and enables self-healing deployments. Platform engineering teams, DevOps engineers managing multiple Kubernetes clusters, and organizations transitioning from traditional CI/CD to GitOps methodologies will find this stack invaluable. Unlike traditional deployment tools like Jenkins or GitLab CI that push changes to clusters, Argo CD operates on a pull model where the controller continuously polls Git repositories and automatically applies changes, providing superior security posture and audit trails. The declarative nature means application configurations are versioned, reviewable through standard Git workflows, and can be rolled back instantly, making it ideal for teams requiring compliance, auditability, and reliable deployment processes.

Key Features

  • GitOps-based deployments with Git repository as single source of truth for all application configurations
  • Declarative application definitions using Kubernetes YAML, Helm charts, Kustomize, or Jsonnet templates
  • Real-time application health monitoring with detailed resource status and sync state visualization
  • Multi-cluster application management from a single control plane with cluster credential management
  • Automated drift detection and self-healing capabilities to maintain desired state continuously
  • SSO integration through Dex supporting LDAP, SAML, OIDC, GitHub, Google, and other identity providers
  • Resource hooks for pre-sync, post-sync, and sync failure operations enabling advanced deployment patterns
  • Application rollback capabilities with Git commit-level granularity for instant recovery from issues

Common Use Cases

  • 1Multi-environment Kubernetes application delivery with promotion pipelines from dev to staging to production
  • 2Multi-cluster application synchronization for hybrid cloud or disaster recovery scenarios across different regions
  • 3Microservices deployment orchestration with dependency management and coordinated rollouts
  • 4Infrastructure as Code management for Kubernetes operators, CRDs, and cluster-level configurations
  • 5Compliance-driven deployments requiring audit trails and approval workflows through Git-based processes
  • 6Development team self-service application deployment with RBAC controls and namespace isolation
  • 7Disaster recovery automation with Git-based configuration backup and cross-cluster replication capabilities

Prerequisites

  • Minimum 2GB RAM and 2 CPU cores recommended for handling multiple applications and Git repository operations
  • Access to a Kubernetes cluster with cluster-admin permissions for initial Argo CD installation and management
  • Git repository hosting with webhook capabilities (GitHub, GitLab, Bitbucket) containing application manifests
  • Understanding of Kubernetes concepts including deployments, services, ingress, and RBAC configuration
  • Network connectivity allowing Argo CD to reach both Git repositories and target Kubernetes clusters
  • Valid TLS certificates or willingness to use self-signed certificates for HTTPS web UI access

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  argocd-server: 
3    image: quay.io/argoproj/argocd:latest
4    command: argocd-server
5    ports: 
6      - "8080:8080"
7      - "8443:8443"
8    environment: 
9      ARGOCD_REDIS_ADDR: redis:6379
10      ARGOCD_REPO_SERVER_ADDR: argocd-repo-server:8081
11    volumes: 
12      - argocd_server:/home/argocd
13    depends_on: 
14      - redis
15      - argocd-repo-server
16    networks: 
17      - argocd-net
18    restart: unless-stopped
19
20  argocd-repo-server: 
21    image: quay.io/argoproj/argocd:latest
22    command: argocd-repo-server
23    ports: 
24      - "8081:8081"
25    environment: 
26      ARGOCD_REDIS_ADDR: redis:6379
27    volumes: 
28      - argocd_repo:/home/argocd
29    depends_on: 
30      - redis
31    networks: 
32      - argocd-net
33    restart: unless-stopped
34
35  argocd-controller: 
36    image: quay.io/argoproj/argocd:latest
37    command: argocd-application-controller
38    environment: 
39      ARGOCD_REDIS_ADDR: redis:6379
40      ARGOCD_REPO_SERVER_ADDR: argocd-repo-server:8081
41    volumes: 
42      - argocd_controller:/home/argocd
43    depends_on: 
44      - redis
45      - argocd-repo-server
46    networks: 
47      - argocd-net
48    restart: unless-stopped
49
50  redis: 
51    image: redis:7-alpine
52    volumes: 
53      - redis_data:/data
54    networks: 
55      - argocd-net
56    restart: unless-stopped
57
58  dex: 
59    image: ghcr.io/dexidp/dex:latest
60    ports: 
61      - "5556:5556"
62    volumes: 
63      - ./dex-config.yaml:/etc/dex/config.yaml:ro
64    command: dex serve /etc/dex/config.yaml
65    networks: 
66      - argocd-net
67    restart: unless-stopped
68
69volumes: 
70  argocd_server: 
71  argocd_repo: 
72  argocd_controller: 
73  redis_data: 
74
75networks: 
76  argocd-net: 
77    driver: bridge

.env Template

.env
1# Argo CD Configuration
2ARGOCD_ADMIN_PASSWORD=secure_admin_password
3
4# Dex OIDC Configuration
5DEX_GITHUB_CLIENT_ID=xxx
6DEX_GITHUB_CLIENT_SECRET=xxx

Usage Notes

  1. 1Argo CD UI at https://localhost:8443
  2. 2Get initial admin password from secret
  3. 3Best used with Kubernetes - standalone for testing
  4. 4Configure dex-config.yaml for SSO

Individual Services(5 services)

Copy individual services to mix and match with your existing compose files.

argocd-server
argocd-server:
  image: quay.io/argoproj/argocd:latest
  command: argocd-server
  ports:
    - "8080:8080"
    - "8443:8443"
  environment:
    ARGOCD_REDIS_ADDR: redis:6379
    ARGOCD_REPO_SERVER_ADDR: argocd-repo-server:8081
  volumes:
    - argocd_server:/home/argocd
  depends_on:
    - redis
    - argocd-repo-server
  networks:
    - argocd-net
  restart: unless-stopped
argocd-repo-server
argocd-repo-server:
  image: quay.io/argoproj/argocd:latest
  command: argocd-repo-server
  ports:
    - "8081:8081"
  environment:
    ARGOCD_REDIS_ADDR: redis:6379
  volumes:
    - argocd_repo:/home/argocd
  depends_on:
    - redis
  networks:
    - argocd-net
  restart: unless-stopped
argocd-controller
argocd-controller:
  image: quay.io/argoproj/argocd:latest
  command: argocd-application-controller
  environment:
    ARGOCD_REDIS_ADDR: redis:6379
    ARGOCD_REPO_SERVER_ADDR: argocd-repo-server:8081
  volumes:
    - argocd_controller:/home/argocd
  depends_on:
    - redis
    - argocd-repo-server
  networks:
    - argocd-net
  restart: unless-stopped
redis
redis:
  image: redis:7-alpine
  volumes:
    - redis_data:/data
  networks:
    - argocd-net
  restart: unless-stopped
dex
dex:
  image: ghcr.io/dexidp/dex:latest
  ports:
    - "5556:5556"
  volumes:
    - ./dex-config.yaml:/etc/dex/config.yaml:ro
  command: dex serve /etc/dex/config.yaml
  networks:
    - argocd-net
  restart: unless-stopped

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  argocd-server:
5    image: quay.io/argoproj/argocd:latest
6    command: argocd-server
7    ports:
8      - "8080:8080"
9      - "8443:8443"
10    environment:
11      ARGOCD_REDIS_ADDR: redis:6379
12      ARGOCD_REPO_SERVER_ADDR: argocd-repo-server:8081
13    volumes:
14      - argocd_server:/home/argocd
15    depends_on:
16      - redis
17      - argocd-repo-server
18    networks:
19      - argocd-net
20    restart: unless-stopped
21
22  argocd-repo-server:
23    image: quay.io/argoproj/argocd:latest
24    command: argocd-repo-server
25    ports:
26      - "8081:8081"
27    environment:
28      ARGOCD_REDIS_ADDR: redis:6379
29    volumes:
30      - argocd_repo:/home/argocd
31    depends_on:
32      - redis
33    networks:
34      - argocd-net
35    restart: unless-stopped
36
37  argocd-controller:
38    image: quay.io/argoproj/argocd:latest
39    command: argocd-application-controller
40    environment:
41      ARGOCD_REDIS_ADDR: redis:6379
42      ARGOCD_REPO_SERVER_ADDR: argocd-repo-server:8081
43    volumes:
44      - argocd_controller:/home/argocd
45    depends_on:
46      - redis
47      - argocd-repo-server
48    networks:
49      - argocd-net
50    restart: unless-stopped
51
52  redis:
53    image: redis:7-alpine
54    volumes:
55      - redis_data:/data
56    networks:
57      - argocd-net
58    restart: unless-stopped
59
60  dex:
61    image: ghcr.io/dexidp/dex:latest
62    ports:
63      - "5556:5556"
64    volumes:
65      - ./dex-config.yaml:/etc/dex/config.yaml:ro
66    command: dex serve /etc/dex/config.yaml
67    networks:
68      - argocd-net
69    restart: unless-stopped
70
71volumes:
72  argocd_server:
73  argocd_repo:
74  argocd_controller:
75  redis_data:
76
77networks:
78  argocd-net:
79    driver: bridge
80EOF
81
82# 2. Create the .env file
83cat > .env << 'EOF'
84# Argo CD Configuration
85ARGOCD_ADMIN_PASSWORD=secure_admin_password
86
87# Dex OIDC Configuration
88DEX_GITHUB_CLIENT_ID=xxx
89DEX_GITHUB_CLIENT_SECRET=xxx
90EOF
91
92# 3. Start the services
93docker compose up -d
94
95# 4. View logs
96docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/argocd-stack/run | bash

Troubleshooting

  • Application stuck in 'Progressing' state: Check if Kubernetes resources have sufficient CPU/memory quotas and verify image pull secrets exist
  • Repository connection failed with authentication error: Ensure Git credentials are properly configured in Argo CD settings or SSH keys are correctly added
  • Sync operation fails with 'resource mapping not found': Update Argo CD to latest version or install required CRDs in target cluster
  • Web UI shows 'Unauthorized' after login: Verify Dex configuration matches identity provider settings and callback URLs are correctly configured
  • Controller high memory usage: Increase resource limits or reduce application refresh interval in argocd-cm ConfigMap to decrease polling frequency
  • Applications not auto-syncing despite configuration: Check webhook configuration in Git repository and verify network connectivity between Git provider and Argo CD

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

argocd-serverargocd-repo-serverargocd-controllerredisdex

Tags

#argocd#gitops#kubernetes#cd#declarative

Category

DevOps & CI/CD

Related Recipes

Ad Space