gitlab-stack-config-generator

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

mkdir -p ./config
chmod 755 ./config

Step 2: Create Service Directories

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

mkdir -p ./config/nginx
mkdir -p ./config/postgres
mkdir -p

Directory Structure:

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:

# 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):

# Check ownership
find . -user root -type f
 
# Fix if needed
sudo chown -R $(id -u):$(id -g) .

Validation

Before deployment, always run:

# 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

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:

Step 4: Update .env

Add all required variables:

Step 5: Update .env.example

CRITICAL: Must match .env exactly:

Step 6: Update docker-compose.yml

Add volume mount for config:

Phase 5: Configuration Validation

Step 1: Syntax Validation

For each config file type:

Nginx:

PostgreSQL:

Redis:

Step 2: Secret Detection (CRITICAL)

Scan all config files for secrets:

Step 3: Path Validation

Check that all referenced paths exist:

1. Config files reference other files?
2. Volume mounts in docker-compose.yml?
3. All paths exist?

Step 4: .env Synchronization (CRITICAL)

Step 5: Docker Validation

CRITICAL: Use docker-validation skill:

Address all findings before completing.

Phase 6: Template Selection

Step 1: Offer Templates

For nginx, PostgreSQL, Redis, offer these options:

Nginx Templates:

1. Simple Reverse Proxy (default)

   • Basic proxy to backend service
   • No SSL
   • Minimal config

2. SSL Termination

   • HTTPS enabled
   • SSL certificates from Docker secrets
   • HTTP to HTTPS redirect

3. Static + Proxy

   • Serve static files
   • Proxy API requests
   • Caching headers

4. Custom

   • User provides requirements
   • Generate custom config

PostgreSQL Templates:

1. Basic (default)

   • Standard settings
   • Simple init.sql
   • Development friendly

2. Production

   • Optimized settings
   • Connection pooling
   • Performance tuning

3. With Extensions

   • PostGIS, UUID, etc.
   • Extension-specific config
   • Init scripts for extensions

4. Custom

   • User-specified

Redis Templates:

1. Cache (default)

   • No persistence
   • Memory-only
   • Fast

2. Persistent

   • RDB snapshots
   • AOF logging
   • Data durability

3. Pub/Sub

   • Optimized for messaging
   • No persistence
   • High throughput

4. Custom

   • User requirements

Step 2: Generate from Template

Based on user selection, generate appropriate config with:

• Required .env variables
• Proper docker-compose.yml integration
• README section documenting the config

Phase 7: Validation Report

After generation, provide comprehensive report:

Service-Specific Patterns

Nginx Configuration

Always include:

• Environment variable placeholders
• Upstream backend reference
• Basic security headers
• Logging configuration

Never include:

• Hardcoded IPs or hosts
• SSL certificate content (use Docker secrets)
• Passwords or tokens

Example variables:

PostgreSQL Configuration

Always include:

• Init scripts for database/user creation
• Basic performance tuning
• Connection limits
• Logging settings

Never include:

• Passwords (use Docker secrets)
• Production database names in dev
• Hardcoded connection strings

Example variables:

Redis Configuration

Always include:

• Persistence settings
• Memory limits
• Network bindings

Never include:

• Passwords (use Docker secrets if needed)
• Hardcoded master/slave IPs

Example variables:

Integration with Companion Skills

secrets-manager

When to call:

• Secrets detected in config files → CRITICAL
• Need to reference secrets in configs
• SSL certificates or private keys needed

docker-validation

When to call:

• After updating docker-compose.yml (ALWAYS)
• Before completing generation
• User requests validation

stack-validator

When to call:

• After generation complete
• Validate entire stack
• Ensure all patterns followed

Important Notes

• No Secrets: NEVER put secrets in config files
• .env Source: All configuration from .env
• .env Sync: .env and .env.example must match
• Docker Validation: Always use docker-validation skill
• CLAUDE.md Rule: Must specify no "Claude" in commit messages
• Templates Optional: User chooses defaults or custom
• Path Validation: All paths must exist

Example Workflow

This skill generates service configurations following GitLab stack patterns with strict validation._