Skip to main content

Docker Installation

Docker is the recommended way to deploy Bloqd. This guide covers the complete setup process.

Prerequisites​

Ensure you have Docker and Docker Compose installed:

# Check Docker version
docker --version

# Check Docker Compose version
docker compose version

If not installed, follow the official Docker installation guide for your OS:

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
    env_file:
      - .env
    restart: unless-stopped
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Step 3: Create Environment File​

Create a .env file with your configuration:

.env
# ===========================================
# REQUIRED SETTINGS
# ===========================================

# Server Configuration
NODE_ENV=production
PORT=3000
HOST=0.0.0.0

# Security - REQUIRED: Generate a unique salt
# Use: openssl rand -hex 16
API_KEY_SALT=your-random-32-character-string-here

# External URL that agents will use to connect
# Set this to your public URL or IP
API_BASE_URL=https://bloqd.example.com

# ===========================================
# OPTIONAL SETTINGS
# ===========================================

# Database location (inside container)
DATABASE_PATH=/app/data/bloqd.db

# Base URL for email links (password reset, etc.)
BASE_URL=https://bloqd.example.com

# Logging level: debug, info, warn, error
LOG_LEVEL=info

# ===========================================
# INTEGRATIONS (Optional)
# ===========================================

# AbuseIPDB - Automatic abuse reporting
ABUSEIPDB_ENABLED=false
ABUSEIPDB_API_KEY=your-abuseipdb-api-key
ABUSEIPDB_RATE_LIMIT=1000

# Discord - Real-time notifications
DISCORD_ENABLED=false
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/xxx/xxx
DISCORD_NOTIFY_BANS=true
DISCORD_NOTIFY_SYNCS=true
DISCORD_NOTIFY_ERRORS=true
DISCORD_DAILY_SUMMARY=true
DISCORD_DAILY_SUMMARY_HOUR=8

See Environment Variables for all available options.

Generate a Secure Salt​

# Linux/Mac
openssl rand -hex 16

# Or using Node.js
node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"
Important

The API_KEY_SALT is used to hash API keys. If you change it after deployment, all existing API keys will stop working.

Step 4: Start Bloqd​

Pull the latest image and start:

docker compose pull
docker compose up -d

Check the logs:

docker compose logs -f bloqd

You should see:

bloqd  | [INFO] Bloqd server starting...
bloqd  | [INFO] Database initialized
bloqd  | [INFO] Server listening on 0.0.0.0:3000

Step 5: Access the Dashboard​

Open your browser and navigate to:

http://your-server-ip:3000

On first access, you'll see the Setup Wizard:

  1. Create Admin Account

    • Enter username and password
    • This will be your primary admin account

  2. Configure SMTP (Optional)

    • Set up email for notifications
    • Can be skipped and configured later

  3. Complete Setup

    • Click to finalize

Docker Image Tags​

TagDescription
latestLatest stable release
x.y.zSpecific version (e.g., 1.2.4)
devDevelopment build (unstable)
# Use specific version
image: clusterzx/bloqd:1.2.4

Managing the Container​

View Logs​

# Follow logs
docker compose logs -f bloqd

# Last 100 lines
docker compose logs --tail 100 bloqd

Stop Bloqd​

docker compose stop

Restart Bloqd​

docker compose restart

Update Bloqd​

# Pull latest image
docker compose pull

# Recreate container with new image
docker compose up -d

Remove Everything​

# Stop and remove container
docker compose down

# Remove data as well (DESTRUCTIVE!)
docker compose down -v
rm -rf ./data

Advanced Configuration​

Custom Port​

To use a different port:

ports:
  - "8080:3000"  # Host:Container

Update API_BASE_URL accordingly:

API_BASE_URL=https://bloqd.example.com:8080

Persistent Data​

The ./data directory stores:

  • SQLite database (bloqd.db)
  • Database journals
Backup

To backup Bloqd, simply copy the ./data directory while the container is stopped.

Resource Limits​

Add resource limits for production:

services:
  bloqd:
    # ... other config
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
        reservations:
          memory: 256M

Health Checks​

The container includes automatic health checks. Verify status:

docker inspect bloqd --format='{{.State.Health.Status}}'

Log Rotation​

Default configuration limits logs to 10MB with 3 files. Adjust as needed:

logging:
  driver: json-file
  options:
    max-size: "50m"
    max-file: "5"

Network Configuration​

For advanced networking (e.g., with Traefik):

services:
  bloqd:
    image: clusterzx/bloqd:latest
    networks:
      - traefik
      - default
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.bloqd.rule=Host(`bloqd.example.com`)"

networks:
  traefik:
    external: true

Production Checklist​

Before going to production, ensure:

  • API_KEY_SALT is a secure random string
  • API_BASE_URL points to your public URL
  • HTTPS is configured (via reverse proxy)
  • Firewall allows only necessary ports
  • Regular backups are scheduled
  • Resource limits are set
  • Log rotation is configured

Troubleshooting​

Container Won't Start​

Check the logs:

docker compose logs bloqd

Common issues:

  • Port already in use: Change the port mapping
  • Permission denied on data dir: chmod 755 ./data
  • Missing environment variables: Check .env file exists

Database Errors​

If you see database errors:

# Stop container
docker compose stop

# Check database file
ls -la ./data/

# Remove corrupted database (DESTRUCTIVE!)
rm ./data/bloqd.db*

# Start fresh
docker compose up -d

Memory Issues​

If the container is killed (OOMKilled):

# Check container stats
docker stats bloqd

Increase memory limits in docker-compose.yaml.

Can't Connect from Agents​

  1. Verify API_BASE_URL is correct
  2. Check firewall allows inbound traffic
  3. Test connectivity: curl https://bloqd.example.com/health

Next Steps​