Skip to main content

Quick Start

Get Bloqd running in 5 minutes using Docker.

Prerequisites​

  • Docker and Docker Compose installed
  • A server with at least 1GB RAM
  • Port 3000 available (or configure a different port)

Step 1: Create Project Directory​

mkdir bloqd && cd bloqd

Step 2: Create Docker Compose File​

Create a docker-compose.yaml file:

docker-compose.yaml
services:
  bloqd:
    image: clusterzx/bloqd:latest
    container_name: bloqd
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data
    environment:
      - NODE_ENV=production
      - PORT=3000
      - API_KEY_SALT=${API_KEY_SALT}
      - API_BASE_URL=${API_BASE_URL}
    restart: unless-stopped

Step 3: Create Environment File​

Create a .env file with your configuration:

.env
# Required: Generate a unique salt for API key hashing
API_KEY_SALT=your-random-32-character-string-here

# Required: External URL that agents will use to connect
API_BASE_URL=https://bloqd.example.com
Generate a Random Salt
openssl rand -hex 16

Step 4: Start Bloqd​

docker compose up -d

Open your browser:

http://localhost:3000

Step 5: Complete Setup Wizard​

On first launch, Bloqd displays a setup wizard:

  1. Create Admin Account - Set your admin username and password
  2. Configure SMTP (optional) - For email notifications
  3. Complete Setup - Finalize the configuration

Step 6: Add Your First Server​

  1. Navigate to Servers → Add Server
  2. Enter a name for your server (e.g., "web-01")
  3. Select the jails you want to enable (sshd is recommended)
  4. Click Generate Install Command

You'll get a one-liner like this:

curl -sSL https://your-bloqd-server.com/api/v1/installer/script/inst_xxxxx | sudo bash
  1. SSH into your target server and run the command
  2. Wait for installation to complete

What's Next?​

Troubleshooting​

Container won't start​

docker compose logs -f bloqd

Server not connecting​

  • Ensure API_BASE_URL is set correctly
  • Check the agent logs: journalctl -u bloqd-agent -f

For more help, see Troubleshooting.