HomeBox should be configured for home inventory data integrity and permission-safe household sharing.
# Application Mode
HBOX_MODE=production # Set to 'production', 'development', or 'test'
# Server Configuration
HBOX_SERVER_PORT=7745 # Default port (when running directly)
HBOX_SERVER_PUBLIC_URL=https://inventory.example.com # Public URL for the application
HBOX_SERVER_BASE_PATH=/ # Base path if running behind a reverse proxy
HBOX_SERVER_REQUEST_TIMEOUT=30 # Request timeout in seconds
HBOX_SERVER_SHUTDOWN_TIMEOUT=30 # Shutdown timeout in seconds
HBOX_SERVER_METRICS_ENABLED=false # Enable Prometheus metrics endpoint (/metrics)
HBOX_SERVER_METRICS_USERNAME=metrics # Username for metrics endpoint (if enabled)
HBOX_SERVER_METRICS_PASSWORD=password # Password for metrics endpoint (if enabled)
# Timezone
TZ=America/New_York # Timezone for the application
# Database Type (sqlite or postgres)
HBOX_DB_TYPE=sqlite # Use 'sqlite' for simple setup or 'postgres' for production
# SQLite Configuration (default)
HBOX_DB_SQLITE_FILE=data.db # Path to SQLite database file (relative to data directory)
# PostgreSQL Configuration (alternative)
HBOX_DB_HOST=localhost # PostgreSQL host
HBOX_DB_PORT=5432 # PostgreSQL port
HBOX_DB_NAME=homebox # Database name
HBOX_DB_USER=homebox # Database user
HBOX_DB_PASSWORD=password # Database password
HBOX_DB_SSL_MODE=disable # SSL mode (disable, require, verify-ca, verify-full)
HBOX_DB_TIMEZONE=UTC # Database timezone
# Registration Settings
HBOX_OPTIONS_ALLOW_REGISTRATION=true # Allow user registration (set to false after setup)
HBOX_OPTIONS_DEFAULT_ROLE=user # Default role for new users ('user' or 'admin')
HBOX_OPTIONS_INVITE_ONLY=false # Require invite links for new user registration
# File Upload Settings
HBOX_WEB_MAX_UPLOAD_SIZE=10 # Maximum file upload size in MB
HBOX_WEB_ALLOWED_FILE_TYPES=image/* # Allowed file types for uploads
# Logging
HBOX_LOG_LEVEL=info # Log level (debug, info, warn, error)
HBOX_LOG_FORMAT=text # Log format (text or json)
# Feature Flags
HBOX_FEATURE_QR_CODES=true # Enable QR code generation
HBOX_FEATURE_API=true # Enable REST API access
HBOX_FEATURE_BULK_IMPORT=true # Enable bulk import functionality
HBOX_FEATURE_BULK_EXPORT=true # Enable bulk export functionality
HBOX_FEATURE_TEMPLATES=true # Enable item templates
HBOX_FEATURE_COLLECTIONS=true # Enable collections feature (requires v0.23.0+)
# Currency Settings
HBOX_CURRENCY=USD # Default currency for pricing fields
HBOX_CUSTOM_CURRENCIES=EUR,GBP # Additional custom currencies to enable
# Rate Limiting
HBOX_RATE_LIMIT_GENERAL=100 # General request rate limit (requests per minute)
HBOX_RATE_LIMIT_AUTHENTICATION=5 # Authentication request rate limit (attempts per minute)
# Local Authentication
HBOX_AUTH_LOCAL_ENABLED=true # Enable local authentication
# OIDC Configuration (Single Sign-On)
HBOX_OIDC_ENABLED=false # Enable OIDC authentication
HBOX_OIDC_ISSUER=https://auth.example.com # OIDC issuer URL
HBOX_OIDC_CLIENT_ID=client-id # OIDC client ID
HBOX_OIDC_CLIENT_SECRET=client-secret # OIDC client secret (store securely)
HBOX_OIDC_SCOPES=openid,profile,email # OIDC scopes
HBOX_OIDC_GROUPS_CLAIM=groups # Claim for groups/roles
HBOX_OIDC_USERNAME_CLAIM=email # Claim for username
HBOX_OIDC_FIRST_NAME_CLAIM=given_name # Claim for first name
HBOX_OIDC_LAST_NAME_CLAIM=family_name # Claim for last name
HBOX_OIDC_AUTO_CREATE=true # Automatically create users on successful OIDC login
HBOX_OIDC_AUTO_ASSIGN_ROLES=false # Automatically assign roles based on OIDC groups claim
# Session Configuration
HBOX_SESSION_SECRET=random-string # Secret for session encryption (required for production)
HBOX_SESSION_COOKIE_NAME=homebox_session # Name of the session cookie
HBOX_SESSION_SECURE_COOKIE=true # Set secure flag on cookies (requires HTTPS)
HBOX_SESSION_COOKIE_DOMAIN=.example.com # Domain for session cookies (optional)
HBOX_SESSION_TIMEOUT=24 # Session timeout in hours
# Local Storage
HBOX_STORAGE_TYPE=local # Storage type ('local' or 's3')
HBOX_STORAGE_LOCAL_PATH=./data/media # Path for local file storage
# S3-Compatible Storage (for external storage)
HBOX_STORAGE_S3_ENDPOINT=https://s3.amazonaws.com # S3 endpoint
HBOX_STORAGE_S3_BUCKET=bucket-name # S3 bucket name
HBOX_STORAGE_S3_REGION=us-east-1 # S3 region
HBOX_STORAGE_S3_FORCE_PATH_STYLE=false # Force path-style URLs for S3-compatible services
AWS_ACCESS_KEY_ID=access-key # S3 access key
AWS_SECRET_ACCESS_KEY=secret-key # S3 secret key
# MQTT Configuration (Available in regular and rootless images)
HBOX_MQTT_ENABLED=false # Enable MQTT client for IoT integrations
HBOX_MQTT_BROKER=tcp://localhost:1883 # MQTT broker URL
HBOX_MQTT_USERNAME=username # MQTT username (if required)
HBOX_MQTT_PASSWORD=password # MQTT password (if required)
HBOX_MQTT_CLIENT_ID=homebox # MQTT client identifier
HBOX_MQTT_TOPIC_PREFIX=homebox # Prefix for MQTT topics
# Mailer Settings
HBOX_MAILER_ENABLED=false # Enable email notifications
HBOX_MAILER_FROM=noreply@example.com # From address for emails
HBOX_MAILER_SMTP_HOST=smtp.example.com # SMTP server
HBOX_MAILER_SMTP_PORT=587 # SMTP port
HBOX_MAILER_SMTP_USERNAME=username # SMTP username
HBOX_MAILER_SMTP_PASSWORD=password # SMTP password
HBOX_MAILER_SMTP_TLS=true # Use TLS for SMTP
HBOX_MAILER_SMTP_SKIP_VERIFY=false # Skip TLS certificate verification (not recommended for production)
Back up database, uploaded files/assets, and configuration/secrets metadata. Validate restore with one user login, one core business transaction, and one report/export check.
For SQLite databases, simply back up the database file. For PostgreSQL, use pg_dump.
Any questions?
Feel free to contact us. Find all contact information on our contact page.