279 lines
4.9 KiB
Markdown
279 lines
4.9 KiB
Markdown
---
|
|
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.
|