feat: doocs

2025-10-09 00:30:31 +02:00
parent 37b1d6dafc
commit aa054f8e27
67 changed files with 2347 additions and 2447 deletions
--- a/Projects/kompose/docs/content/3.guide/configuration.md
+++ b/Projects/kompose/docs/content/3.guide/configuration.md
@@ -0,0 +1,60 @@
+---
+title: Configuration
+description: Configure Kompose and your stacks
+---
+
+### Root Configuration (`.env`)
+
+Global settings shared across all stacks:
+
+```bash
+# Network Configuration
+NETWORK_NAME=kompose
+
+# Database Connection (default values)
+DB_USER=dbuser
+DB_PASSWORD=secretpassword
+DB_PORT=5432
+DB_HOST=postgres
+
+# Admin Settings
+ADMIN_EMAIL=admin@example.com
+
+# Email/SMTP Settings
+EMAIL_TRANSPORT=smtp
+EMAIL_FROM=noreply@example.com
+EMAIL_SMTP_HOST=smtp.example.com
+EMAIL_SMTP_PORT=465
+EMAIL_SMTP_USER=smtp@example.com
+EMAIL_SMTP_PASSWORD=smtppassword
+```
+
+### Stack Configuration (`<stack>/.env`)
+
+Stack-specific settings:
+
+```bash
+# Stack Identification
+COMPOSE_PROJECT_NAME=blog
+
+# Docker Image
+DOCKER_IMAGE=joseluisq/static-web-server:latest
+
+# Traefik Configuration
+TRAEFIK_HOST=example.com
+
+# Application Settings
+APP_PORT=80
+```
+
+### Configuration Precedence
+
+```
+CLI Overrides (-e flag) 
+    ↓
+Stack .env
+    ↓
+Root .env
+    ↓
+Compose defaults
+```
--- a/Projects/kompose/docs/content/3.guide/database.md
+++ b/Projects/kompose/docs/content/3.guide/database.md
@@ -0,0 +1,28 @@
+---
+title: Database Operations
+description: Export, import, and manage PostgreSQL databases
+---
+
+- **Automated backups**: Export PostgreSQL databases with timestamped dumps
+- **Smart imports**: Auto-detect latest dumps or specify exact files
+- **Drop & recreate**: Safe database import with connection termination
+- **Cleanup utilities**: Keep only the latest dumps, remove old backups
+- **Hook integration**: Custom pre/post operations for each database action
+
+### :icon{name="lucide:git-branch"} Extensibility
+- **Custom hooks**: Define `pre_db_export`, `post_db_export`, `pre_db_import`, `post_db_import`
+- **Stack-specific logic**: Each stack can have unique operational requirements
+- **Environment access**: Hooks inherit all environment variables
+- **Dry-run aware**: Test hook execution without side effects
+
+### :icon{name="lucide:globe"} Network Management
+- **Unified network**: All stacks communicate on a single Docker network
+- **CLI overrides**: Change network on-the-fly without editing configs
+- **Traefik integration**: Seamless reverse proxy setup with proper network awareness
+- **Multi-network support**: Special stacks can have additional internal networks
+
+### :icon{name="lucide:wrench"} Environment Control
+- **Global overrides**: Set environment variables via CLI flags
+- **Layered configs**: Root `.env` + stack `.env` + CLI overrides
+- **Precedence rules**: CLI > Stack > Root configuration hierarchy
+- **Real-time changes**: No need to edit files for temporary overrides
--- a/Projects/kompose/docs/content/3.guide/hooks.md
+++ b/Projects/kompose/docs/content/3.guide/hooks.md
@@ -0,0 +1,89 @@
+---
+title: Hooks System
+description: Extend Kompose with custom hooks
+---
+
+Extend Kompose functionality with custom hooks for each stack.
+
+### Available Hooks
+
+| Hook | Timing | Arguments | Use Case |
+|------|--------|-----------|----------|
+| `hook_pre_db_export` | Before DB export | None | Prepare data, export schemas |
+| `hook_post_db_export` | After DB export | `$1` = dump file path | Cleanup, notifications |
+| `hook_pre_db_import` | Before DB import | `$1` = dump file path | Prepare environment, schema setup |
+| `hook_post_db_import` | After DB import | `$1` = dump file path | Restart services, clear caches |
+
+### Creating Hooks
+
+Create `<stack>/hooks.sh`:
+
+```bash
+#!/usr/bin/env bash
+
+# Export schema before database export
+hook_pre_db_export() {
+    echo "  Exporting application schema..."
+    docker exec sexy_api npx directus schema snapshot --yes ./schema.yaml
+    return 0  # 0 = success, 1 = failure
+}
+
+# Apply schema before database import
+hook_pre_db_import() {
+    local dump_file="$1"
+    echo "  Applying schema snapshot..."
+    docker exec sexy_api npx directus schema apply --yes ./schema.yaml
+    return 0
+}
+
+# Restart service after import
+hook_post_db_import() {
+    local dump_file="$1"
+    echo "  Restarting application..."
+    docker restart sexy_api
+    return 0
+}
+```
+
+### Real-World Example: Directus (sexy stack)
+
+The `sexy` stack uses hooks for Directus schema management:
+
+**Export Flow:**
+1. `pre_db_export`: Export Directus schema snapshot
+2. Database export creates SQL dump
+3. Result: Both database dump + schema snapshot
+
+**Import Flow:**
+1. `pre_db_import`: Apply Directus schema from snapshot
+2. Database import loads SQL dump
+3. `post_db_import`: Restart Directus container
+4. Result: Fully synchronized schema + data
+
+### Testing Hooks
+
+```bash
+# Preview hook execution
+./kompose.sh sexy db:export --dry-run
+
+# Execute with hooks
+./kompose.sh sexy db:export
+
+# Import with hooks
+./kompose.sh sexy db:import
+```
+
+### Hook Best Practices
+
+✅ **DO:**
+- Return 0 for success, 1 for failure
+- Use indented output: `echo "  Message"`
+- Make non-critical operations return 0
+- Check container status before `docker exec`
+- Test in dry-run mode first
+
+❌ **DON'T:**
+- Assume containers are running
+- Use blocking operations without timeouts
+- Forget error handling
+- Hardcode paths or credentials
--- a/Projects/kompose/docs/content/3.guide/index.md
+++ b/Projects/kompose/docs/content/3.guide/index.md
@@ -0,0 +1,27 @@
+---
+title: User Guide
+description: Comprehensive guide to using Kompose
+---
+
+Learn everything you need to know about using Kompose effectively.
+
+## Getting Started
+
+- [Quick Start](/guide/quick-start) - Get up and running in minutes
+- [Installation](/installation) - Detailed installation instructions
+
+## Core Concepts
+
+- [Stack Management](/guide/stack-management) - Managing multiple Docker Compose stacks
+- [Database Operations](/guide/database) - Backup, restore, and maintain databases
+- [Hooks System](/guide/hooks) - Extend functionality with custom hooks
+- [Network Architecture](/guide/network) - Understanding networking in Kompose
+
+## Configuration
+
+- [Configuration Guide](/guide/configuration) - Configure Kompose and stacks
+- [Environment Variables](/reference/environment) - All available environment variables
+
+## Troubleshooting
+
+- [Common Issues](/guide/troubleshooting) - Solutions to common problems
--- a/Projects/kompose/docs/content/3.guide/network.md
+++ b/Projects/kompose/docs/content/3.guide/network.md
@@ -0,0 +1,50 @@
+---
+title: Network Architecture
+description: Understanding Kompose network design
+---
+
+### Single Network Design
+
+All stacks communicate through a unified Docker network:
+
+```
+┌─────────────────────────────────────────────────┐
+│          kompose Network (Bridge)               │
+│                                                 │
+│  ┌───────┐  ┌───────┐  ┌──────┐  ┌──────┐    │
+│  │ Blog  │  │ News  │  │ Auth │  │ Data │    │
+│  └───────┘  └───────┘  └──────┘  └──────┘    │
+│      │          │          │         │         │
+│  ┌───────────────────────────────────────┐    │
+│  │         Traefik (Reverse Proxy)       │    │
+│  └───────────────────────────────────────┘    │
+│                    │                            │
+└────────────────────┼────────────────────────────┘
+                     │
+              ┌──────┴──────┐
+              │  Internet   │
+              └─────────────┘
+```
+
+### Network Configuration
+
+**Default network:** `kompose` (defined in root `.env`)
+
+**Override network:**
+```bash
+# Temporary override
+./kompose.sh --network staging "*" up -d
+
+# Permanent override
+echo "NETWORK_NAME=production" >> .env
+```
+
+### Special Network Cases
+
+**trace stack** - Dual network setup:
+- `kompose` - External access via Traefik
+- `signoz` - Internal component communication
+
+**vpn stack** - Dual network setup:
+- `kompose` - Web UI access
+- `wg` - WireGuard tunnel network
--- a/Projects/kompose/docs/content/3.guide/quick-start.md
+++ b/Projects/kompose/docs/content/3.guide/quick-start.md
@@ -0,0 +1,27 @@
+---
+title: Quick Start
+description: Get started with Kompose in minutes
+---
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/kompose.git
+cd kompose
+
+# Make kompose executable
+chmod +x kompose.sh
+
+# List all stacks
+./kompose.sh --list
+
+# Start everything
+./kompose.sh "*" up -d
+
+# View logs from specific stacks
+./kompose.sh "blog,news" logs -f
+
+# Export all databases
+./kompose.sh "*" db:export
+
+# That's it! :icon{name="lucide:party-popper"}
+```
--- a/Projects/kompose/docs/content/3.guide/stack-management.md
+++ b/Projects/kompose/docs/content/3.guide/stack-management.md
@@ -0,0 +1,24 @@
+---
+title: Stack Management
+description: Learn how to manage multiple Docker Compose stacks
+---
+
+```bash
+# Start stacks
+./kompose.sh <pattern> up -d
+
+# Stop stacks
+./kompose.sh <pattern> down
+
+# View logs
+./kompose.sh <pattern> logs -f
+
+# Restart stacks
+./kompose.sh <pattern> restart
+
+# Check status
+./kompose.sh <pattern> ps
+
+# Pull latest images
+./kompose.sh <pattern> pull
+```
--- a/Projects/kompose/docs/content/3.guide/troubleshooting.md
+++ b/Projects/kompose/docs/content/3.guide/troubleshooting.md
@@ -0,0 +1,113 @@
+---
+title: Troubleshooting
+description: Common issues and solutions
+---
+
+### Common Issues
+
+#### :icon{name="lucide:ban"} 404 Error from Traefik
+
+**Problem:** Websites return 404 even though containers are running
+
+**Solution:**
+```bash
+# Check Traefik logs
+docker logs proxy_app
+
+# Verify network configuration
+docker network inspect kompose
+
+# Restart proxy and affected stacks
+./kompose.sh proxy down && ./kompose.sh proxy up -d
+./kompose.sh blog restart
+```
+
+**Debug:**
+```bash
+# Check Traefik dashboard
+http://your-server:8080
+
+# Verify container labels
+docker inspect blog_app | grep traefik
+```
+
+#### :icon{name="lucide:hard-drive"} Database Import Fails
+
+**Problem:** `db:import` command fails
+
+**Common causes:**
+1. **Active connections** - Solved automatically (kompose terminates connections)
+2. **Missing dump file** - Check file path
+3. **Insufficient permissions** - Check DB_USER permissions
+4. **Wrong database** - Verify DB_NAME in stack `.env`
+
+**Solution:**
+```bash
+# Check database connectivity
+docker exec data_postgres psql -U $DB_USER -l
+
+# Verify dump file exists
+ls -lh news/*.sql
+
+# Check logs for detailed error
+./kompose.sh news db:import 2>&1 | tee import.log
+```
+
+#### :icon{name="lucide:plug"} Container Won't Connect to Network
+
+**Problem:** Container fails to join kompose network
+
+**Solution:**
+```bash
+# Recreate network
+docker network rm kompose
+docker network create kompose
+
+# Restart all stacks
+./kompose.sh "*" down
+./kompose.sh "*" up -d
+```
+
+#### :icon{name="lucide:git-branch"} Hooks Not Executing
+
+**Problem:** Custom hooks aren't running
+
+**Checklist:**
+- [ ] `hooks.sh` file exists in stack directory
+- [ ] `hooks.sh` is executable: `chmod +x <stack>/hooks.sh`
+- [ ] Function names match: `hook_pre_db_export`, etc.
+- [ ] Functions return 0 (success) or 1 (failure)
+
+**Test:**
+```bash
+# Dry-run shows hook execution
+./kompose.sh sexy db:export --dry-run
+
+# Check if hooks.sh exists
+./kompose.sh --list | grep hooks
+```
+
+### Debug Mode
+
+Enable verbose logging:
+
+```bash
+# View Traefik debug logs
+docker logs -f proxy_app
+
+# Check environment variables
+./kompose.sh news ps
+docker exec news_backend env
+
+# Inspect running containers
+docker ps -a
+docker inspect <container_name>
+```
+
+### Getting Help
+
+1. **Check logs:** `./kompose.sh <stack> logs`
+2. **Use dry-run:** `./kompose.sh --dry-run <pattern> <command>`
+3. **List stacks:** `./kompose.sh --list`
+4. **Read help:** `./kompose.sh --help`
+5. **Open an issue:** [GitHub Issues](https://github.com/yourusername/kompose/issues)