feat: doocs

Projects/kompose/docs/content/4.reference/cli.md

@@ -0,0 +1,200 @@
+---
+title: CLI Reference
+description: Complete command-line interface reference
+---
+
+Complete reference for all Kompose CLI commands and options.
+
+## Synopsis
+
+```bash
+./kompose.sh [OPTIONS] <PATTERN> <COMMAND> [ARGS...]
+```
+
+## Options
+
+### Global Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--help` | `-h` | Show help message |
+| `--list` | `-l` | List all available stacks |
+| `--dry-run` | `-n` | Preview actions without executing |
+| `--network <n>` | | Override network name |
+| `-e <KEY=VALUE>` | | Set environment variable |
+
+### Examples
+
+```bash
+# Show help
+./kompose.sh --help
+
+# List all stacks
+./kompose.sh --list
+
+# Dry run mode
+./kompose.sh --dry-run "*" up -d
+
+# Override network
+./kompose.sh --network staging "*" up -d
+
+# Set environment variable
+./kompose.sh -e DB_HOST=localhost news up -d
+```
+
+## Stack Patterns
+
+### Pattern Syntax
+
+- `*` - All stacks
+- `stack1,stack2,stack3` - Specific stacks (comma-separated)
+- `stack` - Single stack
+
+### Examples
+
+```bash
+# All stacks
+./kompose.sh "*" up -d
+
+# Multiple specific stacks
+./kompose.sh "auth,blog,news" logs -f
+
+# Single stack
+./kompose.sh proxy restart
+```
+
+## Docker Compose Commands
+
+Any Docker Compose command can be passed through:
+
+```bash
+# Start services
+./kompose.sh <pattern> up -d
+
+# Stop services
+./kompose.sh <pattern> down
+
+# View logs
+./kompose.sh <pattern> logs -f
+
+# Restart services
+./kompose.sh <pattern> restart
+
+# Pull images
+./kompose.sh <pattern> pull
+
+# Check status
+./kompose.sh <pattern> ps
+
+# Execute commands
+./kompose.sh <pattern> exec <service> <command>
+```
+
+## Database Commands
+
+### db:export
+
+Export PostgreSQL database to SQL dump file.
+
+```bash
+./kompose.sh <pattern> db:export
+```
+
+**Output:** `<stack-dir>/<db-name>_YYYYMMDD_HHMMSS.sql`
+
+### db:import
+
+Import PostgreSQL database from SQL dump file.
+
+```bash
+# Import latest dump (auto-detected)
+./kompose.sh <stack> db:import
+
+# Import specific dump file
+./kompose.sh <stack> db:import path/to/dump.sql
+```
+
+**:icon{name="lucide:alert-triangle"} WARNING:** Drops and recreates the database!
+
+### db:cleanup
+
+Remove old database dump files (keeps only the latest).
+
+```bash
+./kompose.sh <pattern> db:cleanup
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Missing required arguments |
+| 3 | No matching stacks |
+
+## Environment Variables
+
+Environment variables can be set via:
+
+1. Root `.env` file
+2. Stack `.env` file
+3. CLI `-e` flag (highest priority)
+
+### Precedence
+
+```
+CLI (-e flag) > Stack .env > Root .env > Compose defaults
+```
+
+## Examples
+
+### Daily Workflow
+
+```bash
+# Morning: Start everything
+./kompose.sh "*" up -d
+
+# Check status
+./kompose.sh "*" ps
+
+# View logs
+./kompose.sh "*" logs --tail=50
+
+# Evening: Backup databases
+./kompose.sh "*" db:export
+./kompose.sh "*" db:cleanup
+```
+
+### Deployment
+
+```bash
+# Pull latest images
+./kompose.sh "*" pull
+
+# Backup before update
+./kompose.sh "*" db:export
+
+# Restart with new images
+./kompose.sh "*" down
+./kompose.sh "*" up -d
+
+# Verify health
+./kompose.sh "*" ps
+```
+
+### Development
+
+```bash
+# Start dev environment
+./kompose.sh "data,proxy,news" up -d
+
+# Override for testing
+./kompose.sh -e DB_NAME=test_db news up -d
+
+# Watch logs
+./kompose.sh news logs -f
+
+# Clean up
+./kompose.sh news down
+```

Projects/kompose/docs/content/4.reference/environment.md

@@ -0,0 +1,145 @@
+---
+title: Environment Variables
+description: Complete reference for all environment variables
+---
+
+Complete reference for all environment variables used in Kompose.
+
+## Global Variables
+
+These are set in the root `.env` file and available to all stacks.
+
+### Network Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `NETWORK_NAME` | `kompose` | Docker network name |
+
+### Database Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DB_USER` | - | PostgreSQL username |
+| `DB_PASSWORD` | - | PostgreSQL password |
+| `DB_PORT` | `5432` | PostgreSQL port |
+| `DB_HOST` | `postgres` | PostgreSQL host |
+
+### Admin Settings
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ADMIN_EMAIL` | - | Administrator email |
+| `ADMIN_PASSWORD` | - | Administrator password |
+
+### Email/SMTP Settings
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `EMAIL_TRANSPORT` | `smtp` | Email transport method |
+| `EMAIL_FROM` | - | Default sender address |
+| `EMAIL_SMTP_HOST` | - | SMTP server hostname |
+| `EMAIL_SMTP_PORT` | `465` | SMTP server port |
+| `EMAIL_SMTP_USER` | - | SMTP username |
+| `EMAIL_SMTP_PASSWORD` | - | SMTP password |
+
+## Stack-Specific Variables
+
+These are set in individual stack `.env` files.
+
+### Common Stack Variables
+
+| Variable | Description |
+|----------|-------------|
+| `COMPOSE_PROJECT_NAME` | Stack project name |
+| `TRAEFIK_HOST` | Domain for Traefik routing |
+| `APP_PORT` | Internal application port |
+
+### Auth Stack (Keycloak)
+
+| Variable | Description |
+|----------|-------------|
+| `KC_ADMIN_USERNAME` | Keycloak admin username |
+| `KC_ADMIN_PASSWORD` | Keycloak admin password |
+| `KC_DB_NAME` | Keycloak database name |
+
+### News Stack (Letterspace)
+
+| Variable | Description |
+|----------|-------------|
+| `JWT_SECRET` | JWT signing secret |
+| `DB_NAME` | Newsletter database name |
+| `NODE_ENV` | Node environment (production/development) |
+
+### Sexy Stack (Directus)
+
+| Variable | Description |
+|----------|-------------|
+| `KEY` | Directus encryption key |
+| `SECRET` | Directus secret key |
+| `ADMIN_EMAIL` | Directus admin email |
+| `ADMIN_PASSWORD` | Directus admin password |
+
+## Configuration Precedence
+
+Environment variables follow this priority order:
+
+1. **CLI Override** (`-e` flag) - Highest priority
+2. **Stack .env** - Stack-specific settings
+3. **Root .env** - Global defaults
+4. **Compose File** - Docker Compose defaults
+
+### Example
+
+```bash
+# Root .env
+DB_HOST=postgres
+
+# news/.env
+DB_HOST=news-postgres  # Overrides root
+
+# CLI
+./kompose.sh -e DB_HOST=localhost news up -d  # Overrides both
+```
+
+## Best Practices
+
+### Security
+
+- ✅ Use strong, random passwords
+- ✅ Never commit `.env` files to version control
+- ✅ Use `.env.example` as template
+- ✅ Rotate secrets regularly
+
+### Organization
+
+- ✅ Document custom variables
+- ✅ Group related variables
+- ✅ Use consistent naming
+- ✅ Keep defaults in root `.env`
+
+## Generating Secrets
+
+### Random Passwords
+
+```bash
+# OpenSSL
+openssl rand -hex 32
+
+# UUID
+uuidgen
+
+# Base64
+openssl rand -base64 32
+```
+
+### JWT Secrets
+
+```bash
+openssl rand -hex 64
+```
+
+### Encryption Keys
+
+```bash
+openssl rand -base64 32
+```

Projects/kompose/docs/content/4.reference/index.md

@@ -0,0 +1,26 @@
+---
+title: Reference Documentation
+description: Complete reference documentation for Kompose
+---
+
+Complete reference documentation for all aspects of Kompose.
+
+## Command Line
+
+- [CLI Reference](/reference/cli) - All commands and options
+- [Stack Patterns](/reference/cli#stack-patterns) - Pattern matching syntax
+
+## Configuration
+
+- [Environment Variables](/reference/environment) - All environment variables
+- [Configuration Files](/guide/configuration) - File structure and precedence
+
+## Stack Reference
+
+- [Stack Documentation](/stacks) - Detailed docs for each stack
+
+## Advanced Topics
+
+- [Network Architecture](/guide/network) - Network design and configuration
+- [Hook System](/guide/hooks) - Writing custom hooks
+- [Database Operations](/guide/database) - Advanced database management