This guide walks through a self-hosted installation of HomeBox.
For Docker installation, see Docker.
Create a docker-compose.yml file:
version: '3.8'
services:
homebox:
image: ghcr.io/sysadminsmedia/homebox:latest # Use :latest-rootless for enhanced security
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
- HBOX_OPTIONS_DEFAULT_ROLE=user
- HBOX_WEB_MAX_UPLOAD_SIZE=10 # Max upload size in MB
- HBOX_LOG_LEVEL=info
# Uncomment for OIDC SSO:
# - HBOX_OIDC_ENABLED=true
# - HBOX_OIDC_ISSUER=https://your-auth-provider.com
# - HBOX_OIDC_CLIENT_ID=your-client-id
# - HBOX_OIDC_CLIENT_SECRET=your-client-secret
volumes:
- ./data:/data # Persistent data storage
networks:
- homebox-net
networks:
homebox-net:
driver: bridge
For enhanced security in production environments, use the rootless image:
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 # 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 # Set your public URL
- HBOX_DB_TYPE=sqlite
- HBOX_DB_SQLITE_FILE=/data/data.db
- HBOX_OPTIONS_ALLOW_REGISTRATION=false # Disable after initial setup
- HBOX_LOG_LEVEL=info
- HBOX_SESSION_SECRET=your-super-secret-session-key-here # Required for production
- HBOX_SESSION_SECURE_COOKIE=true # Required when using HTTPS reverse proxy
- HBOX_RATE_LIMIT_GENERAL=100
- HBOX_RATE_LIMIT_AUTHENTICATION=5
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
Then start the service:
docker compose up -d
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
For enhanced security, use the rootless or hardened image:
# Create data directory with proper permissions
mkdir -p /path/to/data/folder
chown 65532:65532 -R /path/to/data/folder
# Run with rootless image
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-rootless
http://your-server-ip:3100HBOX_OPTIONS_ALLOW_REGISTRATION=falsePrefer automation? See HomeBox Ansible Setup for an example playbook.
Prefer containers? See HomeBox Docker Setup.
Any questions?
Feel free to contact us. Find all contact information on our contact page.