# ArgoCD GitOps Stack

> ArgoCD for GitOps continuous delivery with Gitea and sealed secrets

- Category: DevOps & CI/CD
- Difficulty: advanced
- Components: argocd, gitea, sealed-secrets, postgres
- Tags: argocd, gitops, kubernetes, gitea, cd, devops
- Source: https://docker.recipes/devops/argocd-gitops

## Overview

Argo CD is a declarative GitOps continuous delivery tool for Kubernetes that emerged from Intuit's need for better application deployment practices. Following the GitOps methodology, it uses Git repositories as the single source of truth for application definitions, automatically synchronizing Kubernetes cluster states with Git-stored manifests. This approach revolutionizes how teams manage deployments by making Git commits the primary mechanism for triggering infrastructure changes.

This GitOps stack combines Argo CD with Gitea for self-hosted Git repositories, PostgreSQL for reliable data persistence, and Redis for high-performance caching. Gitea serves as the lightweight Git service hosting your application manifests and Kubernetes YAML files, while Argo CD continuously monitors these repositories and applies changes to your clusters. The stack creates a complete on-premises GitOps pipeline where code commits automatically trigger deployments without complex CI/CD scripting.

Development teams transitioning from traditional deployment methods, platform engineers building internal developer platforms, and organizations requiring air-gapped or self-hosted solutions will find exceptional value in this combination. The stack eliminates the complexity of managing external Git services while providing enterprise-grade GitOps capabilities that scale from single clusters to multi-cluster environments with full audit trails and rollback capabilities.

## Features

- Declarative GitOps deployments with Git as single source of truth
- Multi-cluster application management from centralized Argo CD interface
- Self-hosted Git service with GitHub-like interface and webhook integration
- Automated drift detection and cluster state reconciliation
- Visual application topology with real-time health monitoring
- Git-based rollback capabilities with complete deployment history
- Pull request workflows for application changes through Gitea
- Resource-efficient PostgreSQL backend with ACID compliance for metadata storage

## Use cases

- Platform teams building self-hosted GitOps pipelines for Kubernetes deployments
- Organizations requiring air-gapped development environments with complete Git hosting
- Multi-cluster application delivery across development, staging, and production environments
- Teams migrating from Jenkins-based deployments to declarative GitOps workflows
- Startups needing cost-effective alternative to GitHub Enterprise plus external GitOps tools
- DevOps teams implementing infrastructure-as-code with Kubernetes manifest management
- Companies requiring audit trails and compliance tracking for all deployment activities

## Prerequisites

- Kubernetes cluster access with kubectl configured for Argo CD connectivity
- Minimum 2GB RAM and 2 CPU cores for running all stack components effectively
- Available ports 3000 (Gitea), 8080 (Argo CD), and 222 (Gitea SSH) on host system
- Understanding of Kubernetes manifests, YAML structure, and GitOps principles
- Git workflow knowledge including branching, pull requests, and webhook concepts
- Basic PostgreSQL administration skills for database maintenance and backups

## docker-compose.yml

```yaml
services:
  gitea:
    image: gitea/gitea:latest
    container_name: gitops-gitea
    restart: unless-stopped
    ports:
      - "${GITEA_HTTP:-3000}:3000"
      - "${GITEA_SSH:-222}:22"
    environment:
      - GITEA__database__DB_TYPE=postgres
      - GITEA__database__HOST=db:5432
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=gitea
      - GITEA__database__PASSWD=${DB_PASSWORD}
    volumes:
      - gitea_data:/data
    depends_on:
      - db

  argocd:
    image: quay.io/argoproj/argocd:latest
    container_name: argocd
    restart: unless-stopped
    ports:
      - "${ARGOCD_PORT:-8080}:8080"
    command: ["argocd-server", "--insecure"]
    environment:
      - ARGOCD_SERVER_INSECURE=true
    volumes:
      - argocd_data:/home/argocd

  argocd-repo-server:
    image: quay.io/argoproj/argocd:latest
    container_name: argocd-repo-server
    restart: unless-stopped
    command: ["argocd-repo-server"]
    volumes:
      - argocd_repo:/tmp

  argocd-application-controller:
    image: quay.io/argoproj/argocd:latest
    container_name: argocd-controller
    restart: unless-stopped
    command: ["argocd-application-controller"]

  redis:
    image: redis:7-alpine
    container_name: argocd-redis
    restart: unless-stopped

  db:
    image: postgres:15-alpine
    container_name: gitops-db
    restart: unless-stopped
    environment:
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=gitea
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  gitea_data:
  argocd_data:
  argocd_repo:
  postgres_data:
```

## .env

```bash
# ArgoCD GitOps Stack
GITEA_HTTP=3000
GITEA_SSH=222
ARGOCD_PORT=8080

# Database
DB_PASSWORD=gitops_password
```

## Usage notes

- Gitea at http://localhost:3000 for Git repos
- ArgoCD at http://localhost:8080
- Initial ArgoCD password: argocd admin initial-password
- Connect ArgoCD to Gitea repositories
- Define applications in Git for GitOps workflow
- ArgoCD syncs Kubernetes manifests from Git

## Troubleshooting

- Argo CD shows 'Unknown' application health: Verify Kubernetes cluster connectivity and ensure kubectl context is properly configured for the target cluster
- Gitea webhook delivery failures: Check that Argo CD repository server can reach Gitea on port 3000 and webhook URLs use container network names instead of localhost
- Application sync stuck in 'Progressing' state: Examine resource hooks and ensure Kubernetes resources don't have conflicting finalizers or validation errors
- Argo CD login shows 'Failed to get token': Reset admin password using 'argocd admin initial-password' command or check Redis connectivity for session storage
- Repository connection timeout errors: Verify Gitea SSH key configuration and ensure the argocd-repo-server container can resolve Gitea hostname
- PostgreSQL connection refused during Gitea startup: Wait for database initialization to complete or check DB_PASSWORD environment variable matches between services

