Skip to main content
Deploy Kioku locally or on a VPS with Docker Compose.

​
Prerequisites

​
Setup

cd deployment/docker

# 1. Bootstrap .env (copies template, generates secure secrets, pulls images)
./scripts/setup.sh

# 2. Fill in your API keys and domain
$EDITOR .env

# 3. (Optional) Configure Cloudflare Tunnel
cp cloudflared.yml.example cloudflared.yml
# Edit cloudflared.yml with your tunnel ID + domains
# Set CLOUDFLARED_CREDENTIALS_DIR in .env

# 4. Start everything (stateful first, then stateless)
./scripts/manage.sh start

# 5. Verify health
./scripts/healthcheck.sh

​
Architecture

Compose FileServices
docker-compose.stateful.ymlPostgres (pgvector), Qdrant
docker-compose.stateless.ymlHivemind, all Vexa services, Ollama, Redis, MinIO, Cloudflared
Stateful services start first (data volumes), then stateless services connect to them.

​
Services

ServicePortDescription
Hivemind API9100Core API (auth, sessions, knowledge search, MCP)
Vexa API Gateway8056Meeting bot API
Vexa Admin API8057Admin operations
Vexa MCP18888Vexa MCP server
MinIO Console9001Object storage UI
Ollama11434Local embedding model server
Qdrant6333Vector DB REST API

​
Management Commands

./scripts/manage.sh start               # start all services
./scripts/manage.sh stop                # stop all (data preserved)
./scripts/manage.sh down               # stop and remove containers
./scripts/manage.sh down-volumes        # destroy ALL data
./scripts/manage.sh restart             # restart all services
./scripts/manage.sh status              # show running containers + resource usage
./scripts/manage.sh logs [service]      # tail logs
./scripts/manage.sh backup              # dump databases to backups/
./scripts/manage.sh restore <file>      # restore from backup
./scripts/manage.sh shell [service]     # open shell in a container
./scripts/manage.sh db-shell            # open psql shell
./scripts/manage.sh start-stateful      # start only postgres + qdrant
./scripts/manage.sh stop-stateful       # stop only postgres + qdrant

​
Cloudflare Tunnel

For public access without opening inbound ports, use Cloudflare Tunnel:
  1. Create a tunnel at Cloudflare Zero Trust
  2. Download the credentials JSON to your machine
  3. Set CLOUDFLARED_CREDENTIALS_DIR in .env to the folder containing the JSON
  4. Copy and edit the tunnel config:
cp cloudflared.yml.example cloudflared.yml
  1. Edit with your tunnel ID and domains:
tunnel: <your-tunnel-id>
credentials-file: /etc/cloudflared/creds/<your-tunnel-id>.json

ingress:
  - hostname: api.example.com
    service: http://kioku-hivemind:9100
  - hostname: meetings.example.com
    service: http://vexa-api-gateway:8000
  - service: http_status:404