---
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://code.pivoine.art/valknar/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://code.pivoine.art/valknar/kompose/archive/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://code.pivoine.art/valknar/kompose/issues) on the git repository.