feat: doocs

Projects/kompose/docs/content/2.installation.md

@@ -0,0 +1,278 @@
+---
+title: Installation Guide
+description: Running on your system in just a few minutes.
+---
+
+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](/guide/quick-start)
+2. [Learn about Stack Management](/guide/stack-management)
+3. [Explore Database Operations](/guide/database)
+4. [Set up Custom Hooks](/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](/guide/troubleshooting) or [open an issue](https://github.com/yourusername/kompose/issues) on GitHub.