Complete installation guide for Burning Ash Protocol using Docker Compose or manual setup.

Installation Guide

This guide covers installing Burning Ash Protocol using Docker Compose (recommended) or manually on your own server.

Prerequisites

Before installing BAP, ensure you have:

A server with Linux (Ubuntu 20.04+ recommended)
At least 2GB RAM and 10GB storage
Docker and Docker Compose (for Docker installation)
Or Go 1.26+ and Node.js 20+ (for manual installation)
A domain name with DNS configured (for production)
SSL/TLS certificates (Let's Encrypt recommended)

Option 1: Docker Compose (Recommended)

Docker Compose is the fastest way to get BAP running with all components.

Step 1: Clone the Repository

git clone https://github.com/baprotocol/bap.git
cd bap

Step 2: Configure Environment Variables

Copy the example environment file and generate secrets:

make env
make generate-key

Then edit .env with your settings:

Edit .env with your settings:

# Required - generate a secure random string
JWT_SECRET=your-super-secret-jwt-key-min-32-chars
MASTER_KEY=your-master-encryption-key-exactly-32-bytes

# Optional - customize ports
API_PORT=8080
WEB_PORT=3000

# Optional - database (sqlite default, use postgres for production)
DB_TYPE=sqlite
# DB_TYPE=postgres
# DATABASE_URL=postgresql://bap:password@postgres:5432/bap

# Optional - production settings
CORS_ORIGINS=https://yourdomain.com
FRONTEND_URL=https://yourdomain.com
NEXT_PUBLIC_API_URL=https://yourdomain.com/api

Step 3: Generate Secure Keys

Generate secure keys for JWT and master encryption:

# Generate JWT secret (32+ characters)
openssl rand -base64 32

# Generate master key (32 bytes hex = 64 characters)
openssl rand -hex 32

Step 4: Start BAP

# Start all services
docker compose up -d

# View logs
docker compose logs -f

Step 5: Verify Installation

Check that all services are running:

docker compose ps

You should see:

api — Running on port 8080
web — Running on port 3000

Step 6: Access the Dashboard

Open your browser and navigate to:

Host Dashboard: http://localhost:3000
API Health: http://localhost:8080/api/health

Option 2: Manual Installation

For more control or custom deployments, install components manually.

Database Setup

SQLite (Development)

# Create data directory
mkdir -p /opt/bap/data

# Database is created automatically on first run

PostgreSQL (Production)

# Install PostgreSQL
sudo apt update
sudo apt install postgresql postgresql-contrib

# Create database
sudo -u postgres createdb bap
sudo -u postgres createuser bap -P  # Enter password when prompted

# Grant privileges
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE bap TO bap;"

Backend Installation

# Clone and build
git clone https://github.com/baprotocol/bap.git
cd bap/api
go build -o bap ./cmd/api

# Create data directory
mkdir -p /opt/bap/data

# Configure environment
export JWT_SECRET="your-jwt-secret-min-32-chars"
export MASTER_KEY="$(openssl rand -hex 32)"
export DB_TYPE=postgres
export DATABASE_URL="postgresql://bap:password@localhost:5432/bap"

# Start the API server (migrations run automatically)
./bap

Frontend Installation

# Navigate to web directory
cd bap/web

# Install dependencies
npm install

# Build for production
npm run build

# Start the production server
NODE_ENV=production npm start

Using Systemd (Linux)

Create a systemd service file:

sudo nano /etc/systemd/system/bap-api.service

[Unit]
Description=Burning Ash Protocol API
After=network.target

[Service]
Type=simple
User=bap
WorkingDirectory=/opt/bap
ExecStart=/opt/bap/api/bap serve
EnvironmentFile=/opt/bap/.env
Restart=always

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable bap-api
sudo systemctl start bap-api

Production Deployment

SSL/TLS with Nginx

Install Nginx and configure SSL:

sudo apt install nginx certbot python3-certbot-nginx

Create Nginx config:

sudo nano /etc/nginx/sites-available/bap

server {
    listen 80;
    server_name yourdomain.com;
    return 301 https://$server_name$request_uri;
}

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

    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

    # Frontend
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }

    # API
    location /api {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Enable the site:

sudo ln -s /etc/nginx/sites-available/bap /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

# Get SSL certificate
sudo certbot --nginx -d yourdomain.com

Firewall Configuration

# Allow SSH, HTTP, HTTPS
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Configuration Reference

Environment Variables

Variable	Required	Default	Description
`API_PORT`	No	8080	API server port
`DB_TYPE`	No	sqlite	Database type: `sqlite` or `postgres`
`DATABASE_PATH`	No	./data/bap.db	SQLite database path
`DATABASE_URL`	For postgres	-	PostgreSQL connection string
`JWT_SECRET`	Yes	-	Secret for JWT signing (32+ chars)
`MASTER_KEY`	Yes	-	Master encryption key (32 bytes hex)
`CORS_ORIGINS`	No	http://localhost:3000	Allowed CORS origins
`FRONTEND_URL`	No	http://localhost:3000	Frontend URL for redirects
`NEXT_PUBLIC_API_URL`	No	http://localhost:8080/api	API URL for frontend

OAuth Configuration

For Google Drive and Dropbox storage:

# Google OAuth
GOOGLE_OAUTH_CLIENT_ID=your-client-id
GOOGLE_OAUTH_CLIENT_SECRET=your-client-secret
GOOGLE_OAUTH_REDIRECT_URL=https://yourdomain.com/api/storages/oauth/callback

# Dropbox OAuth  
DROPBOX_APP_KEY=your-app-key
DROPBOX_APP_SECRET=your-app-secret
DROPBOX_OAUTH_REDIRECT_URL=https://yourdomain.com/api/storages/oauth/callback

Upgrading

See the Upgrading Guide for version-specific upgrade instructions.

Troubleshooting

Common Issues

API won't start - port in use:

# Find what's using the port
sudo lsof -i :8080
# Kill the process or change the port in .env

Database connection errors:

For SQLite: Ensure the data directory is writable
For PostgreSQL: Verify credentials and database exist

OAuth failures:

Check redirect URLs match exactly in OAuth console
Ensure SSL is working (OAuth requires HTTPS)

Logs

# Docker logs
docker compose logs api
docker compose logs web

# Systemd logs
journalctl -u bap-api -f

Next Steps

Quickstart Guide — Get started in 5 minutes
Configuration — Full configuration reference
Architecture Overview — Understand the system design

Installation Guide

On this page