Self-Hosting

Upgrades & Backup

Keep your Kokomo server updated and your data safe.

Upgrading Kokomo

Kokomo uses Docker for easy upgrades. Follow these steps to update to the latest version.

Standard Upgrade Process

# Navigate to Kokomo directory
cd ~/kokomo

# Pull latest images
docker compose pull

# Restart with new images (minimal downtime)
docker compose up -d

# Verify the upgrade
docker compose ps
docker compose logs -f kokomo-server --tail=50

# Check version
curl https://kokomo.yourdomain.com/health

Before major upgrades: Always backup your database first. Check the release notes for breaking changes.

Version Pinning

For production stability, pin to specific versions instead of using `latest`.

docker-compose.yml

services:
  kokomo-server:
    image: macroblink/kokomo-server:1.5.2  # Pin to specific version
    # instead of: macroblink/kokomo-server:latest

Check available versions

# List available tags
curl -s https://registry.hub.docker.com/v2/repositories/macroblink/kokomo-server/tags | jq '.results[].name'

Database Backup

Regular backups protect against data loss. Here's how to backup your PostgreSQL database.

Manual Backup

# Backup database to file
docker compose exec -T postgres pg_dump -U kokomo kokomo > backup_$(date +%Y%m%d_%H%M%S).sql

# Compressed backup
docker compose exec -T postgres pg_dump -U kokomo kokomo | gzip > backup_$(date +%Y%m%d_%H%M%S).sql.gz

Automated Daily Backup (cron)

# Edit crontab
crontab -e

# Add this line for daily backup at 2 AM
0 2 * * * cd ~/kokomo && docker compose exec -T postgres pg_dump -U kokomo kokomo | gzip > ~/backups/kokomo_$(date +\%Y\%m\%d).sql.gz

# Keep only last 30 days
0 3 * * * find ~/backups -name "kokomo_*.sql.gz" -mtime +30 -delete

Restore from Backup

Restore your database from a backup file.

Restore Process

# Stop the server
docker compose stop kokomo-server

# Restore from backup
gunzip -c backup_20240315.sql.gz | docker compose exec -T postgres psql -U kokomo kokomo

# Or from uncompressed file
cat backup.sql | docker compose exec -T postgres psql -U kokomo kokomo

# Restart services
docker compose up -d

Warning: Restoring will overwrite all existing data. Make sure you're restoring to the correct database.

File Storage Backup

If using local storage, backup uploaded files separately.

Backup uploaded files

# Copy uploads from Docker volume
docker cp kokomo-kokomo-server-1:/var/kokomo/uploads ./uploads_backup_$(date +%Y%m%d)

# Or backup using tar
tar -czf uploads_backup_$(date +%Y%m%d).tar.gz -C /var/lib/docker/volumes/kokomo_kokomo-uploads/_data .

# Sync to remote storage (S3, rsync, etc.)
aws s3 sync ./uploads_backup s3://your-backup-bucket/kokomo-uploads/

# Or use rsync to remote server
rsync -avz ./uploads_backup/ backup-server:/backups/kokomo-uploads/

Health Monitoring

Monitor your server health and set up alerts.

Health check endpoints

# Basic health check
curl https://kokomo.yourdomain.com/health
# Returns: {"status":"ok","version":"1.5.2"}

# Check Prometheus metrics (if enabled)
curl https://kokomo.yourdomain.com/metrics

Simple uptime monitoring script

#!/bin/bash
# save as check_kokomo.sh

HEALTH_URL="https://kokomo.yourdomain.com/health"
ALERT_EMAIL="admin@yourdomain.com"

response=$(curl -s -o /dev/null -w "%{http_code}" $HEALTH_URL)

if [ $response != "200" ]; then
  echo "Kokomo is down! HTTP $response" | mail -s "Kokomo Alert" $ALERT_EMAIL
fi

Log Management

Access and manage server logs for debugging.

Viewing logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f kokomo-server

# Last 100 lines
docker compose logs --tail=100 kokomo-server

# Since specific time
docker compose logs --since="2024-03-15T10:00:00" kokomo-server

# Filter by log level (if using JSON logs)
docker compose logs kokomo-server | grep '"level":"error"'

Log rotation (docker daemon.json)

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "50m",
    "max-file": "5"
  }
}

Resource Monitoring

Monitor container resources and database connections.

Docker resource usage

# Live resource usage
docker stats

# One-time snapshot
docker stats --no-stream

# Disk usage
docker system df
df -h

# Database connections
docker compose exec postgres psql -U kokomo -c "SELECT count(*) FROM pg_stat_activity;"

Complete Backup Script

backup_kokomo.sh

#!/bin/bash
set -e

# Configuration
BACKUP_DIR=~/backups/kokomo
KOKOMO_DIR=~/kokomo
RETENTION_DAYS=30
DATE=$(date +%Y%m%d_%H%M%S)

# Create backup directory
mkdir -p $BACKUP_DIR

echo "Starting Kokomo backup..."

# Backup database
echo "Backing up database..."
cd $KOKOMO_DIR
docker compose exec -T postgres pg_dump -U kokomo kokomo | gzip > $BACKUP_DIR/db_$DATE.sql.gz

# Backup uploads (if using local storage)
echo "Backing up uploads..."
docker cp kokomo-kokomo-server-1:/var/kokomo/uploads $BACKUP_DIR/uploads_$DATE 2>/dev/null || true
tar -czf $BACKUP_DIR/uploads_$DATE.tar.gz -C $BACKUP_DIR uploads_$DATE 2>/dev/null && rm -rf $BACKUP_DIR/uploads_$DATE || true

# Backup configuration
echo "Backing up configuration..."
cp $KOKOMO_DIR/.env $BACKUP_DIR/env_$DATE.bak
cp $KOKOMO_DIR/docker-compose.yml $BACKUP_DIR/docker-compose_$DATE.yml

# Cleanup old backups
echo "Cleaning up old backups..."
find $BACKUP_DIR -name "*.gz" -mtime +$RETENTION_DAYS -delete
find $BACKUP_DIR -name "*.bak" -mtime +$RETENTION_DAYS -delete
find $BACKUP_DIR -name "*.yml" -mtime +$RETENTION_DAYS -delete

echo "Backup completed: $BACKUP_DIR"
ls -lh $BACKUP_DIR/*$DATE*

Troubleshooting

Server not starting

• Check logs: docker compose logs kokomo-server
• Verify environment variables in .env
• Ensure PostgreSQL is healthy: docker compose ps

Database connection failed

• Check if postgres is running: docker compose ps postgres
• Restart postgres: docker compose restart postgres
• Verify DB_PASSWORD matches in .env

Out of disk space

• Clean Docker: docker system prune -a
• Clean old backups: find ~/backups -mtime +30 -delete
• Check uploads: du -sh /var/lib/docker/volumes/

Connect Clients All Documentation