ljwx-harbor/gitlab/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is the GitLab maintenance module within the macOS toolchain, providing a complete GitLab code hosting platform management solution with service deployment, automated backups, health monitoring, and one-click recovery capabilities.

Core Architecture

The system consists of several key components:

1. GitLab Service: Docker-based GitLab CE instance with persistent data storage
2. GitLab Runner: CI/CD execution environment with Docker and Shell executors
3. Data Protection: Automated backup and recovery system with dual scheduling (cron + launchd)
4. Configuration Management: Environment-based configuration with customizable settings

Service Configuration

• GitLab URL: http://192.168.1.83:8890
• SSH Port: 8929
• Data Directory: ~/ops/data/gitlab
• Backup Directory: ~/ops/backups/gitlab
• Configuration Directory: ./config

Essential Commands

Primary Operations

# Start GitLab service
./gitlab-data-protection.sh start

# Stop GitLab service
./gitlab-data-protection.sh stop

# Restart GitLab service
./gitlab-data-protection.sh restart

# Health check
./gitlab-data-protection.sh health

# View service statistics
./gitlab-data-protection.sh stats

# Initialize environment and scheduled tasks
./gitlab-data-protection.sh setup

Backup and Recovery

# Manual backup with timestamp
./gitlab-backup.sh

# Manual backup with custom name
./gitlab-backup.sh my-backup-$(date +%Y%m%d)

# List available backups
./gitlab-restore.sh

# Restore from specific backup
./gitlab-restore.sh gitlab-20231019-120000.tar.gz

GitLab Runner Management

# Register runners (simple version)
./register-runner-simple.sh

# Register runners (full version)
./register-runner.sh

# Setup CI/CD environment for project
./setup-ci-env.sh <project-name> [dev|prod]

Docker Operations

# Start all services
docker-compose up -d

# Stop all services
docker-compose down

# View service logs
docker logs -f gitlab-ce
docker logs -f gitlab-runner

# Execute commands in GitLab container
docker exec -it gitlab-ce /bin/bash

# Execute commands in Runner container
docker exec -it gitlab-runner gitlab-runner list

Directory Structure

gitlab/
├── docker-compose.yml              # Main service configuration
├── .env.example                    # Environment variable template
├── gitlab-data-protection.sh       # Primary management script
├── gitlab-backup.sh                # Backup operations script
├── gitlab-restore.sh               # Recovery operations script
├── register-runner.sh              # Full runner registration
├── register-runner-simple.sh       # Simplified runner registration
├── setup-ci-env.sh                 # CI/CD environment setup
├── config/                         # GitLab configuration directory
├── gitlab-runner-config/           # Runner configuration directory
│   └── config.toml                 # Runner settings
├── ci-templates/                   # CI/CD pipeline templates
│   ├── .gitlab-ci.yml.stock       # Full production pipeline
│   └── .gitlab-ci.yml.simple      # Simplified pipeline
├── manual-runner-setup.md          # Manual setup guide
├── CICD-SUMMARY.md                 # Configuration summary
└── README.md                       # Detailed documentation

Configuration Management

Environment Variables

Copy .env.example to .env and customize:

Key variables:

• GITLAB_DOMAIN: Server domain (default: 192.168.1.83)
• GITLAB_HTTP_PORT: Web UI port (default: 8890)
• GITLAB_SSH_PORT: SSH port (default: 8929)
• GITLAB_BACKUP_RETENTION_DAYS: Backup retention period (default: 30)
• GITLAB_BACKUP_INTERVAL_HOURS: Backup frequency (default: 6)

GitLab Configuration

The main GitLab configuration is handled through GITLAB_OMNIBUS_CONFIG in docker-compose.yml. This includes:

• External URL and SSH port settings
• Nginx configuration
• Optional SMTP email settings
• SSL/TLS configuration (if needed)

CI/CD Integration

Runner Registration

Runners are registered using the provided scripts:

• Docker Runner: For containerized builds and deployments
• Shell Runner: For local script execution and system integration

Pipeline Templates

Two CI/CD templates are provided:

1. Full Pipeline (.gitlab-ci.yml.stock): Production-ready with lint, test, build, security, and deploy stages
2. Simple Pipeline (.gitlab-ci.yml.simple): Basic test, build, and deploy workflow

Environment Setup

Use setup-ci-env.sh to configure project-specific environment variables for CI/CD pipelines, supporting both development and production environments.

Backup and Recovery System

Automated Backups

The system provides dual-scheduled backups:

• Cron Jobs: Traditional Unix scheduling
• Launchd Services: macOS native scheduling

Backup includes:

• GitLab configuration files
• Application data and repositories
• PostgreSQL database
• Docker Compose configurations

Recovery Process

The recovery system includes:

• Safety Backups: Automatic backup before any restore operation
• Integrity Checks: Post-recovery validation
• Rollback Support: Ability to revert failed restores

Development Workflow

Service Management

1. Initialization: Run ./gitlab-data-protection.sh setup to configure environment and scheduled tasks
2. Service Start: Use ./gitlab-data-protection.sh start to launch GitLab and Runner services
3. Health Monitoring: Regular health checks with ./gitlab-data-protection.sh health
4. Backup Operations: Automated every 6 hours, manual backup available on demand

CI/CD Development

1. Project Setup: Create GitLab project and copy appropriate CI/CD template
2. Runner Registration: Register runners using provided scripts
3. Environment Configuration: Set up project-specific variables with setup-ci-env.sh
4. Pipeline Testing: Commit and push to trigger CI/CD pipelines

Maintenance Operations

• Log Monitoring: Check ~/ops/logs/gitlab-protection.log for service activities
• Backup Management: Monitor ~/ops/backups/gitlab/ for backup files
• Resource Monitoring: Use docker stats gitlab-ce to monitor resource usage

Troubleshooting

Common Issues

1. GitLab Startup Delay: First-time startup requires 5-15 minutes
2. Port Conflicts: Ensure ports 8890 and 8929 are available
3. Runner Registration: Confirm GitLab is fully running before registering runners
4. Permission Issues: Ensure scripts have execute permissions (chmod +x *.sh)

Debug Commands

# Check service status
docker ps | grep gitlab

# View service logs
docker logs gitlab-ce
docker logs gitlab-runner

# Test GitLab connectivity
curl -f http://localhost:8890/-/health

# Verify runner status
docker exec gitlab-runner gitlab-runner list

Integration Points

This GitLab module integrates with the broader macOS DevOps toolchain:

• Data Storage: Uses ~/ops/data/ for persistent storage
• Backup System: Integrates with centralized backup infrastructure
• Logging: Uses ~/ops/logs/ for unified logging
• Networking: Configured to work with existing service network (192.168.1.83)

Security Considerations

• Change default admin password from admin123 in production
• Configure firewall rules for ports 8890 and 8929
• Use HTTPS configuration for production deployments
• Regularly update GitLab to latest stable version
• Implement proper access controls and user management