chore: claude.md
This commit is contained in:
258
Projects/kompose/CLAUDE.md
Normal file
258
Projects/kompose/CLAUDE.md
Normal file
@@ -0,0 +1,258 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
**Kompose** is a Bash-based orchestration tool for managing multiple Docker Compose stacks from a single repository. Each subdirectory represents a "stack" (a Docker Compose application), and the central `kompose.sh` script provides unified commands for lifecycle management, database operations, and custom hooks.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Core Components
|
||||
|
||||
- **`kompose.sh`**: Main orchestration script (bash) that manages all stacks
|
||||
- **Stack Directories**: Each directory (`auth/`, `blog/`, `track/`, etc.) represents a self-contained Docker Compose stack
|
||||
- **Environment Management**: Two-tier configuration system:
|
||||
- Root `.env`: Non-sensitive configuration and stack-scoped variables
|
||||
- `secrets.env`: Sensitive data (passwords, tokens) - generated from `secrets.env.template`
|
||||
- **Hooks System**: Per-stack lifecycle hooks in `<stack>/hooks.sh`
|
||||
|
||||
### Key Design Patterns
|
||||
|
||||
1. **Stack-Scoped Variables**: Configuration uses `{STACK_NAME}_{VARIABLE}` pattern (e.g., `TRACK_TRAEFIK_HOST`, `AUTH_DB_NAME`)
|
||||
2. **Shared Variables**: Common settings like `DB_USER`, `DB_HOST`, `NETWORK_NAME` shared across all stacks
|
||||
3. **Hook-Based Extensibility**: Each stack can define custom pre/post hooks for Docker Compose commands and database operations
|
||||
4. **Centralized Network**: All stacks connect to a shared Docker network (`kompose` by default)
|
||||
|
||||
### Stack Structure
|
||||
|
||||
Each stack directory contains:
|
||||
- `compose.yaml` or `docker-compose.yaml`: Docker Compose configuration
|
||||
- `.env`: Stack-specific variables (typically just `COMPOSE_PROJECT_NAME`)
|
||||
- `hooks.sh` (optional): Custom lifecycle hooks
|
||||
- Database dumps: `{DB_NAME}_{timestamp}.sql` files
|
||||
|
||||
### Monorepo Stacks
|
||||
|
||||
Some stacks are complete applications with their own build systems:
|
||||
- **`news/`**: Turborepo monorepo with Next.js apps (pnpm workspace)
|
||||
- **`docs/`**: Nuxt.js documentation site (pnpm)
|
||||
|
||||
## Common Commands
|
||||
|
||||
### Core Operations
|
||||
|
||||
```bash
|
||||
# Start all stacks
|
||||
./kompose.sh "*" up -d
|
||||
|
||||
# Start specific stack(s)
|
||||
./kompose.sh auth up -d
|
||||
./kompose.sh "auth,blog,data" up -d
|
||||
|
||||
# Stop stack(s)
|
||||
./kompose.sh auth down
|
||||
./kompose.sh "*" down
|
||||
|
||||
# View logs
|
||||
./kompose.sh auth logs -f
|
||||
./kompose.sh "*" logs --tail=100
|
||||
|
||||
# Check status
|
||||
./kompose.sh --list
|
||||
./kompose.sh "*" ps
|
||||
|
||||
# Restart services
|
||||
./kompose.sh auth restart
|
||||
|
||||
# Dry-run mode (preview without executing)
|
||||
./kompose.sh --dry-run "*" up -d
|
||||
```
|
||||
|
||||
### Database Operations
|
||||
|
||||
```bash
|
||||
# Export database dump(s)
|
||||
./kompose.sh auth db:export
|
||||
./kompose.sh "*" db:export
|
||||
|
||||
# Import latest dump (WARNING: drops & recreates database)
|
||||
./kompose.sh auth db:import
|
||||
|
||||
# Import specific dump file
|
||||
./kompose.sh auth db:import auth/keycloak_20251007_080554.sql
|
||||
|
||||
# Clean up old dumps (keeps only latest)
|
||||
./kompose.sh "*" db:cleanup
|
||||
```
|
||||
|
||||
### Environment Overrides
|
||||
|
||||
```bash
|
||||
# Override variables from CLI
|
||||
./kompose.sh -e DB_HOST=localhost -e DB_PORT=5433 news up -d
|
||||
|
||||
# Override network name
|
||||
./kompose.sh --network custom_network "*" up -d
|
||||
```
|
||||
|
||||
### Secret Management
|
||||
|
||||
```bash
|
||||
# Generate secrets from template (creates secrets.env)
|
||||
./kompose.sh --generate-secrets
|
||||
```
|
||||
|
||||
## Development Workflows
|
||||
|
||||
### Monorepo Stacks (news, docs)
|
||||
|
||||
```bash
|
||||
# News stack (Turborepo)
|
||||
cd news
|
||||
pnpm install
|
||||
pnpm dev # Start all apps in dev mode
|
||||
pnpm build # Build all apps
|
||||
pnpm lint # Lint all apps
|
||||
|
||||
# Docs stack (Nuxt)
|
||||
cd docs
|
||||
pnpm install
|
||||
pnpm dev # Start dev server
|
||||
pnpm build # Build for production
|
||||
pnpm generate # Generate static site
|
||||
```
|
||||
|
||||
### Testing kompose.sh Changes
|
||||
|
||||
```bash
|
||||
# Check syntax
|
||||
bash -n kompose.sh
|
||||
|
||||
# Use shellcheck for best practices
|
||||
shellcheck kompose.sh
|
||||
|
||||
# Test with dry-run
|
||||
./kompose.sh --dry-run auth up -d
|
||||
```
|
||||
|
||||
## Hooks System
|
||||
|
||||
Stacks can define custom hooks in `<stack>/hooks.sh` for lifecycle management.
|
||||
|
||||
### Available Hooks
|
||||
|
||||
**Database Hooks:**
|
||||
- `hook_pre_db_export`: Before database export
|
||||
- `hook_post_db_export`: After database export (receives dump file path)
|
||||
- `hook_pre_db_import`: Before database import (receives dump file path)
|
||||
- `hook_post_db_import`: After database import
|
||||
|
||||
**Docker Compose Command Hooks:**
|
||||
- `hook_pre_<command>`: Before docker compose command (up, down, start, stop, restart, build, pull, logs, etc.)
|
||||
- `hook_post_<command>`: After docker compose command (only runs on success)
|
||||
|
||||
### Hook Example
|
||||
|
||||
The `sexy/` stack uses hooks to manage Directus schema snapshots:
|
||||
|
||||
```bash
|
||||
hook_pre_db_export() {
|
||||
# Export Directus schema before database export
|
||||
docker exec "${COMPOSE_PROJECT_NAME}_api" npx directus schema snapshot
|
||||
}
|
||||
|
||||
hook_post_db_import() {
|
||||
# Restart Directus after database import
|
||||
docker restart "${COMPOSE_PROJECT_NAME}_api"
|
||||
}
|
||||
```
|
||||
|
||||
### Hook Reference
|
||||
|
||||
- Hooks receive command arguments as parameters: `$@`
|
||||
- Return `0` for success, `1` for failure
|
||||
- Post-hooks only execute if the main command succeeds
|
||||
- Available environment variables: `$SCRIPT_DIR`, `$stack`, all `.env` variables
|
||||
- Template available at `hooks.sh.template`
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### Configuration Structure
|
||||
|
||||
1. **Root `.env`**: Stack-scoped configuration (committed to git)
|
||||
- Pattern: `{STACK}_{VARIABLE}` (e.g., `AUTH_TRAEFIK_HOST`)
|
||||
- Shared variables: `DB_USER`, `DB_HOST`, `NETWORK_NAME`, etc.
|
||||
|
||||
2. **`secrets.env`**: Sensitive data (NOT committed to git)
|
||||
- Generated from `secrets.env.template` using `--generate-secrets`
|
||||
- Pattern: `{STACK}_{SECRET}` (e.g., `AUTH_KC_ADMIN_PASSWORD`)
|
||||
|
||||
3. **Stack `.env`**: Minimal stack-specific overrides
|
||||
- Typically only contains `COMPOSE_PROJECT_NAME`
|
||||
|
||||
### Secret Generation Patterns
|
||||
|
||||
The `--generate-secrets` command generates different secret types:
|
||||
- `*_PASSWORD`: 32-char alphanumeric password
|
||||
- `*_SECRET`, `*_ENCRYPTION_KEY`: 64-char hex (32 bytes)
|
||||
- `*_TOKEN`: 40-char alphanumeric token
|
||||
- `*_HASH`: 64-char hex hash
|
||||
- Default: 32-char alphanumeric
|
||||
|
||||
## Important Notes
|
||||
|
||||
### Security
|
||||
- `secrets.env` is in `.gitignore` and should NEVER be committed
|
||||
- Use `secrets.env.template` as a reference for required secrets
|
||||
- Stack-scoped variables prevent conflicts between stacks
|
||||
|
||||
### Database Operations
|
||||
- Database imports are **destructive** - they drop and recreate the database
|
||||
- Always backup before running `db:import`
|
||||
- Database dumps are saved as `{DB_NAME}_{timestamp}.sql` in stack directories
|
||||
- Only PostgreSQL databases are currently supported
|
||||
|
||||
### Network Configuration
|
||||
- All stacks use a shared Docker network (default: `kompose`)
|
||||
- Network must be created before starting stacks: `docker network create kompose`
|
||||
- Override network with `--network` flag or `NETWORK_NAME` in `.env`
|
||||
|
||||
### Traefik Integration
|
||||
- Services can be exposed via Traefik reverse proxy
|
||||
- Control per-stack: `{STACK}_TRAEFIK_ENABLED=true/false`
|
||||
- Host configuration: `{STACK}_TRAEFIK_HOST=subdomain.example.com`
|
||||
|
||||
## Migration Guide
|
||||
|
||||
Recent changes introduced stack-scoped variables and centralized secrets management. See `MIGRATION_GUIDE.md` for detailed migration steps from the old configuration format.
|
||||
|
||||
## Code Style Guidelines
|
||||
|
||||
### Bash Script Conventions (kompose.sh)
|
||||
|
||||
- **Constants**: `UPPER_CASE` with `readonly`
|
||||
- **Local variables**: `lowercase_with_underscores`
|
||||
- **Functions**: `function_name()` with descriptive names
|
||||
- **Error handling**: Use `set -euo pipefail`
|
||||
- **Logging**: Use provided functions (`log_info`, `log_error`, `log_success`, `log_warning`)
|
||||
- **Indentation**: 4 spaces
|
||||
- **Return codes**: `0` for success, `1` for failure
|
||||
- **ShellCheck**: Code should pass `shellcheck` linting
|
||||
|
||||
### Hook Development
|
||||
|
||||
- Return `0` for success, even for non-critical failures
|
||||
- Use indented output: `echo " Message"`
|
||||
- Check container status before `docker exec` commands
|
||||
- Test with `--dry-run` before executing
|
||||
- Add timeouts for long-running operations
|
||||
- Document hooks with comments
|
||||
|
||||
## Documentation Location
|
||||
|
||||
Full documentation is available in `docs/` (Nuxt site). Key documents:
|
||||
- `CONTRIBUTING.md`: Contribution guidelines
|
||||
- `HOOKS_QUICKREF.md`: Quick reference for hooks system
|
||||
- `MIGRATION_GUIDE.md`: Configuration migration guide
|
||||
- `hooks.sh.template`: Template for creating stack hooks
|
||||
Reference in New Issue
Block a user