Installation¶

Get Kraken running locally with Docker Compose. This is the fastest way to start — all services (backend, frontend, MongoDB, Redis) are managed for you.

Prerequisites¶

• Docker (v20+) and Docker Compose (v2+)
• Git

Quick start¶

1. Clone the repository¶

git clone https://github.com/krakenchat/kraken.git
cd kraken

2. Configure environment¶

cp backend/env.sample backend/.env

Edit backend/.env and change the JWT secrets:

JWT_SECRET=replace-with-a-long-random-string
JWT_REFRESH_SECRET=replace-with-a-different-long-random-string

See the Configuration page for the full environment variable reference.

3. Start all services¶

docker-compose up

This brings up:

4. Initialize the database¶

On first run, push the Prisma schema to MongoDB:

docker compose run --rm backend npm run prisma

This generates the Prisma client and pushes the schema to the database.

5. Open Kraken¶

Visit http://localhost:5173 in your browser. You're ready to create your first account.

Stopping and restarting¶

# Stop all services
docker-compose down

# Start again (data is persisted in Docker volumes)
docker-compose up

# Full reset (removes all data)
docker-compose down -v

Voice and video (optional)¶

Kraken uses LiveKit for voice and video calls. Without LiveKit configured, everything else works — voice/video features are simply disabled.

To enable voice and video:

1. Sign up at LiveKit Cloud or run a self-hosted LiveKit server
2. Add credentials to backend/.env:

   LIVEKIT_URL=wss://your-livekit-server.com
   LIVEKIT_API_KEY=your-api-key
   LIVEKIT_API_SECRET=your-api-secret
   

3. Configure webhooks — LiveKit needs to send events back to Kraken for voice presence tracking. Set the webhook URL to https://your-kraken-domain.com/api/livekit/webhook and enable these events:
   • participant_joined
   • participant_left
   • egress_started
   • egress_updated
   • egress_ended

See the Configuration page for all LiveKit-related variables.

Troubleshooting¶

"Replica set not initialized"¶

The Docker Compose setup automatically configures the MongoDB replica set. If you see this error, restart the containers:

docker-compose down && docker-compose up

"Port already in use"¶

Check what's using the port and stop it:

lsof -i :3000  # Backend
lsof -i :5173  # Frontend

"Prisma client not generated"¶

Run the Prisma setup again:

docker compose run --rm backend npm run prisma

Containers won't start¶

Rebuild from scratch:

docker-compose down -v
docker-compose build --no-cache
docker-compose up

Next steps¶

• Configuration — Full environment variable reference
• First Run — Create your first user, community, and channels
• Development Setup — Set up for contributing