Docker Installation

Overview

Docker is the recommended way to run Homarr. The official Docker image includes all dependencies, handles database migrations automatically, and provides a consistent runtime environment across different platforms.

The official Homarr Docker image is available at ghcr.io/homarr-labs/homarr on GitHub Container Registry.

Image Architecture

The Homarr Docker image is based on Node.js 24.14.0 Alpine Linux and includes:

Next.js application running on port 3000
WebSocket server for real-time updates on port 3001
Background task processor for scheduled jobs
Nginx reverse proxy on port 7575 (the main entry point)
Embedded Redis server for caching and sessions
Database migration tooling for SQLite, MySQL, and PostgreSQL

Basic Installation

Pull the Image

docker pull ghcr.io/homarr-labs/homarr:latest

Run the Container

docker run -d \
  --name homarr \
  --restart unless-stopped \
  -p 7575:7575 \
  -v /path/to/homarr/data:/appdata \
  -e SECRET_ENCRYPTION_KEY=$(openssl rand -hex 32) \
  ghcr.io/homarr-labs/homarr:latest

Critical: Save your SECRET_ENCRYPTION_KEY in a secure location. You’ll need it to restore your container or migrate to a new server. Without it, encrypted integration credentials cannot be decrypted.

Environment Variables

Required Variables

Variable	Description	Example
`SECRET_ENCRYPTION_KEY`	64-character hex string for AES-256-CBC encryption of secrets	`0000...0000` (64 chars)

Generate a secure encryption key with: openssl rand -hex 32

Authentication & Authorization

Variable	Default	Description
`AUTH_SECRET`	Auto-generated	Secret for Auth.js (generated automatically on startup)
`AUTH_PROVIDERS`	`credentials`	Authentication providers: `credentials`, `oidc`, `ldap`
`AUTH_SESSION_EXPIRY_TIME`	-	Session expiration time in seconds
`AUTH_LOGOUT_REDIRECT_URL`	-	URL to redirect after logout

OIDC Authentication (Optional)

-e AUTH_PROVIDERS=oidc \
-e AUTH_OIDC_CLIENT_ID=your-client-id \
-e AUTH_OIDC_CLIENT_SECRET=your-client-secret \
-e AUTH_OIDC_ISSUER=https://your-oidc-provider.com \
-e AUTH_OIDC_CLIENT_NAME="My SSO" \
-e AUTH_OIDC_AUTO_LOGIN=false

LDAP Authentication (Optional)

-e AUTH_PROVIDERS=ldap \
-e AUTH_LDAP_URI=ldap://ldap.example.com:389 \
-e AUTH_LDAP_BASE="dc=example,dc=com" \
-e AUTH_LDAP_BIND_DN="cn=admin,dc=example,dc=com" \
-e AUTH_LDAP_BIND_PASSWORD=adminpassword \
-e AUTH_LDAP_USERNAME_ATTRIBUTE=uid \
-e AUTH_LDAP_USER_MAIL_ATTRIBUTE=mail

Database Configuration

SQLite (Default)

-e DB_DRIVER=better-sqlite3 \
-e DB_URL=/appdata/db/db.sqlite

MySQL

-e DB_DRIVER=mysql2 \
-e DB_URL=mysql://user:password@host:3306/database

PostgreSQL

-e DB_DRIVER=node-postgres \
-e DB_URL=postgres://user:password@host:5432/database

Logging & Monitoring

Variable	Default	Description
`LOG_LEVEL`	`info`	Logging level: `debug`, `info`, `warn`, `error`
`DISABLE_REDIS_LOGS`	`false`	Disable Redis logging output

File Permissions

Variable	Default	Description
`PUID`	`0`	User ID for running the application
`PGID`	`0`	Group ID for running the application

Set PUID and PGID to match your host user to avoid permission issues with mounted volumes. Find your IDs with id -u and id -g.

Advanced Configuration

Variable	Default	Description
`LOCAL_CERTIFICATE_PATH`	`/appdata/trusted-certificates`	Path for trusted SSL certificates
`DB_MIGRATIONS_DISABLED`	`false`	Disable automatic database migrations
`REDIS_IS_EXTERNAL`	`false`	Use external Redis instead of embedded instance
`REDIS_HOST`	-	External Redis hostname (if `REDIS_IS_EXTERNAL=true`)
`REDIS_PORT`	-	External Redis port (if `REDIS_IS_EXTERNAL=true`)
`ENABLE_KUBERNETES`	`false`	Enable Kubernetes integration features
`TURBO_TELEMETRY_DISABLED`	`1`	Disable Turborepo telemetry

Volume Mounts

Application Data Volume

The /appdata volume contains all persistent data:

/appdata/
├── db/                          # SQLite database (if using SQLite)
│   └── db.sqlite
├── redis/                       # Redis persistence (if configured)
├── trusted-certificates/        # Custom SSL certificates
└── logs/                        # Application logs

Recommended mount: -v /path/to/homarr/data:/appdata

Always backup the /appdata volume before upgrading or making major changes. This contains your entire Homarr configuration and data.

Network Configuration

Exposed Ports

Port	Service	Description
7575	Nginx Proxy	Main entry point for HTTP and WebSocket traffic

Ports 3000 (Next.js) and 3001 (WebSocket) are used internally and don’t need to be exposed.

Reverse Proxy Setup

If you’re using a reverse proxy (Nginx Proxy Manager, Traefik, Caddy), configure it to:

Forward HTTP traffic to port 7575
Enable WebSocket support for /websockets path

Set appropriate headers:

X-Forwarded-For $proxy_add_x_forwarded_for
X-Forwarded-Proto $scheme
X-Real-IP $remote_addr

Container Management

View Logs

# Follow logs in real-time
docker logs -f homarr

# View last 100 lines
docker logs --tail 100 homarr

# View logs since 1 hour ago
docker logs --since 1h homarr

Access Container Shell

docker exec -it homarr sh

Use Homarr CLI

The container includes the Homarr CLI tool:

# Reset user password
docker exec -it homarr homarr reset-password username

# View CLI help
docker exec -it homarr homarr --help

Restart Container

docker restart homarr

Stop Container

docker stop homarr

Remove Container

# Stop and remove (data volume is preserved)
docker stop homarr
docker rm homarr

Updating Homarr

Backup your data

tar -czf homarr-backup-$(date +%Y%m%d).tar.gz /path/to/homarr/data

Stop and remove the old container

docker stop homarr
docker rm homarr

Pull the latest image

docker pull ghcr.io/homarr-labs/homarr:latest

Start the new container

Use the same docker run command you used initially, with all the same environment variables and volume mounts.

Verify the update

docker logs -f homarr

Check for successful startup and database migration messages.

Database migrations run automatically on startup. The first start after an update may take slightly longer.

Troubleshooting

Database Migration Errors

If migrations fail, check:

# View detailed logs
docker logs homarr | grep -i migration

# Ensure database is accessible
docker exec -it homarr ping database-host

You can disable automatic migrations with:

-e DB_MIGRATIONS_DISABLED=true

Permission Issues

If you see permission errors:

Check file ownership:
```
ls -la /path/to/homarr/data
```

Set correct PUID/PGID:

id -u  # Get your user ID
id -g  # Get your group ID

Recreate container with correct IDs:

docker run -d ... -e PUID=1000 -e PGID=1000 ...

Container Won’t Start

Check for port conflicts:
```
netstat -tulpn | grep 7575
```
Verify volume mount exists:
```
ls -la /path/to/homarr/data
```
Check Docker daemon logs:
```
journalctl -u docker -n 50
```

High Memory Usage

If Homarr uses too much memory:

Consider using external Redis:

-e REDIS_IS_EXTERNAL=true \
-e REDIS_HOST=redis.example.com \
-e REDIS_PORT=6379

Limit Docker container memory:

docker run -d --memory="512m" --memory-swap="1g" ...

Best Practices

Always use volume mounts for /appdata - never store data in the container
Save your encryption key in a password manager or secure vault
Use external databases (MySQL/PostgreSQL) for production deployments
Enable automatic restarts with --restart unless-stopped
Monitor logs regularly for errors and performance issues
Keep containers updated by pulling latest images weekly
Backup before updates to avoid data loss
Use specific version tags in production instead of latest

Next Steps

Docker Compose

Simplify management with Docker Compose

Bare Metal Installation

Run Homarr directly on your system

Configuration Guide

Learn about advanced configuration options

Database Setup

Set up external MySQL or PostgreSQL

Get Started

Core Features

Configuration

Integrations

Guides

​Overview

​Image Architecture

​Basic Installation

​Pull the Image

​Run the Container

​Environment Variables

​Required Variables

​Authentication & Authorization

​OIDC Authentication (Optional)

​LDAP Authentication (Optional)

​Database Configuration

​SQLite (Default)

​MySQL

​PostgreSQL

​Logging & Monitoring

​File Permissions

​Advanced Configuration

​Volume Mounts

​Application Data Volume

​Network Configuration

​Exposed Ports

​Reverse Proxy Setup

​Container Management

​View Logs

​Access Container Shell

​Use Homarr CLI

​Restart Container

​Stop Container

​Remove Container

​Updating Homarr

​Troubleshooting

​Database Migration Errors

​Permission Issues

​Container Won’t Start

​High Memory Usage

​Best Practices

​Next Steps

Docker Compose

Bare Metal Installation

Configuration Guide

Database Setup

Build docs developers (and LLMs) love

Overview

Image Architecture

Basic Installation

Pull the Image

Run the Container

Environment Variables

Required Variables

Authentication & Authorization

OIDC Authentication (Optional)

LDAP Authentication (Optional)

Database Configuration

SQLite (Default)

MySQL

PostgreSQL

Logging & Monitoring

File Permissions

Advanced Configuration

Volume Mounts

Application Data Volume

Network Configuration

Exposed Ports

Reverse Proxy Setup

Container Management

View Logs

Access Container Shell

Use Homarr CLI

Restart Container

Stop Container

Remove Container

Updating Homarr

Troubleshooting

Database Migration Errors

Permission Issues

Container Won’t Start

High Memory Usage

Best Practices

Next Steps