Kokomo
Back to Documentation

Self-Hosting

Installation Guide

Deploy Kokomo Server on your own infrastructure using Docker.

RECOMMENDED

One-Click Install

Install Kokomo on your Ubuntu/Debian server with a single command. Handles Docker installation, configuration, and startup automatically.

Terminal
curl -fsSL https://kokomo.macroblink.io/install.sh | bash
Auto Docker Install
Installs Docker if not present
Interactive Setup
Prompts for domain, email, password
Auto-generated Secrets
Secure JWT and DB passwords
Auto HTTPS (Caddy)
Let's Encrypt SSL included

After installation: Your server will be running at https://your-domain.com. Configuration files are saved in ~/kokomo/.

Or install manually

Technology Stack

Go 1.23
Runtime
Fiber
Web Framework
PostgreSQL 15
Database
Redis 7
Cache & Sessions

1System Requirements

Minimum

  • 1 vCPU
  • 1GB RAM
  • 20GB SSD
  • ~100 users

Recommended

  • 2 vCPU
  • 2GB RAM
  • 40GB SSD
  • ~1,000 users

Enterprise

  • 4+ vCPU
  • 4GB+ RAM
  • 100GB+ SSD
  • 5,000+ users
  • Docker Engine 20.10+ and Docker Compose v2.0+
  • Domain name (required for SSL/HTTPS)
  • Ports 80, 443 available

2Install Docker

Ubuntu/Debian
# Install Docker
curl -fsSL https://get.docker.com | sh

# Add your user to docker group
sudo usermod -aG docker $USER

# Log out and back in, then verify
docker --version
docker compose version

3Create Project Directory

Terminal
# Create Kokomo directory
mkdir -p ~/kokomo && cd ~/kokomo

4Create docker-compose.yml

docker-compose.yml
version: '3.8'

services:
  # Kokomo API Server
  kokomo-server:
    image: macroblink/kokomo-server:latest
    ports:
      - "8080:8080"
    environment:
      - DATABASE_URL=postgres://kokomo:${DB_PASSWORD}@postgres:5432/kokomo?sslmode=disable
      - REDIS_URL=redis://redis:6379
      - JWT_SECRET=${JWT_SECRET}
      - JWT_REFRESH_SECRET=${JWT_REFRESH_SECRET}
      - PORT=8080
      - ENV=production
      - BASE_URL=${BASE_URL}
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_started
    networks:
      - kokomo-network
    volumes:
      - kokomo-uploads:/var/kokomo/uploads
    restart: unless-stopped

  # PostgreSQL Database
  postgres:
    image: postgres:15-alpine
    environment:
      - POSTGRES_USER=kokomo
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=kokomo
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - kokomo-network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U kokomo"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  # Redis (Caching & Sessions)
  redis:
    image: redis:7-alpine
    volumes:
      - redis-data:/data
    networks:
      - kokomo-network
    command: redis-server --appendonly yes
    restart: unless-stopped

  # Nginx (Reverse Proxy) - Optional
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - kokomo-uploads:/var/www/uploads
    depends_on:
      - kokomo-server
    networks:
      - kokomo-network
    restart: unless-stopped

volumes:
  postgres-data:
  redis-data:
  kokomo-uploads:

networks:
  kokomo-network:
    driver: bridge

5Configure Environment

Create .env file with your settings:

.env
# Server
ENV=production
PORT=8080
BASE_URL=https://kokomo.yourdomain.com

# Database Password (change this!)
DB_PASSWORD=your-secure-database-password

# JWT Secrets (generate with: openssl rand -hex 64)
JWT_SECRET=your-64-char-random-secret-string-here
JWT_REFRESH_SECRET=another-64-char-random-secret-string

# Token Expiration
JWT_EXPIRATION_MINUTES=15
JWT_REFRESH_EXPIRATION_DAYS=7

# File Storage
UPLOAD_DIR=/var/kokomo/uploads
MAX_UPLOAD_SIZE_MB=50

# CORS (your client domains)
CORS_ALLOWED_ORIGINS=https://kokomo.yourdomain.com

# Rate Limiting
RATE_LIMIT_ENABLED=true
RATE_LIMIT_WINDOW_SECONDS=60
RATE_LIMIT_MAX_REQUESTS=100

Important: Generate secure secrets:

openssl rand -hex 64

6Start the Server

Terminal
# Start all services
docker compose up -d

# Check status
docker compose ps

# View logs
docker compose logs -f kokomo-server

Services started:

  • kokomo-server - Main API and WebSocket server (port 8080)
  • postgres - PostgreSQL 15 database
  • redis - Redis 7 cache with AOF persistence
  • nginx - Reverse proxy (optional, ports 80/443)

7Verify Installation

Terminal
# Health check
curl http://localhost:8080/health

# Expected response:
{"status":"ok","version":"1.0.0"}

# Access Swagger API Documentation
# Open in browser: http://localhost:8080/swagger/

Your Kokomo server is running! Database tables are auto-created on first startup.

Next Steps

Configuration

All environment variables

SSL & Domain

Set up HTTPS (required)

Connect Clients

Connect desktop and mobile apps

Maintenance

Backups and upgrades

SANDBOX MODE