Troubleshooting

# Find what's using the port (default: 3000)
sudo lsof -i :3000

# Change port in docker-compose.yml
ports:
  - "3001:3000"  # Use different external port

# Kill the process using the port
sudo kill -9 <PID>

# Create data directory
mkdir -p /path/to/homarr/data

# Set permissions
chmod 755 /path/to/homarr/data

# For Docker, may need specific user
chown -R 1000:1000 /path/to/homarr/data

# Verify internet connectivity
ping github.com

# Try pulling image manually
docker pull ghcr.io/homarr-labs/homarr:latest

# Check Docker registry authentication
docker login ghcr.io

docker compose ps db
docker compose up -d db

# In docker-compose, use service name as host
DB_URL='mysql://homarr:password@db:3306/homarrdb'
#                                  ^^^ service name, not 'localhost'

services:
  homarr:
    depends_on:
      db:
        condition: service_healthy

# docker-compose.yml
services:
  db:
    environment:
      MYSQL_USER: homarr
      MYSQL_PASSWORD: secure_password
      MYSQL_DATABASE: homarrdb
  
  homarr:
    environment:
      DB_URL: 'mysql://homarr:secure_password@db:3306/homarrdb'
      #                      ^^^^^^^^^^^^^^^
      #                      Must match MYSQL_PASSWORD

# Fix permissions
chmod 644 /path/to/db.sqlite
chown homarr:homarr /path/to/db.sqlite

# Docker Compose
docker compose exec homarr homarr-cli reset-password --username admin

# Docker
docker exec -it homarr homarr-cli reset-password --username admin

docker compose exec homarr homarr-cli recreate-admin --username newadmin

# Check AUTH_PROVIDERS includes your provider
echo $AUTH_PROVIDERS

docker compose logs homarr | grep -i "auth\|oidc\|ldap"

# From Homarr container
docker compose exec homarr curl -v https://your-oidc-provider.com

# Generate new secret
openssl rand -hex 32

# Add to .env
AUTH_SECRET="your-generated-secret"

# Check system time
date

# Sync time if needed
sudo ntpdate -s time.nist.gov

# Check if service is accessible
curl http://your-service:port

docker compose exec homarr curl -v http://your-service:port

docker compose logs homarr | grep -i "widget\|integration"

services:
  homarr:
    networks:
      - homarr-network
  
  plex:  # or other service
    networks:
      - homarr-network

networks:
  homarr-network:

# Set certificate path in .env
LOCAL_CERTIFICATE_PATH='/path/to/certificates'

# Mount certificates in docker-compose.yml
volumes:
  - /path/to/certs:/appdata/trusted-certificates:ro

-- MySQL
OPTIMIZE TABLE board, item, widget;

-- PostgreSQL
VACUUM ANALYZE;

docker stats homarr

# Monitor resource usage
docker stats homarr

# Check for resource limits
docker inspect homarr | grep -A 5 Memory

services:
  homarr:
    deploy:
      resources:
        limits:
          memory: 1G
          cpus: '1.0'

# List volumes
docker volume ls

# Inspect volume
docker volume inspect homarr-db-volume

# In .env file
SECRET_ENCRYPTION_KEY="<your-original-key>"

location / {
    proxy_pass http://homarr:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.homarr.rule=Host(`homarr.example.com`)"
  - "traefik.http.services.homarr.loadbalancer.server.port=3000"