project-name/
├── .git/                       # Git repository
│   ├── hooks/                  # Git hooks (validation scripts)
│   └── config                  # Git configuration
├── config/                     # Service configurations
│   ├── nginx/                  # Nginx configs (if needed)
│   ├── postgres/               # PostgreSQL configs (if needed)
│   └── redis/                  # Redis configs (if needed)
├── secrets/                    # Docker secrets files
│   └── .gitkeep               # Keep directory in git
├── _temporary/                 # Temporary files (gitignored)
├── scripts/                    # Validation and utility scripts
│   ├── pre-commit              # Pre-commit validation hook
│   ├── validate-stack.sh       # Full stack validation
│   └── setup-hooks.sh          # Hook installation script
├── docs/                       # Project documentation
│   ├── decisions/              # Architecture decision records
│   ├── setup.md                # Setup instructions
│   └── services.md             # Service documentation
├── docker-compose.yml          # Main compose file
├── .env.example                # Environment template
├── .gitignore                  # Git exclusions
├── .dockerignore               # Docker exclusions
├── CLAUDE.md                   # Claude Code instructions
└── README.md                   # Project overview

# Set main as branch name
git config init.defaultBranch main

# Set ff-only merge strategy
git config pull.ff only
git config merge.ff only

# Ensure no rebase by default
git config pull.rebase false

# Set user info if not set globally
git config user.name "User Name"
git config user.email "user@example.com"

# Secrets - NEVER commit
secrets/*
!secrets/.gitkeep
*.key
*.pem
*.crt
*.p12
*.pfx

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

# Temporary files
_temporary/
*.tmp
*.temp
.cache/

# Docker
.docker/

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

# OS
.DS_Store
Thumbs.db
*.log

# Backup files
*.bak
*.backup

.git
.gitignore
README.md
docs/
_temporary/
*.md
.env
.env.example
secrets/
.vscode/
.idea/

#!/usr/bin/env bash
set -euo pipefail

echo "=== GitLab Stack Validation ==="
echo

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

ERRORS=0

echo "1. Validating stack structure..."
if ! claude-code-cli run stack-validator; then
    echo -e "${RED}✗ Stack validation failed${NC}"
    ((ERRORS++))
else
    echo -e "${GREEN}✓ Stack validation passed${NC}"
fi
echo

echo "2. Validating secrets configuration..."
if ! claude-code-cli run secrets-manager --validate; then
    echo -e "${RED}✗ Secrets validation failed${NC}"
    ((ERRORS++))
else
    echo -e "${GREEN}✓ Secrets validation passed${NC}"
fi
echo

echo "3. Validating Docker configuration..."
if ! claude-code-cli run docker-validation; then
    echo -e "${RED}✗ Docker validation failed${NC}"
    ((ERRORS++))
else
    echo -e "${GREEN}✓ Docker validation passed${NC}"
fi
echo

if [ $ERRORS -gt 0 ]; then
    echo -e "${RED}Validation failed with $ERRORS error(s)${NC}"
    exit 1
fi

echo -e "${GREEN}All validations passed!${NC}"
exit 0

#!/usr/bin/env bash
set -euo pipefail

echo "Running pre-commit validation..."

# Check for secrets in staged files
if git diff --cached --name-only | grep -qE "secrets/.*[^.gitkeep]|\.env$"; then
    echo "ERROR: Attempting to commit secrets or .env file!"
    echo "Secrets should never be committed to git."
    exit 1
fi

# Check for root-owned files
if find . -user root -not -path "./.git/*" 2>/dev/null | grep -q .; then
    echo "ERROR: Root-owned files detected!"
    echo "All files should be owned by the user running Docker."
    exit 1
fi

# Run quick validation (if available)
if [ -x "./scripts/validate-stack.sh" ]; then
    echo "Running stack validation..."
    if ! ./scripts/validate-stack.sh; then
        echo "ERROR: Stack validation failed!"
        echo "Fix issues before committing, or use 'git commit --no-verify' to skip."
        exit 1
    fi
fi

echo "Pre-commit validation passed!"
exit 0

#!/usr/bin/env bash
set -euo pipefail

echo "Installing git hooks..."

# Check if .git directory exists
if [ ! -d ".git" ]; then
    echo "ERROR: Not a git repository!"
    exit 1
fi

# Install pre-commit hook
if [ -f "scripts/pre-commit" ]; then
    cp scripts/pre-commit .git/hooks/pre-commit
    chmod +x .git/hooks/pre-commit
    echo "✓ Installed pre-commit hook"
else
    echo "✗ scripts/pre-commit not found"
    exit 1
fi

echo "Git hooks installed successfully!"

services:
  # Services will be added based on requirements

  # Example: nginx service
  nginx:
    image: nginx:alpine
    container_name: ${PROJECT_NAME:-project}_nginx
    restart: unless-stopped
    ports:
      - "${NGINX_PORT:-80}:80"
    volumes:
      - ./config/nginx:/etc/nginx/conf.d:ro
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

# Secrets will be defined here when needed
secrets: {}

# Volumes for persistent data
volumes: {}

# Project Configuration
PROJECT_NAME=myproject

# Service Ports
NGINX_PORT=80
# Add more as needed

# Database Configuration (if applicable)
# POSTGRES_PORT=5432
# REDIS_PORT=6379

# IMPORTANT: Copy this file to .env and configure for your environment
# .env is gitignored and should contain actual secrets

# Setup Instructions

## Prerequisites

- Docker Engine 20.10+
- Docker Compose V2
- Git

## Initial Setup

1. Clone the repository:
   ```bash
   git clone <repository-url>
   cd <project-name>

./scripts/validate-stack.sh

#### 8.2 Create docs/services.md

Document all services:
```markdown
# Services Documentation

## Service Overview

| Service | Port | Purpose | Configuration |
|---------|------|---------|---------------|
| nginx | 80 | Web server | ./config/nginx |
| ... | ... | ... | ... |

## Service Details

### Nginx

**Image**: nginx:alpine
**Purpose**: Web server and reverse proxy
**Configuration**: ./config/nginx/
**Secrets**: None
**Volumes**:
- ./config/nginx:/etc/nginx/conf.d:ro

### [Other Services]

Document each service similarly...

# 1. Stack Architecture

**Date**: YYYY-MM-DD

## Status

Accepted

## Context

This project uses GitLab Stack Management patterns to ensure:
- Consistent configuration management
- Secure secrets handling
- Proper file ownership
- Validated deployments

## Decision

We will follow these principles:
1. All configuration in docker-compose.yml and ./config
2. All secrets in ./secrets and Docker secrets
3. docker-entrypoint.sh only when necessary
4. No root-owned files
5. ./_temporary for transient files
6. Complete validation before deployment

## Consequences

**Positive**:
- Consistent structure across all stacks
- Automated validation prevents issues
- Secure by default
- Easy to maintain and update

**Negative**:
- Initial setup requires more steps
- Must follow strict patterns
- Validation gates can slow rapid iteration

## Compliance

- stack-validator: Ensures structure compliance
- secrets-manager: Ensures secure secrets
- docker-validation: Ensures Docker best practices

# CLAUDE.md

This file provides guidance to Claude Code when working with this stack project.

## Project Structure

This is a GitLab Stack project following strict patterns:
- Configuration: docker-compose.yml and ./config/
- Secrets: ./secrets/ and Docker secrets
- Temporary: ./_temporary/ (gitignored)
- Documentation: ./docs/
- Validation: ./scripts/

## Required Skills

This project uses these Claude Code skills:
- **stack-validator**: Validate entire stack structure
- **secrets-manager**: Manage Docker secrets securely
- **docker-validation**: Validate Docker configurations
- **config-generator**: Generate service configs

## Git Configuration

**Branch**: main
**Merge Strategy**: ff-only (fast-forward only)
**Hooks**: Pre-commit validation enabled

## Validation Requirements

BEFORE any git commit, ALL these must pass:
1. stack-validator reports NO issues
2. secrets-manager is satisfied
3. docker-validation is satisfied
4. No root-owned files exist
5. No secrets in .env or docker-compose.yml environment

## Making Changes

### Adding a Service

1. Update docker-compose.yml
2. Use config-generator to create configs
3. Use secrets-manager to handle secrets
4. Run ./scripts/validate-stack.sh
5. Fix ALL issues before committing
6. NEVER commit if validation fails

### Modifying Configuration

1. Edit configuration files
2. Validate with docker-validation
3. Run ./scripts/validate-stack.sh
4. Fix ALL issues before committing

### Working with Secrets

1. Use secrets-manager for ALL secret operations
2. NEVER put secrets in .env or docker-compose.yml
3. Use Docker secrets or ./secrets/ directory
4. Validate with secrets-manager before committing

## Commit Standards

**Pre-commit Hook**: Automatically validates before commit
**Skip Hook**: `git commit --no-verify` (emergency only)
**Commit Messages**: Use conventional commits format

Example:

## Important Rules

1. NEVER commit secrets to git
2. NEVER create root-owned files
3. NEVER skip validation without asking
4. NEVER use workarounds - ask user instead
5. ALWAYS run validation before committing
6. ALWAYS document decisions in ./docs/decisions/
7. ALWAYS use ff-only merge strategy
8. ALWAYS use main as branch name

## Troubleshooting

### Validation Fails

1. Review validation output
2. Use respective skill to investigate (stack-validator, secrets-manager, docker-validation)
3. Fix reported issues
4. Re-run validation
5. Ask user if stuck - NEVER use workarounds

### Git Conflicts

1. NEVER use rebase without explicit permission
2. Use ff-only merges
3. Ask user how to resolve conflicts

### Permission Issues

1. Check file ownership: `find . -user root`
2. Fix with: `sudo chown -R $USER:$USER .`
3. Validate with stack-validator

## Resources

- Stack Validator Documentation
- Secrets Manager Documentation
- Docker Validation Documentation
- Config Generator Documentation

# Project Name

Brief description of the project.

## Quick Start

```bash
# Clone repository
git clone <url>
cd <project-name>

# Copy environment template
cp .env.example .env

# Configure environment (edit .env)
nano .env

# Install git hooks
./scripts/setup-hooks.sh

# Validate stack
./scripts/validate-stack.sh

# Start services
docker compose up -d

.
├── config/          # Service configurations
├── secrets/         # Docker secrets (gitignored except .gitkeep)
├── _temporary/      # Temporary files (gitignored)
├── scripts/         # Validation and utility scripts
├── docs/            # Project documentation
└── docker-compose.yml

# Full validation
./scripts/validate-stack.sh

# Pre-commit validation (automatic)
git commit -m "message"

find . -user root -not -path "./.git/*"

sudo chown -R $USER:$USER .

### Phase 9: Final Validation

#### 9.1 Run Complete Validation

Execute full validation workflow:

```bash
# Run validation script
./scripts/validate-stack.sh

# Stage all files
git add .

# Commit (pre-commit hook will validate)
git commit -m "feat: initial stack setup

- Created directory structure
- Configured git with main branch and ff-only
- Set up validation scripts and hooks
- Generated docker-compose.yml
- Created service configurations
- Set up secrets management
- Added comprehensive documentation"

# Push to remote (if configured)
git push -u origin main

User: "Create a new stack for a web application with nginx"
Assistant: "I'll create a new web stack with nginx. Let me gather some information first."

**Questions**:
1. "What's the project name?"
   User: "mywebapp"

2. "Do you have a remote git repository URL?"
   User: "https://gitlab.com/user/mywebapp.git"

3. "What environment is this for?"
   User: "production"

**Actions**:
1. Create directory structure
2. Initialize git and connect to remote
3. Configure git (main branch, ff-only)
4. Create docker-compose.yml with nginx
5. Use docker-validation to validate
6. Use config-generator to create nginx config
7. Create validation scripts
8. Install git hooks
9. Generate all documentation
10. Run full validation
11. Report status

**Completion**:
"Stack creation complete! All validations passed:
✓ stack-validator: NO issues
✓ secrets-manager: NO issues (no secrets needed)
✓ docker-validation: NO issues

Next steps:
1. Review generated files
2. Customize .env from .env.example
3. Run: docker compose up -d"

User: "Create a stack with nginx, PostgreSQL, and Redis"
Assistant: "I'll create a full application stack. Let me gather information."

**Questions**:
1. "Project name?" → "myapp"
2. "Remote repository?" → "Yes, https://gitlab.com/user/myapp.git"
3. "Environment?" → "production"

**Actions**:
1. Create directory structure with config/{nginx,postgres,redis}
2. Initialize git, connect remote, configure (main, ff-only)
3. Create docker-compose.yml with all three services
4. Validate with docker-validation
5. Use config-generator for each service:
   - nginx production config
   - PostgreSQL production config
   - Redis production config
6. Use secrets-manager for:
   - PostgreSQL password
   - Redis password
   - Create Docker secrets
7. Create validation scripts and install hooks
8. Generate all documentation
9. Run full validation (stack-validator, secrets-manager, docker-validation)
10. Initial commit

**Completion**:
"Stack creation complete! All validations passed:
✓ stack-validator: NO issues
✓ secrets-manager: All secrets properly configured
✓ docker-validation: NO issues

Services configured:
- nginx (port 80)
- PostgreSQL (port 5432, password in Docker secret)
- Redis (port 6379, password in Docker secret)

Next steps:
1. Review secrets in ./secrets/
2. Customize .env from .env.example
3. Run: docker compose up -d"