Skip to main content

Configuration

Complete reference for configuring your Hive-Pal installation.

Environment Variables​

Backend Configuration​

Database​

DATABASE_URL="postgresql://user:password@host:port/database"

Security​

JWT_SECRET=your_secure_jwt_secret_here
JWT_EXPIRES_IN=7d
ALLOWED_ORIGINS=http://localhost:5173,https://yourdomain.com

Optional Services​

# Email (SMTP)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password

# Error Tracking
SENTRY_DSN=your_sentry_dsn_here

# File Storage (see "File Storage" section below for details)
STORAGE_TYPE=local  # or 's3' (default)

Frontend Configuration​

API Connection​

VITE_API_URL=http://localhost:3000
VITE_API_TIMEOUT=30000

Optional Features​

VITE_SENTRY_DSN=your_sentry_dsn_here
VITE_GOOGLE_MAPS_API_KEY=your_maps_api_key
VITE_WEATHER_API_KEY=your_weather_api_key

Database Configuration​

Connection Pool​

DB_POOL_MIN=2
DB_POOL_MAX=10
DB_POOL_IDLE_TIMEOUT=10000
DB_POOL_ACQUIRE_TIMEOUT=60000

Performance Tuning​

-- postgresql.conf optimizations
shared_buffers = 256MB
effective_cache_size = 1GB
work_mem = 4MB
maintenance_work_mem = 64MB
checkpoint_completion_target = 0.9
random_page_cost = 1.1

Security Settings​

HTTPS Configuration​

# Force HTTPS
FORCE_HTTPS=true
HSTS_MAX_AGE=31536000

# CORS Settings
CORS_CREDENTIALS=true
CORS_MAX_AGE=86400

Rate Limiting​

RATE_LIMIT_WINDOW=900000  # 15 minutes
RATE_LIMIT_MAX=100        # requests per window

File Storage​

Hive-Pal supports two storage backends for file uploads (audio recordings, photos): local filesystem and S3-compatible object storage. Set STORAGE_TYPE to choose which one to use.

Local Storage​

The simplest option for self-hosted deployments — files are stored directly on disk (or a Docker volume). No external services required.

STORAGE_TYPE=local
STORAGE_LOCAL_PATH=./data/uploads  # default: ./data/uploads

In Docker, STORAGE_LOCAL_PATH defaults to /data/uploads, which is backed by the hivepal_uploads volume for persistence across container restarts.

Download URLs are generated as signed, time-limited paths (using HMAC-SHA256 with JWT_SECRET), so they work the same way as S3 pre-signed URLs — no frontend changes needed.

S3-Compatible Storage​

Use this for AWS S3, MinIO, or any S3-compatible service. This is the default when STORAGE_TYPE is unset.

STORAGE_TYPE=s3  # default
S3_ENDPOINT=http://localhost:9000   # MinIO or S3-compatible endpoint
S3_REGION=us-east-1
S3_BUCKET=hivepal-audio
S3_ACCESS_KEY_ID=your_key
S3_SECRET_ACCESS_KEY=your_secret

For local development with MinIO:

docker compose up -d minio
# Access MinIO console at http://localhost:9001 to create a bucket

Logging​

Log Levels​

LOG_LEVEL=info  # error, warn, info, debug
LOG_FORMAT=json # json, simple
LOG_FILE=/var/log/hive-pal/app.log

External Logging​

# Loki
LOKI_URL=http://localhost:3100
LOKI_USERNAME=admin
LOKI_PASSWORD=admin

Monitoring​

Health Checks​

HEALTH_CHECK_ENABLED=true
HEALTH_CHECK_PATH=/health

Metrics​

PROMETHEUS_ENABLED=true
PROMETHEUS_PORT=9090
METRICS_PATH=/metrics

Email Configuration​

SMTP Settings​

MAIL_FROM=noreply@your-domain.com
MAIL_FROM_NAME="Hive-Pal"
MAIL_REPLY_TO=support@your-domain.com

Email Templates​

  • Welcome email
  • Password reset
  • Inspection reminders
  • System notifications

API Configuration​

Rate Limiting​

API_RATE_LIMIT=1000  # requests per hour
API_BURST_LIMIT=50   # burst requests

Timeouts​

API_TIMEOUT=30000     # 30 seconds
DB_TIMEOUT=10000      # 10 seconds
UPLOAD_TIMEOUT=300000 # 5 minutes

Cache Configuration​

Redis (Optional)​

REDIS_URL=redis://localhost:6379
REDIS_TTL=3600        # 1 hour
REDIS_KEY_PREFIX=hive-pal:

Memory Cache​

CACHE_MAX_SIZE=100    # MB
CACHE_TTL=1800        # 30 minutes

Backup Configuration​

Database Backups​

BACKUP_ENABLED=true
BACKUP_SCHEDULE="0 2 * * *"  # Daily at 2 AM
BACKUP_RETENTION=30          # Days
BACKUP_PATH=/backups

File Backups​

FILE_BACKUP_ENABLED=true
FILE_BACKUP_SCHEDULE="0 3 * * *"
FILE_BACKUP_COMPRESSION=true

Development Settings​

Debug Mode​

NODE_ENV=development
DEBUG=true
VERBOSE_LOGGING=true

Hot Reload​

WATCH_MODE=true
RELOAD_ON_CHANGE=true

Production Optimizations​

Performance​

NODE_ENV=production
COMPRESSION_ENABLED=true
GZIP_LEVEL=6
STATIC_CACHE_TTL=31536000  # 1 year

Security​

HELMET_ENABLED=true
CSP_ENABLED=true
SECURE_COOKIES=true

Configuration Validation​

Required Variables​

  • DATABASE_URL
  • JWT_SECRET
  • ALLOWED_ORIGINS

Optional Variables​

  • All other settings have defaults
  • Override as needed
  • Environment-specific files supported

Best Practices​

  • Use environment-specific .env files
  • Never commit secrets to version control
  • Use Docker secrets in production
  • Validate configuration on startup
  • Monitor configuration changes