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

title, description

title	description
Installation Guide	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)

# 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)

# 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

# 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:

docker network create kompose

2. Configure Environment

Create and configure the root .env file:

# Copy example environment file
cp .env.example .env

# Edit with your preferred editor
nano .env

Example .env configuration:

# 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:

# Example: Configure the proxy stack
cd proxy
cp .env.example .env
nano .env

Verification

Check Installation

# 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

# 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:

# 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:

# 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:

# 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:

chmod +x kompose.sh

Docker Network Already Exists

If the network creation fails:

# 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:

# 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
2. Learn about Stack Management
3. Explore Database Operations
4. Set up Custom Hooks

Updating Kompose

To update to the latest version:

# 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:

# 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 or open an issue on GitHub.