Kizuna Help

Appearance

This guide covers installing Kizuna OSS for production use.

System Requirements ​

Minimum (Small Team) ​

ResourceRequirement
CPU2 cores
RAM4 GB
Storage50 GB SSD
Network100 Mbps
ResourceRequirement
CPU4+ cores
RAM8+ GB
Storage200+ GB SSD
Network1 Gbps

Prerequisites ​

  • Docker 24.0+ and Docker Compose 2.0+
  • Or Kubernetes 1.28+ with Helm 3.0+
  • External PostgreSQL 16+ (optional, can use container)
  • External Valkey/Redis 7+ (optional, can use container)
  • S3-compatible object storage (optional, for artifacts)

Docker Compose Installation ​

1. Create Installation Directory ​

bash
mkdir -p /opt/kizuna
cd /opt/kizuna

2. Download Configuration ​

bash
# Docker Compose file
curl -O https://raw.githubusercontent.com/kizuna-platform/kizuna/main/docker-compose.yml

# Environment template
curl -O https://raw.githubusercontent.com/kizuna-platform/kizuna/main/.env.example -o .env

3. Configure Environment ​

Edit .env:

bash
# Database
DATABASE_URL=postgres://kizuna:secure_password@postgres:5432/kizuna

# Secret key (generate with: openssl rand -base64 48)
SECRET_KEY_BASE=your-generated-secret-key

# Host configuration
PHX_HOST=kizuna.yourdomain.com
PORT=4000

# Object storage (optional, for CI artifacts)
# S3_ENDPOINT=https://s3.amazonaws.com
# S3_BUCKET=kizuna-artifacts
# S3_ACCESS_KEY=your-access-key
# S3_SECRET_KEY=your-secret-key

4. Start Services ​

bash
docker-compose up -d

5. Database Setup ​

bash
# Run migrations
docker-compose exec kizuna bin/migrate

# Create admin user
docker-compose exec kizuna bin/kizuna eval "KizunaCore.Release.create_admin('[email protected]', 'your-secure-password')"

6. Verify Installation ​

bash
# Check all services are running
docker-compose ps

# View logs
docker-compose logs -f kizuna

Access Kizuna at http://localhost:4000 (or your configured PHX_HOST).

Kubernetes Installation ​

Using Helm ​

1. Add Kizuna Helm Repository ​

bash
helm repo add kizuna https://charts.kizuna.codes
helm repo update

2. Create Namespace ​

bash
kubectl create namespace kizuna

3. Install Chart ​

bash
helm install kizuna kizuna/kizuna \
  --namespace kizuna \
  --set ingress.host=kizuna.yourdomain.com \
  --set postgresql.auth.password=secure-password \
  --set secretKeyBase=$(openssl rand -base64 48)

Note: Make sure to set required values when installing:

bash
helm install kizuna kizuna/kizuna \
  --set kizuna.secretKeyBase=$(openssl rand -hex 64) \
  --set postgresql.auth.password=$(openssl rand -hex 16) \
  --set kizuna.host=kizuna.yourdomain.com

4. Verify Installation ​

bash
kubectl get pods -n kizuna

Manual Manifests ​

For custom deployments, use the Kubernetes manifests in the k8s directory:

bash
git clone https://github.com/kizuna-platform/kizuna.git
cd kizuna/k8s

# Apply manifests
kubectl apply -k overlays/production/

Source Installation (Advanced) ​

For development or custom builds:

Prerequisites ​

  • Elixir 1.19+ with OTP 28+
  • Rust 1.85+ (edition 2024)
  • PostgreSQL 16+
  • Valkey or Redis 7+

1. Clone Repository ​

bash
git clone https://github.com/kizuna-platform/kizuna.git
cd kizuna

2. Install Elixir Dependencies ​

bash
cd kizuna
mix deps.get
mix compile

3. Build Rust Subsystems ​

bash
cd ../rust
cargo build --release

4. Database Setup ​

bash
# Create database
cd ../kizuna
mix ecto.create
mix ecto.migrate

5. Start Server ​

bash
mix phx.server

SSL/HTTPS Configuration ​

Configure Nginx or Traefik in front of Kizuna:

nginx
server {
    listen 443 ssl http2;
    server_name kizuna.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:4000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Using Let's Encrypt with Docker ​

yaml
# Add to docker-compose.yml
services:
  traefik:
    image: traefik:v3.0
    command:
      - "--providers.docker=true"
      - "--entrypoints.websecure.address=:443"
      - "--certificatesresolvers.letsencrypt.acme.tlschallenge=true"
      - "--certificatesresolvers.letsencrypt.acme.email=admin@yourdomain.com"
      - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
    ports:
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./letsencrypt:/letsencrypt

Post-Installation ​

1. Configure External Authentication (Optional) ​

Kizuna supports OIDC providers for SSO:

bash
# Via environment or UI
KIZUNA_OIDC_PROVIDER=okta
KIZUNA_OIDC_CLIENT_ID=your-client-id
KIZUNA_OIDC_CLIENT_SECRET=your-client-secret

2. Set Up Backup ​

bash
# Database backup script
#!/bin/bash
docker-compose exec -T postgres pg_dump -U kizuna kizuna > backup-$(date +%Y%m%d).sql

3. Configure Monitoring ​

Kizuna exposes Prometheus metrics at /metrics:

yaml
# prometheus.yml
scrape_configs:
  - job_name: 'kizuna'
    static_configs:
      - targets: ['kizuna:4000']

Troubleshooting ​

Services Won't Start ​

bash
# Check logs
docker-compose logs kizuna

# Common: Database connection failed
# Solution: Ensure postgres is healthy first
docker-compose up -d postgres
sleep 10
docker-compose up -d kizuna

Permission Denied Errors ​

bash
# Fix data directory permissions
sudo chown -R 1000:1000 ./data

High Memory Usage ​

Reduce connection pools in .env:

bash
POOL_SIZE=10

Next Steps ​