KohakuHub/docs/deployment/docker.md

title, description, icon

title	description	icon
Docker Deployment	Complete Docker Compose setup guide for KohakuHub.	i-carbon-container-services

Docker Deployment

This guide provides a complete walkthrough for deploying KohakuHub using Docker Compose.

Quick Deploy (Recommended)

This is the easiest and fastest way to get KohakuHub running.

1. Clone the Repository

git clone https://github.com/KohakuBlueleaf/KohakuHub.git
cd KohakuHub

2. Configure and Deploy

First, run the interactive script to generate your docker-compose.yml file. This will guide you through setting up the database, storage, and other services.

python scripts/generate_docker_compose.py

Then, run the deployment script. This will automatically build the frontend applications and start all the Docker services.

python scripts/deploy.py

That's it! The application is now running.

Step-by-Step Setup

If you need more control over the setup process, you can follow these manual steps.

1. Clone the Repository

git clone https://github.com/KohakuBlueleaf/KohakuHub.git
cd KohakuHub

2. Generate docker-compose.yml

Copy the example file and manually edit it to fit your environment.

cp docker-compose.example.yml docker-compose.yml

3. Build the Frontend

Before starting the services, you need to build the frontend applications:

npm install --prefix src/kohaku-hub-ui
npm install --prefix src/kohaku-hub-admin
npm run build --prefix src/kohaku-hub-ui
npm run build --prefix src/kohaku-hub-admin

4. Start the Services

To start all services in detached mode, run:

docker-compose up -d --build

Security Configuration

It is critical to change the default secrets before deploying to production.

Generate Secret Keys

You can generate secure random strings for your secrets using the following commands:

# Generate a 64-character random string for session and admin tokens
python scripts/generate_secret.py 64

# Or use openssl
openssl rand -base64 48

Update the following variables in your docker-compose.yml with the generated secrets:

• KOHAKU_HUB_SESSION_SECRET
• KOHAKU_HUB_ADMIN_SECRET_TOKEN
• LAKEFS_AUTH_ENCRYPT_SECRET_KEY

Services

The Docker Compose setup includes the following services:

• hub-ui: Nginx server for the frontend application (port 28080).
• hub-api: The main FastAPI backend (port 48888).
• postgres: PostgreSQL database for metadata (port 5432).
• lakefs: LakeFS for data versioning (port 28000).
• minio: MinIO for S3-compatible object storage (ports 29000 and 29001).

Managing the Application

View Logs

To view the logs for all services, use:

docker-compose logs -f

To view the logs for a specific service, use:

docker-compose logs -f hub-api

Stop the Services

To stop all running services, use:

docker-compose down

Accessing the Application

• Web UI: http://localhost:28080
• Admin Portal: http://localhost:28080/admin
• API Docs: http://localhost:48888/docs
• LakeFS UI: http://localhost:28000
• MinIO Console: http://localhost:29000