This guide uses Docker Compose to run HomeBox.
For Docker installation, see Docker.
For a quick test installation:
# Create data directory with proper permissions
mkdir -p /path/to/data/folder
chown 65532:65532 -R /path/to/data/folder # For rootless/hardened images
# Run the container
docker run -d \
--name homebox \
--restart unless-stopped \
--publish 3100:7745 \
--env TZ=America/New_York \
--volume /path/to/data/folder:/data \
ghcr.io/sysadminsmedia/homebox:latest
Create a docker-compose.yml file:
version: '3.8'
services:
homebox:
image: ghcr.io/sysadminsmedia/homebox:latest
container_name: homebox
restart: unless-stopped
ports:
- "3100:7745" # Map host port 3100 to container port 7745
environment:
- TZ=America/New_York # Set your timezone
- HBOX_MODE=production
- HBOX_DB_TYPE=sqlite # or postgres for PostgreSQL
- HBOX_DB_SQLITE_FILE=/data/data.db
- HBOX_OPTIONS_ALLOW_REGISTRATION=true # Set to false after initial setup
volumes:
- ./data:/data # Persistent data storage
networks:
- homebox-net
networks:
homebox-net:
driver: bridge
Then start the service:
docker compose up -d
HomeBox provides multiple Docker image variants for different security and deployment requirements:
ghcr.io/sysadminsmedia/homebox:latest
ghcr.io/sysadminsmedia/homebox:latest-rootless
ghcr.io/sysadminsmedia/homebox:latest-hardened
ghcr.io/sysadminsmedia/homebox:nightly
ghcr.io/sysadminsmedia/homebox:nightly-rootless
ghcr.io/sysadminsmedia/homebox:nightly-hardened
ghcr.io/sysadminsmedia/homebox:v0.23.1
ghcr.io/sysadminsmedia/homebox:v0.23.1-rootless
ghcr.io/sysadminsmedia/homebox:v0.23.1-hardened
environment:
- TZ=America/New_York # Set timezone
- HBOX_MODE=production # Set to production mode
- HBOX_OPTIONS_ALLOW_REGISTRATION=true # Enable registration initially
environment:
# SQLite (default)
- HBOX_DB_TYPE=sqlite
- HBOX_DB_SQLITE_FILE=/data/data.db
# PostgreSQL (alternative)
- HBOX_DB_TYPE=postgres
- HBOX_DB_HOST=db
- HBOX_DB_PORT=5432
- HBOX_DB_NAME=homebox
- HBOX_DB_USER=homebox
- HBOX_DB_PASSWORD=password
environment:
- HBOX_OPTIONS_ALLOW_REGISTRATION=false # Disable public registration after setup
- HBOX_LOG_LEVEL=info # Set log level
- HBOX_SERVER_PUBLIC_URL=https://inventory.example.com # Public URL
For production deployments, consider this more secure configuration with additional features:
version: '3.8'
services:
homebox:
image: ghcr.io/sysadminsmedia/homebox:latest-rootless # Use rootless image
container_name: homebox
restart: unless-stopped
security_opt:
- no-new-privileges:true
read_only: true # Run with read-only root filesystem
tmpfs:
- /tmp
- /run
ports:
- "3100:7745"
environment:
- TZ=America/New_York
- HBOX_MODE=production
- HBOX_SERVER_PUBLIC_URL=https://inventory.example.com
- HBOX_SERVER_METRICS_ENABLED=true # Enable Prometheus metrics
- HBOX_SERVER_METRICS_USERNAME=metrics
- HBOX_SERVER_METRICS_PASSWORD=secure-password-for-metrics
- HBOX_DB_TYPE=sqlite
- HBOX_DB_SQLITE_FILE=/data/data.db
- HBOX_OPTIONS_ALLOW_REGISTRATION=false # Disable after initial setup
- HBOX_OPTIONS_DEFAULT_ROLE=user
- HBOX_OPTIONS_INVITE_ONLY=true # Require invite links for new users
- HBOX_WEB_MAX_UPLOAD_SIZE=25 # Increase max upload size if needed
- HBOX_LOG_LEVEL=info
- HBOX_LOG_FORMAT=json # JSON logs for easier parsing
- HBOX_SESSION_SECRET=very-long-random-string-here # Required for production
- HBOX_SESSION_SECURE_COOKIE=true # Required when using HTTPS reverse proxy
- HBOX_SESSION_TIMEOUT=24 # Session timeout in hours
- HBOX_RATE_LIMIT_GENERAL=100 # General request rate limit
- HBOX_RATE_LIMIT_AUTHENTICATION=5 # Auth rate limit
# OIDC Configuration (uncomment and configure as needed):
# - HBOX_OIDC_ENABLED=true
# - HBOX_OIDC_ISSUER=https://your-idp.example.com
# - HBOX_OIDC_CLIENT_ID=your-client-id
# - HBOX_OIDC_CLIENT_SECRET=your-client-secret
# - HBOX_OIDC_SCOPES=openid,profile,email
# - HBOX_OIDC_GROUPS_CLAIM=groups
# - HBOX_OIDC_USERNAME_CLAIM=email
# - HBOX_OIDC_AUTO_CREATE=true
# - HBOX_OIDC_AUTO_ASSIGN_ROLES=false
# MQTT Configuration (if needed for IoT integration):
# - HBOX_MQTT_ENABLED=true
# - HBOX_MQTT_BROKER=tcp://mqtt.example.com:1883
# - HBOX_MQTT_CLIENT_ID=homebox
# - HBOX_MQTT_TOPIC_PREFIX=homebox
volumes:
- ./data:/data:rw # Only data directory is writable
- /etc/localtime:/etc/localtime:ro # Read-only system time
networks:
- homebox-net
cap_drop:
- ALL # Drop all capabilities for additional security
networks:
homebox-net:
driver: bridge
For larger deployments, you can use PostgreSQL instead of SQLite:
version: '3.8'
services:
db:
image: postgres:15-alpine
container_name: homebox-postgres
restart: unless-stopped
environment:
- POSTGRES_DB=homebox
- POSTGRES_USER=homebox
- POSTGRES_PASSWORD=secure-password-here
volumes:
- ./postgres_data:/var/lib/postgresql/data
networks:
- homebox-net
homebox:
image: ghcr.io/sysadminsmedia/homebox:latest-rootless
container_name: homebox-app
restart: unless-stopped
depends_on:
- db
security_opt:
- no-new-privileges:true
read_only: true
tmpfs:
- /tmp
- /run
ports:
- "3100:7745"
environment:
- TZ=America/New_York
- HBOX_MODE=production
- HBOX_SERVER_PUBLIC_URL=https://inventory.example.com
- HBOX_DB_TYPE=postgres
- HBOX_DB_HOST=db
- HBOX_DB_PORT=5432
- HBOX_DB_NAME=homebox
- HBOX_DB_USER=homebox
- HBOX_DB_PASSWORD=secure-password-here
- HBOX_OPTIONS_ALLOW_REGISTRATION=false
- HBOX_SESSION_SECRET=very-long-random-string-here
- HBOX_SESSION_SECURE_COOKIE=true
volumes:
- /etc/localtime:/etc/localtime:ro
networks:
- homebox-net
cap_drop:
- ALL
networks:
homebox-net:
driver: bridge
To use S3-compatible storage for attachments:
version: '3.8'
services:
homebox:
image: ghcr.io/sysadminsmedia/homebox:latest-rootless
container_name: homebox
restart: unless-stopped
security_opt:
- no-new-privileges:true
read_only: true
tmpfs:
- /tmp
- /run
ports:
- "3100:7745"
environment:
- TZ=America/New_York
- HBOX_MODE=production
- HBOX_SERVER_PUBLIC_URL=https://inventory.example.com
- HBOX_DB_TYPE=sqlite
- HBOX_DB_SQLITE_FILE=/data/data.db
- HBOX_OPTIONS_ALLOW_REGISTRATION=false
- HBOX_SESSION_SECRET=very-long-random-string-here
- HBOX_SESSION_SECURE_COOKIE=true
# S3 Storage Configuration
- HBOX_STORAGE_TYPE=s3
- HBOX_STORAGE_S3_ENDPOINT=https://s3.example.com
- HBOX_STORAGE_S3_BUCKET=homebox-storage
- HBOX_STORAGE_S3_REGION=us-east-1
- HBOX_STORAGE_S3_FORCE_PATH_STYLE=true # For S3-compatible services
# S3 Credentials (preferably set via external means like Docker secrets)
- AWS_ACCESS_KEY_ID=your-access-key
- AWS_SECRET_ACCESS_KEY=your-secret-key
volumes:
- /etc/localtime:/etc/localtime:ro
networks:
- homebox-net
cap_drop:
- ALL
http://your-server-ip:3100HBOX_OPTIONS_ALLOW_REGISTRATION=falsechown 65532:65532 -R /path/to/data/folderAny questions?
Feel free to contact us. Find all contact information on our contact page.