feat: docus

2025-10-08 13:54:19 +02:00
parent 47539d8cc8
commit 223cc2ac6a
31 changed files with 2476 additions and 1820 deletions
--- a/Projects/kompose/docs/content/docs/index.md
+++ b/Projects/kompose/docs/content/docs/index.md
@@ -0,0 +1,65 @@
+---
+title: Introduction to Kompose
+description: Learn about Kompose, your Docker Compose Symphony Conductor for managing multiple stacks with style and grace.
+---
+
+# Introduction to Kompose
+
+**Kompose** is a powerful Bash orchestration tool for managing multiple Docker Compose stacks with style and grace. Think of it as a conductor for your Docker symphony - each stack plays its part, and Kompose makes sure they're all in harmony.
+
+## Why Kompose?
+
+🎯 **One Command to Rule Them All** - Manage dozens of stacks with a single command
+
+🔄 **Database Wizardry** - Export, import, and clean up PostgreSQL databases like a boss
+
+🎪 **Hook System** - Extend functionality with custom pre/post operation hooks
+
+🌐 **Network Maestro** - Smart network management with CLI overrides
+
+🔐 **Environment Juggler** - Override any environment variable on the fly
+
+🎨 **Beautiful Output** - Color-coded logs and status indicators
+
+🧪 **Dry-Run Mode** - Test changes before applying them
+
+## Quick Example
+
+```bash
+# Start all stacks
+./kompose.sh "*" up -d
+
+# View logs from specific stacks
+./kompose.sh "blog,news" logs -f
+
+# Export all databases
+./kompose.sh "*" db:export
+
+# Override network for staging
+./kompose.sh --network staging "*" up -d
+```
+
+## Key Features
+
+### Stack Management
+
+Pattern-based selection allows you to target stacks with globs, comma-separated lists, or wildcards. Execute commands across multiple stacks simultaneously with visual feedback and color-coded success/failure indicators.
+
+### Database Operations
+
+Automated backups with timestamped dumps, smart imports that auto-detect latest dumps, and safe database operations with connection termination. Keep your storage clean with cleanup utilities.
+
+### Hooks System
+
+Extend Kompose with custom hooks for each stack. Define `pre_db_export`, `post_db_export`, `pre_db_import`, and `post_db_import` hooks to add stack-specific logic.
+
+### Network Management
+
+All stacks communicate through a unified Docker network. Override the network on-the-fly via CLI without editing configs, with seamless Traefik integration.
+
+## Next Steps
+
+- [Installation Guide](/docs/installation)
+- [Quick Start Tutorial](/docs/quick-start)
+- [Stack Management](/docs/guide/stack-management)
+- [Database Operations](/docs/guide/database)
--- a/Projects/kompose/docs/content/docs/installation.md
+++ b/Projects/kompose/docs/content/docs/installation.md
@@ -0,0 +1,280 @@
+---
+title: Installation Guide
+description: Step-by-step guide to install and set up Kompose on your system
+---
+
+# Installation Guide
+
+Get Kompose up and running on your system in just a few minutes.
+
+## Prerequisites
+
+Before installing Kompose, make sure you have the following installed:
+
+### Required
+
+- **Bash** 4.0 or higher
+- **Docker** 20.10 or higher
+- **Docker Compose** v2.0 or higher
+
+### Optional (for database operations)
+
+- **PostgreSQL client tools** (for database operations)
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install postgresql-client
+
+# macOS
+brew install postgresql
+
+# Arch Linux
+sudo pacman -S postgresql
+```
+
+## Installation
+
+### Method 1: Clone from Git (Recommended)
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/kompose.git
+
+# Navigate to the directory
+cd kompose
+
+# Make the script executable
+chmod +x kompose.sh
+
+# Verify installation
+./kompose.sh --help
+```
+
+### Method 2: Download Release
+
+```bash
+# Download the latest release
+wget https://github.com/yourusername/kompose/archive/refs/heads/main.zip
+
+# Extract
+unzip main.zip
+
+# Navigate to directory
+cd kompose-main
+
+# Make executable
+chmod +x kompose.sh
+```
+
+## Initial Setup
+
+### 1. Create Docker Network
+
+Kompose uses a unified Docker network for all stacks:
+
+```bash
+docker network create kompose
+```
+
+### 2. Configure Environment
+
+Create and configure the root `.env` file:
+
+```bash
+# Copy example environment file
+cp .env.example .env
+
+# Edit with your preferred editor
+nano .env
+```
+
+**Example `.env` configuration:**
+
+```env
+# Network Configuration
+NETWORK_NAME=kompose
+
+# Database Connection
+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
+```
+
+### 3. Configure Individual Stacks
+
+Each stack needs its own `.env` file. Navigate to any stack directory:
+
+```bash
+# Example: Configure the proxy stack
+cd proxy
+cp .env.example .env
+nano .env
+```
+
+## Verification
+
+### Check Installation
+
+```bash
+# List all available stacks
+./kompose.sh --list
+
+# Should output something like:
+# Stack: auth (compose.yaml) [.env] [PostgreSQL]
+# Stack: blog (compose.yaml) [.env]
+# Stack: data (compose.yaml) [.env] [PostgreSQL]
+# ...
+```
+
+### Test Basic Commands
+
+```bash
+# Start the proxy stack
+./kompose.sh proxy up -d
+
+# Check if it's running
+./kompose.sh proxy ps
+
+# View logs
+./kompose.sh proxy logs
+```
+
+## Post-Installation
+
+### Add to PATH (Optional)
+
+For easier access, add Kompose to your PATH:
+
+```bash
+# Add to ~/.bashrc or ~/.zshrc
+echo 'export PATH="$PATH:/path/to/kompose"' >> ~/.bashrc
+source ~/.bashrc
+
+# Now you can run from anywhere
+kompose.sh --list
+```
+
+### Create Aliases (Optional)
+
+Add helpful aliases to your shell configuration:
+
+```bash
+# Add to ~/.bashrc or ~/.zshrc
+alias kp='./kompose.sh'
+alias kup='./kompose.sh "*" up -d'
+alias kdown='./kompose.sh "*" down'
+alias klogs='./kompose.sh "*" logs -f'
+alias kps='./kompose.sh "*" ps'
+```
+
+### Set Up Automated Backups
+
+Create a cron job for automatic database backups:
+
+```bash
+# Edit crontab
+crontab -e
+
+# Add daily backup at 2 AM
+0 2 * * * cd /path/to/kompose && ./kompose.sh "*" db:export 2>&1 | tee -a backup.log
+
+# Add weekly cleanup (Sundays at 3 AM)
+0 3 * * 0 cd /path/to/kompose && ./kompose.sh "*" db:cleanup
+```
+
+## Troubleshooting
+
+### Permission Denied
+
+If you get a "Permission denied" error:
+
+```bash
+chmod +x kompose.sh
+```
+
+### Docker Network Already Exists
+
+If the network creation fails:
+
+```bash
+# Check if it exists
+docker network ls | grep kompose
+
+# If it exists, you're good to go
+# If not, try removing and recreating
+docker network rm kompose
+docker network create kompose
+```
+
+### Docker Not Running
+
+Ensure Docker daemon is running:
+
+```bash
+# Check Docker status
+sudo systemctl status docker
+
+# Start Docker if not running
+sudo systemctl start docker
+
+# Enable Docker to start on boot
+sudo systemctl enable docker
+```
+
+## Next Steps
+
+Now that Kompose is installed, you can:
+
+1. [Start with the Quick Start Guide](/docs/quick-start)
+2. [Learn about Stack Management](/docs/guide/stack-management)
+3. [Explore Database Operations](/docs/guide/database)
+4. [Set up Custom Hooks](/docs/guide/hooks)
+
+## Updating Kompose
+
+To update to the latest version:
+
+```bash
+# Navigate to Kompose directory
+cd /path/to/kompose
+
+# Pull latest changes
+git pull origin main
+
+# Restart affected stacks if needed
+./kompose.sh "*" restart
+```
+
+## Uninstallation
+
+To completely remove Kompose:
+
+```bash
+# Stop all stacks
+./kompose.sh "*" down
+
+# Remove Docker network
+docker network rm kompose
+
+# Remove Kompose directory
+rm -rf /path/to/kompose
+
+# (Optional) Remove from PATH
+# Edit ~/.bashrc or ~/.zshrc and remove the PATH export
+```
+
+---
+
+**Need Help?** Check out the [Troubleshooting Guide](/docs/troubleshooting) or [open an issue](https://github.com/yourusername/kompose/issues) on GitHub.