Self-Hosting

Database Setup

Configure PostgreSQL and Redis for production workloads.

Using Docker (Recommended)

The default docker-compose.yml includes PostgreSQL and Redis. No additional setup required.

docker-compose.yml (database section)

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

volumes:
  postgres-data:
  redis-data:

Auto-Migration: Kokomo automatically creates all required tables on first startup using GORM migrations. No manual SQL setup needed.

Auto-Created Tables

The following tables are automatically created on server startup:

Core

users - User accounts
teams - Organizations
departments - Org hierarchy
team_users - User-team relations

Messaging

rooms - Chat rooms
messages - Chat messages
message_files - Attachments
message_reactions - Emoji reactions

Feed

feeds - Feed posts
feed_replies - Comments
feed_likes - Like tracking
feedgroups - Feed channels

Storage & More

files - File metadata
todos - Task management
notifications - User inbox
user_presence - Online status

External PostgreSQL

Connect to an existing PostgreSQL server or managed database service.

Requirements

PostgreSQL 13 or higher
A dedicated database for Kokomo
User with CREATE, ALTER, DROP privileges

Setup Steps

Create database and user

-- Connect as superuser
psql -U postgres

-- Create user
CREATE USER kokomo WITH PASSWORD 'your-secure-password';

-- Create database
CREATE DATABASE kokomo OWNER kokomo;

-- Grant privileges
GRANT ALL PRIVILEGES ON DATABASE kokomo TO kokomo;

-- Enable UUID extension (required)
\c kokomo
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

.env configuration

# Using DATABASE_URL
DATABASE_URL=postgres://kokomo:your-secure-password@your-db-host:5432/kokomo?sslmode=require

# Or individual variables
DB_HOST=your-db-host.com
DB_PORT=5432
DB_USER=kokomo
DB_PASSWORD=your-secure-password
DB_NAME=kokomo
DB_SSLMODE=require

Managed Databases: For AWS RDS, Google Cloud SQL, DigitalOcean, or other managed services, use the connection string provided by your cloud provider.

External Redis

Connect to an existing Redis server or managed service like AWS ElastiCache.

Requirements

Redis 6 or higher
Persistence enabled (AOF recommended)
At least 512MB memory

.env configuration

# Enable Redis
USE_REDIS=true

# Using individual variables
REDIS_HOST=your-redis-host.com
REDIS_PORT=6379
REDIS_PASSWORD=your-redis-password
REDIS_DB=0

# Or using REDIS_URL
REDIS_URL=redis://:your-redis-password@your-redis-host:6379/0

Performance Tuning

Recommended settings for production workloads.

PostgreSQL Configuration

postgresql.conf

# Memory (adjust based on available RAM)
shared_buffers = 256MB
effective_cache_size = 1GB
work_mem = 16MB

# Connections
max_connections = 100

# WAL
wal_buffers = 16MB
checkpoint_completion_target = 0.9

# Query Planning
random_page_cost = 1.1
effective_io_concurrency = 200

Redis Configuration

Redis memory policy

# In redis.conf or via CONFIG SET
maxmemory 512mb
maxmemory-policy allkeys-lru

Connection Pool Settings

.env connection pool

# Adjust based on expected traffic
# Light traffic (~100 users)
DB_MAX_CONNECTIONS=10
DB_MAX_IDLE_CONNECTIONS=5

# Medium traffic (~1000 users)
DB_MAX_CONNECTIONS=25
DB_MAX_IDLE_CONNECTIONS=10

# Heavy traffic (5000+ users)
DB_MAX_CONNECTIONS=50
DB_MAX_IDLE_CONNECTIONS=20

Database Management

Useful commands for managing your database.

Connect to PostgreSQL (Docker)

# Interactive psql shell
docker compose exec postgres psql -U kokomo kokomo

# Run a single command
docker compose exec postgres psql -U kokomo kokomo -c "SELECT COUNT(*) FROM users;"

# Check database size
docker compose exec postgres psql -U kokomo kokomo -c "SELECT pg_size_pretty(pg_database_size('kokomo'));"

# List all tables
docker compose exec postgres psql -U kokomo kokomo -c "\dt"

Check Redis (Docker)

# Connect to Redis CLI
docker compose exec redis redis-cli

# Check memory usage
docker compose exec redis redis-cli INFO memory

# Get all keys count
docker compose exec redis redis-cli DBSIZE

# Flush cache (use with caution)
docker compose exec redis redis-cli FLUSHDB

Configuration SSL & Domain