Environment Variables

Complete reference of all environment variables for configuring Bloqd.

Required Variables

These variables must be set for Bloqd to function properly.

Variable	Description	Example
API_KEY_SALT	Salt for hashing API keys. Must be unique and secret.	a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
API_BASE_URL	External URL that agents use to connect	https://bloqd.example.com

Critical Security Setting

The API_KEY_SALT is used to hash all API keys. If you change it after deployment:

• All existing API keys will stop working
• All connected agents will lose access
• You'll need to regenerate all keys

Generate a secure salt:

openssl rand -hex 16

Server Configuration

Variable	Description	Default
NODE_ENV	Environment mode (development or production)	production
PORT	HTTP port to listen on	3000
HOST	IP address to bind to	0.0.0.0
DATABASE_PATH	Path to SQLite database file	./data/bloqd.db
BASE_URL	Base URL for email links (password reset, etc.)	http://localhost:5173
LOG_LEVEL	Logging verbosity: debug, info, warn, error	info

Example

NODE_ENV=production
PORT=3000
HOST=0.0.0.0
DATABASE_PATH=/app/data/bloqd.db
BASE_URL=https://bloqd.example.com
LOG_LEVEL=info

Authentication

Variable	Description	Default
JWT_SECRET	Secret for signing JWT access tokens	Auto-generated
JWT_REFRESH_SECRET	Secret for signing JWT refresh tokens	Auto-generated
ADMIN_SETUP_KEY	Initial admin setup key (optional)	-

Auto-Generated Secrets

JWT_SECRET and JWT_REFRESH_SECRET are automatically generated on first startup and saved to your .env file. You don't need to set these manually.

AbuseIPDB Integration

Report malicious IPs to AbuseIPDB automatically.

Variable	Description	Default
ABUSEIPDB_ENABLED	Enable AbuseIPDB integration	false
ABUSEIPDB_API_KEY	Your AbuseIPDB API key	-
ABUSEIPDB_RATE_LIMIT	Maximum reports per rolling window	1000

Example

ABUSEIPDB_ENABLED=true
ABUSEIPDB_API_KEY=abc123def456ghi789jkl012mno345pqr678
ABUSEIPDB_RATE_LIMIT=1000

Getting an API Key

1. Create an account at abuseipdb.com
2. Go to Account → API
3. Create a new API key
4. Copy the key to your .env file

Discord Integration

Receive real-time notifications in Discord.

Variable	Description	Default
DISCORD_ENABLED	Enable Discord notifications	false
DISCORD_WEBHOOK_URL	Discord webhook URL	-
DISCORD_NOTIFY_BANS	Send notifications for new bans	true
DISCORD_NOTIFY_SYNCS	Send notifications for sync events	true
DISCORD_NOTIFY_ERRORS	Send notifications for errors	true
DISCORD_DAILY_SUMMARY	Send daily summary reports	true
DISCORD_DAILY_SUMMARY_HOUR	Hour (UTC) to send daily summary (0-23)	8

Example

DISCORD_ENABLED=true
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/123456789/abcdefghijklmnop
DISCORD_NOTIFY_BANS=true
DISCORD_NOTIFY_SYNCS=true
DISCORD_NOTIFY_ERRORS=true
DISCORD_DAILY_SUMMARY=true
DISCORD_DAILY_SUMMARY_HOUR=8

Creating a Webhook

1. Open Discord and go to your server
2. Server Settings → Integrations → Webhooks
3. Click New Webhook
4. Choose a channel and name
5. Copy the webhook URL

Complete Example

Here's a complete .env file with all options:

.env

# ===========================================
# SERVER CONFIGURATION
# ===========================================
NODE_ENV=production
PORT=3000
HOST=0.0.0.0
DATABASE_PATH=/app/data/bloqd.db
LOG_LEVEL=info

# ===========================================
# URLS
# ===========================================
# External URL for agent connections (REQUIRED)
API_BASE_URL=https://bloqd.example.com

# Base URL for email links
BASE_URL=https://bloqd.example.com

# ===========================================
# SECURITY (REQUIRED)
# ===========================================
# Generate with: openssl rand -hex 16
API_KEY_SALT=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

# Optional: Initial admin key for setup
# ADMIN_SETUP_KEY=your-setup-key

# JWT secrets (auto-generated if not set)
# JWT_SECRET=
# JWT_REFRESH_SECRET=

# ===========================================
# ABUSEIPDB INTEGRATION
# ===========================================
ABUSEIPDB_ENABLED=true
ABUSEIPDB_API_KEY=your-abuseipdb-api-key-here
ABUSEIPDB_RATE_LIMIT=1000

# ===========================================
# DISCORD INTEGRATION
# ===========================================
DISCORD_ENABLED=true
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

Docker Compose with Environment Variables

When using Docker Compose, you can either use an .env file or set variables directly:

Using .env File (Recommended)

docker-compose.yaml

services:
  bloqd:
    image: clusterzx/bloqd:latest
    env_file:
      - .env
    # ...

Direct Environment Variables

docker-compose.yaml

services:
  bloqd:
    image: clusterzx/bloqd:latest
    environment:
      - NODE_ENV=production
      - PORT=3000
      - API_KEY_SALT=${API_KEY_SALT}
      - API_BASE_URL=https://bloqd.example.com
      - DISCORD_ENABLED=true
      - DISCORD_WEBHOOK_URL=${DISCORD_WEBHOOK_URL}
    # ...

Mixed Approach

Use .env for secrets and inline for non-sensitive values:

docker-compose.yaml

services:
  bloqd:
    image: clusterzx/bloqd:latest
    env_file:
      - .env  # Contains API_KEY_SALT, DISCORD_WEBHOOK_URL, etc.
    environment:
      - NODE_ENV=production
      - LOG_LEVEL=info
    # ...

Environment Variable Precedence

When the same variable is defined in multiple places, this is the order of precedence (highest to lowest):

1. Direct environment: in docker-compose.yaml
2. .env file via env_file:
3. Shell environment variables
4. Default values in application

Troubleshooting

Variable Not Being Read

1. Check the variable name is correct (case-sensitive)
2. Ensure no trailing spaces in .env file
3. Restart the container after changes: docker compose restart

Secrets in Logs

By default, sensitive variables are not logged. If you need to debug:

# Check environment inside container
docker exec bloqd env | grep -E "(API_KEY|DISCORD)"

Special Characters

If your value contains special characters, wrap it in quotes:

# Wrong
API_KEY_SALT=abc$123

# Correct
API_KEY_SALT="abc$123"