Homepage Deployment & Usage Guide

1. Prerequisites

Required:

Docker (recommended) or Node.js 18+ with npm/yarn
A directory for configuration files
Basic understanding of YAML syntax

Optional but recommended:

Docker daemon running (for Docker integration)
Access to Docker socket (/var/run/docker.sock)
Reverse proxy (like Nginx, Caddy, or Traefik) for production deployment
API keys for service integrations (Plex, Sonarr, Radarr, weather services, etc.)

2. Installation

Docker (Recommended)

Create a docker-compose.yml file:

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    environment:
      HOMEPAGE_ALLOWED_HOSTS: localhost,homepage.local # Required - add your domain(s)
      PUID: 1000 # Optional - your user ID
      PGID: 1000 # Optional - your group ID
    ports:
      - 3000:3000
    volumes:
      - ./config:/app/config # Configuration directory
      - /var/run/docker.sock:/var/run/docker.sock:ro # For Docker integration
    restart: unless-stopped

Or using docker run:

docker run --name homepage \
  -e HOMEPAGE_ALLOWED_HOSTS=localhost \
  -p 3000:3000 \
  -v ./config:/app/config \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  --restart unless-stopped \
  ghcr.io/gethomepage/homepage:latest

From Source

# Clone the repository
git clone https://github.com/gethomepage/homepage.git
cd homepage

# Install dependencies
npm install

# Build the project
npm run build

# Start the development server
npm run dev

3. Configuration

Essential Environment Variables

HOMEPAGE_ALLOWED_HOSTS (Required): Comma-separated list of allowed hostnames/IPs
PUID/PGID: User/Group IDs for file permissions (optional)
TZ: Timezone (optional, e.g., America/New_York)

Configuration Files

Homepage uses YAML files in /app/config (or your mounted config directory):

Required structure:

config/
├── services.yaml     # Service widgets and groups
├── bookmarks.yaml    # Bookmark links
├── settings.yaml     # Global settings and themes
└── widgets.yaml      # Information widgets

Example services.yaml:

- Media:
  - Sonarr:
      icon: sonarr.png
      href: http://sonarr.local:8989
      description: TV Show Manager
      server: http://sonarr.local:8989
      apiKey: ${SONARR_API_KEY}
  - Plex:
      icon: plex.png
      href: http://plex.local:32400
      description: Media Server
      server: http://plex.local:32400
      token: ${PLEX_TOKEN}

Example bookmarks.yaml:

- Development:
  - GitHub:
      href: https://github.com
      icon: github.png
  - Docker Hub:
      href: https://hub.docker.com
      icon: docker.png

Environment variables in configs: Use ${VARIABLE_NAME} syntax in YAML files. Homepage will substitute these with actual environment variables.

Docker Auto-Discovery

Add labels to your Docker containers for automatic discovery:

labels:
  - "homepage.group=Media"
  - "homepage.name=Sonarr"
  - "homepage.icon=sonarr.png"
  - "homepage.href=http://sonarr:8989"
  - "homepage.description=TV Show Manager"

API Keys & Security

Store API keys as environment variables, not in config files
Use the built-in proxy feature to keep API keys secure
All API requests are proxied through Homepage, keeping keys hidden from clients

4. Build & Run

Development Mode

# From source
npm run dev
# Access at http://localhost:3000

Production Build (Source)

# Build static files
npm run build

# Start production server
npm start

Docker Build

# Build custom image
docker build -t homepage:custom .

# Run custom image
docker run -p 3000:3000 -v ./config:/app/config homepage:custom

5. Deployment

Recommended Platforms

1. Docker Host (Standalone)

Simple deployment on any Docker host
Use Docker Compose for easy management
Add to existing Docker stack

2. Reverse Proxy Setup

# Nginx example
server {
    listen 80;
    server_name homepage.yourdomain.com;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

3. Kubernetes

# Basic deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: homepage
spec:
  replicas: 1
  selector:
    matchLabels:
      app: homepage
  template:
    metadata:
      labels:
        app: homepage
    spec:
      containers:
      - name: homepage
        image: ghcr.io/gethomepage/homepage:latest
        env:
        - name: HOMEPAGE_ALLOWED_HOSTS
          value: "homepage.yourdomain.com"
        volumeMounts:
        - name: config
          mountPath: /app/config
        ports:
        - containerPort: 3000
      volumes:
      - name: config
        hostPath:
          path: /path/to/config

4. Cloud Platforms

DigitalOcean: Docker on Droplet or App Platform
AWS: ECS with Fargate or EC2
Azure: Container Instances or AKS
Google Cloud: Cloud Run or GKE

Security Considerations

Critical: Homepage has no built-in authentication. If exposed to untrusted networks:

Always use a reverse proxy with authentication
Enable TLS/HTTPS
Use VPN for internal access
Restrict access with firewall rules
The built-in host check is not a security feature

6. Troubleshooting

Common Issues

1. "Invalid Host Header" Error

# Solution: Set HOMEPAGE_ALLOWED_HOSTS correctly
HOMEPAGE_ALLOWED_HOSTS=localhost,192.168.1.100,homepage.local
# Include port if accessing with port: localhost:3000

2. Configuration Not Loading

Ensure config directory is mounted correctly
Check file permissions: chmod -R 755 ./config
Verify YAML syntax (use a YAML validator)
Check for environment variable substitution errors

3. Docker Integration Not Working

# Check Docker socket permissions
sudo chmod 666 /var/run/docker.sock
# Or add user to docker group: sudo usermod -aG docker $USER

4. Widgets Not Updating

Verify API keys are correct
Check service URLs are accessible from Homepage container
Enable debug logging in settings.yaml:

logging:
  level: debug

5. High Resource Usage

Homepage is static by default; dynamic widgets may increase load
Reduce update intervals in widget configurations
Consider disabling heavy widgets if not needed

Debug Commands

# Check container logs
docker logs homepage

# Enter container for debugging
docker exec -it homepage sh

# Test configuration syntax
npm run lint:config  # From source

# Verify environment variables
docker exec homepage env

Getting Help

Check documentation: https://gethomepage.dev
Review example configurations in repository
Join Discord community for support
Search existing GitHub issues
Enable debug logging and check browser console

How to Deploy & Use homepage