GitLab Stack Config Generator

What this skill does

# GitLab Stack Config Generator

This skill generates and manages service-specific configuration files for GitLab stack projects, ensuring configurations follow proper patterns, use .env for all variables, and never contain secrets.

## When to Use This Skill

Activate this skill when the user requests:
- Generate configuration files for services (nginx, PostgreSQL, Redis, etc.)
- Create config templates for new services
- Set up ./config directory structure
- Validate existing configuration files
- Ensure configs use .env variables correctly
- Check that configs don't contain secrets
- Set up project meta files (CLAUDE.md, .gitignore, .dockerignore)
- Sync .env and .env.example

## Core Configuration Principles

**CRITICAL RULES**:

1. **./env is Configuration Source**: All configuration variables in .env (NOT in config files)
2. **No Secrets in Configs**: NEVER put secrets in configuration files (use secrets-manager)
3. **Service Directories**: Each service gets `./config/service-name/` directory
4. **Flat Inside Service**: Config files flat inside service directory
5. **.env Sync**: .env and .env.example MUST always match
6. **Path Validation**: All referenced paths must exist
7. **Docker Validation**: Use docker-validation skill for Docker configs
8. **Project Meta Files**: CLAUDE.md, .gitignore, .dockerignore required

## Configuration Workflow

### Phase 1: Understanding Requirements

**Step 1: Determine What to Generate**

Ask the user (or infer):
- Which services need configuration?
- New configs or updating existing?
- Production, development, or both?
- Which templates to use (if any)?

**Step 2: Check Current State**

1. Does ./config directory exist?
2. Does .env exist?
3. Does .env.example exist?
4. Do service directories already exist?
5. Are meta files present (CLAUDE.md, .gitignore, .dockerignore)?

### Phase 2: Directory Structure Setup

**Step 1: Create ./config Directory**

```bash
mkdir -p ./config
chmod 755 ./config
```

**Step 2: Create Service Directories**

For each service (e.g., nginx, postgres, redis):

```bash
mkdir -p ./config/nginx
mkdir -p ./config/postgres
mkdir -p ./config/redis
chmod 755 ./config/*
```

**Directory Structure**:
```
./config/
├── nginx/
│   ├── nginx.conf
│   ├── ssl/
│   │   └── (SSL configs, not certificates)
│   └── conf.d/
│       └── default.conf
├── postgres/
│   ├── postgresql.conf
│   └── init.sql
├── redis/
│   └── redis.conf
└── app/
    └── settings.yml
```

**Principles**:
- One directory per service
- Flat structure inside each service directory
- Subdirectories only when logically needed (e.g., nginx/ssl/, nginx/conf.d/)

### Phase 3: Meta Files Generation

**CRITICAL**: Always ensure these files exist

**Step 1: Generate CLAUDE.md**

Create `CLAUDE.md` in project root:

```markdown
# CLAUDE.md

This file provides guidance when working with code in this repository.

## Repository Purpose

[Brief description of the stack project]

## Stack Architecture

This is a GitLab stack project following these principles:

- **Configuration**: All variables in .env, configs in ./config
- **Secrets**: All secrets in ./secrets via Docker secrets
- **Structure**: Standard directories (./config, ./secrets, ./_temporary)
- **Docker**: Modern Docker Compose (no version field)
- **Ownership**: No root-owned files

## Working with This Stack

### Configuration Files

All service configurations are in `./config/[service-name]/` directories.
Configuration values are loaded from `.env` file.

### Environment Variables

- `.env` contains all configuration (NOT secrets)
- `.env.example` must match `.env` exactly (critical requirement)
- Update both files when adding new variables

### Secrets Management

All secrets are managed via Docker secrets:
- Location: `./secrets/` directory
- Never in .env or docker-compose.yml
- Use secrets-manager skill for secret operations

### Docker Commands

```bash
# Start stack
docker compose up -d

# View logs
docker compose logs -f

# Stop stack
docker compose down
```

## Important Rules

### Git Commits

**CRITICAL**: When creating commit messages, NEVER mention "Claude" or "Claude Code" in the commit message.

Good commit messages:
- "Add nginx configuration for SSL termination"
- "Update PostgreSQL settings for production"
- "Fix Redis persistence configuration"

Bad commit messages:
- "Claude added nginx config"  ❌
- "Asked Claude to update settings"  ❌

### File Permissions

All files must be owned by the current user (not root):
```bash
# Check ownership
find . -user root -type f

# Fix if needed
sudo chown -R $(id -u):$(id -g) .
```

### Validation

Before deployment, always run:
```bash
# Validate entire stack
[validation command]

# Check secrets
[secrets validation command]
```

## Directory Structure

```
./
├── docker-compose.yml      # Main compose file (NO version field)
├── .env                    # Configuration variables
├── .env.example            # Template (must match .env)
├── CLAUDE.md               # This file
├── .gitignore              # Git exclusions
├── .dockerignore           # Docker build exclusions
├── config/                 # Service configurations
│   ├── nginx/
│   ├── postgres/
│   └── redis/
├── secrets/                # Docker secrets (NOT in git)
│   └── .gitkeep
└── _temporary/             # Transient files (NOT in git)
```

## Skills Available

- **stack-validator**: Validate entire stack before deployment
- **secrets-manager**: Manage Docker secrets securely
- **config-generator**: Generate/update service configurations
- **docker-validation**: Validate Docker configs

---

*Last updated: [date]*
```

**Step 2: Generate/Update .gitignore**

```gitignore
# Secrets - NEVER commit
/secrets/
/secrets/*
!secrets/.gitkeep

# Environment
.env
.env.local
.env.*.local

# Temporary
/_temporary/
/_temporary/*

# Docker
.dockerignore

# IDE
.vscode/
.idea/
*.swp
*.swo
*~

# OS
.DS_Store
Thumbs.db

# Logs
*.log
logs/

# Build artifacts
dist/
build/
node_modules/
vendor/

# Backup files
*.backup
*.old
*.bak
```

**Step 3: Generate .dockerignore**

```dockerignore
# Git
.git/
.gitignore

# Environment
.env
.env.*

# Secrets
secrets/

# Temporary
_temporary/

# Documentation
*.md
CLAUDE.md

# IDE
.vscode/
.idea/

# OS
.DS_Store
Thumbs.db

# Dependencies (if not needed in build)
node_modules/
vendor/

# Logs
*.log
logs/
```

### Phase 4: Service Configuration Generation

**Common Services**: nginx, PostgreSQL, Redis

For each service, follow this pattern:

**Step 1: Determine Configuration Needs**

Ask user:
- Use template or custom?
- Which features to enable?
- Production or development settings?

**Step 2: Identify Required .env Variables**

For each service, list all .env variables needed:

Example for nginx:
- NGINX_PORT
- NGINX_HOST
- NGINX_SSL_ENABLED
- APP_HOST
- APP_PORT

**Step 3: Generate Configuration File**

**CRITICAL**: Use environment variable placeholders (`${VAR_NAME}`)

Example nginx.conf:
```nginx
# Nginx Configuration
# Loads variables from .env

upstream app {
    server ${APP_HOST}:${APP_PORT};
}

server {
    listen ${NGINX_PORT};
    server_name ${NGINX_HOST};

    # SSL configuration
    # SSL certificates loaded from Docker secrets
    # ssl_certificate /run/secrets/ssl_cert;
    # ssl_certificate_key /run/secrets/ssl_key;

    location / {
        proxy_pass http://app;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

**Step 4: Update .env**

Add all required variables:

```bash
# Nginx Configuration
NGINX_PORT=80
NGINX_HOST=localhost
NGINX_SSL_ENABLED=false
APP_HOST=app
APP_PORT=8080
```

**Step 5: Update .env.example**

**CRITICAL**: Must match .env exactly:

```bash
# Nginx Configuration
NGINX_PORT=80
NGINX_HOST=localhost
NGINX_SSL_ENABLED=false
APP_HOST=app
APP_PORT=8080
```

**Step 6: Update docker-compose.yml**

Add volume mount for config:

```yaml
services:
  nginx:
    image: nginx:alpine
    ports:
      - "${NGINX_PORT}:80"
    volumes:
      - ./config/nginx/