Merakit-Deploy/gitea

Gitea Deployment Template

Production-ready Gitea deployment with automated DNS, environment generation, and health checking.

Features

• Automated Environment Generation: Random subdomain and secure password generation
• DNS Management: Automatic Cloudflare DNS record creation
• Health Checking: Automated deployment verification
• Rollback Support: Automatic rollback on deployment failure
• Webhook Notifications: Optional webhook notifications for deployment events
• Deployment Tracking: Track and manage all deployments
• Dry-Run Mode: Preview changes before applying

Architecture

gitea/
├── docker-compose.yml          # Docker Compose configuration
├── .env                        # Environment variables (generated)
├── deploy.py                   # Main deployment script
├── destroy.py                  # Deployment destruction script
├── requirements.txt            # Python dependencies
├── deployments/                # Deployment configuration tracking
├── logs/                       # Deployment logs
│   ├── success/               # Successful deployment logs
│   └── failed/                # Failed deployment logs
└── gitea_deployer/            # Python deployment module
    ├── config.py              # Configuration management
    ├── orchestrator.py        # Deployment orchestration
    ├── env_generator.py       # Environment generation
    ├── dns_manager.py         # DNS management (Cloudflare)
    ├── docker_manager.py      # Docker operations
    ├── health.py              # Health checking
    ├── webhooks.py            # Webhook notifications
    ├── deployment_logger.py   # File logging
    └── deployment_config_manager.py  # Deployment tracking

Prerequisites

• Docker and Docker Compose
• Python 3.9+
• Cloudflare account with API token
• Traefik reverse proxy running on proxy network
• /usr/share/dict/words file (install words package)

Installation

1. Install Python dependencies:

pip3 install -r requirements.txt

2. Set environment variables:

export CLOUDFLARE_API_TOKEN="your-token"
export CLOUDFLARE_ZONE_ID="your-zone-id"

3. Ensure Docker proxy network exists:

docker network create proxy

Usage

Deploy Gitea

Basic deployment:

./deploy.py

With options:

# Dry-run mode (preview only)
./deploy.py --dry-run

# Debug mode
./deploy.py --log-level DEBUG

# With webhook notifications
./deploy.py --webhook-url https://hooks.slack.com/your-webhook

# Custom retry count for DNS conflicts
./deploy.py --max-retries 5

List Deployments

./destroy.py --list

Destroy Deployment

By subdomain:

./destroy.py --subdomain my-gitea-site

By URL:

./destroy.py --url my-gitea-site.merakit.my

With options:

# Skip confirmation
./destroy.py --subdomain my-gitea-site --yes

# Dry-run mode
./destroy.py --subdomain my-gitea-site --dry-run

# Keep deployment config file
./destroy.py --subdomain my-gitea-site --keep-config

Environment Variables

Required

• CLOUDFLARE_API_TOKEN: Cloudflare API token with DNS edit permissions
• CLOUDFLARE_ZONE_ID: Cloudflare zone ID for your domain

Optional

• DEPLOYMENT_WEBHOOK_URL: Webhook URL for deployment notifications
• DEPLOYMENT_MAX_RETRIES: Max retries for DNS conflicts (default: 3)
• DEPLOYMENT_HEALTHCHECK_TIMEOUT: Health check timeout in seconds (default: 60)
• DEPLOYMENT_HEALTHCHECK_INTERVAL: Health check interval in seconds (default: 10)

Configuration

Docker Compose Services

• postgres: PostgreSQL 16 database
• gitea: Gitea 1.21 Git service

Generated Values

The deployment automatically generates:

• Random subdomain (e.g., awesome-robot.merakit.my)
• Database name with prefix angali_{random}_{app}_{subdomain}
• Database user with same pattern
• Secure memorable passwords (3-word format)

Customization

Edit .env file to customize:

• GITEA_VERSION: Gitea version (default: 1.21)
• POSTGRES_VERSION: PostgreSQL version (default: 16-alpine)
• DISABLE_REGISTRATION: Disable user registration (default: false)
• DOMAIN: Base domain (default: merakit.my)

Deployment Workflow

1. Validation: Check dependencies and configuration
2. Environment Generation: Generate random subdomain and credentials
3. DNS Setup: Create Cloudflare DNS record
4. Container Deployment: Pull images and start services
5. Health Check: Verify deployment is accessible
6. Logging: Record deployment success/failure

Rollback

If deployment fails at any stage, automatic rollback occurs:

1. Stop and remove containers
2. Remove DNS records
3. Restore previous .env file

Troubleshooting

DNS Conflicts

If subdomain is already taken, the script automatically retries with a new random subdomain (up to max_retries times).

Health Check Failures

Health checks wait up to 60 seconds by default. Increase timeout if needed:

export DEPLOYMENT_HEALTHCHECK_TIMEOUT=120
./deploy.py

Missing Dictionary File

Install the words package:

# Ubuntu/Debian
sudo apt-get install wamerican

# RHEL/CentOS
sudo yum install words

Logs

• Success logs: logs/success/success_{url}_{timestamp}.txt
• Failure logs: logs/failed/failed_{url}_{timestamp}.txt

Deployment Tracking

Deployment configurations are saved in deployments/ directory:

• Format: {subdomain}_{timestamp}.json
• Contains: containers, volumes, networks, DNS records
• Used by destroy.py for cleanup

Security Notes

• Passwords are generated using cryptographically secure random generation
• API tokens are never logged or displayed
• SSL verification is enabled by default (use --no-verify-ssl only for testing)
• Database credentials are automatically generated per deployment

Integration

Webhook Notifications

The script can send webhook notifications for:

• deployment_started: When deployment begins
• dns_added: When DNS record is created
• health_check_passed: When health check succeeds
• deployment_success: When deployment completes
• deployment_failed: When deployment fails

Example webhook payload:

{
  "event_type": "deployment_success",
  "timestamp": "2024-01-01T12:00:00Z",
  "subdomain": "awesome-robot",
  "url": "awesome-robot.merakit.my",
  "message": "Deployment successful for awesome-robot.merakit.my",
  "metadata": {
    "duration": 45.2
  }
}

License

This deployment template is part of the infrastructure management system.