homelab/docs/troubleshooting/faq.md

Frequently Asked Questions (FAQ)

Common questions and answers about the homelab setup.

General Questions

Q: What is this homelab setup?

A: This is a GitOps-based infrastructure for self-hosting services using Docker Compose. It includes:

• 20+ pre-configured services (media, productivity, utilities)
• Automatic SSL/TLS with Let's Encrypt via Traefik
• Single Sign-On (SSO) with LLDAP and Tinyauth
• Automated backups with Backrest
• Service discovery dashboard with Homarr

Q: What are the minimum hardware requirements?

A:

• CPU: 2+ cores (4+ recommended)
• RAM: 8GB minimum (16GB+ recommended)
• Storage: 100GB for containers, additional space for media
• Network: Static IP recommended, ports 80 and 443 accessible
• GPU (Optional): NVIDIA GPU for hardware transcoding

Q: Do I need my own domain name?

A: Yes, you need at least one domain (two configured by default: fig.systems and edfig.dev). You can:

• Register a domain from any registrar
• Update all compose files to use your domain
• Configure wildcard DNS (*.yourdomain.com)

Q: Can I run this on a Raspberry Pi?

A: Partially. ARM64 architecture is supported by most services, but:

• Performance will be limited
• No GPU acceleration available
• Some services may not have ARM images
• 8GB RAM minimum recommended (Pi 4 or Pi 5)

Q: How much does this cost to run?

A:

• Server: $0 (if using existing hardware) or $5-20/month (VPS)
• Domain: $10-15/year
• Backblaze B2: ~$0.60/month for 100GB photos
• Electricity: Varies by hardware and location
• Total: $15-30/year minimum

Setup Questions

Q: Why won't my services start?

A: Common causes:

1. Environment variables not set: Check for changeme_* in .env files
2. Ports already in use: Check if 80/443 are available
3. Network not created: Run docker network create homelab
4. DNS not configured: Services need valid DNS records
5. Insufficient resources: Check RAM and disk space

Debug:

cd compose/path/to/service
docker compose logs
docker compose ps

Q: How do I know if everything is working?

A: Check these indicators:

1. All containers running: docker ps shows all services
2. SSL certificates valid: Visit https://home.fig.systems (no cert errors)
3. Dashboard accessible: Homarr shows all services
4. SSO working: Can login to protected services
5. No errors in logs: docker compose logs shows no critical errors

Q: What order should I deploy services?

A: Follow this order:

1. Core: Traefik → LLDAP → Tinyauth
2. Configure: Create LLDAP users
3. Media: Jellyfin → Immich → Jellyseerr → Sonarr → Radarr → Downloaders
4. Utility: Homarr → Backrest → Everything else

Q: Do I need to configure all 20 services?

A: No! Deploy only what you need:

• Core (required): Traefik, LLDAP, Tinyauth
• Media (optional): Jellyfin, Immich, Sonarr, Radarr
• Utility (pick what you want): Homarr, Backrest, Linkwarden, Vikunja, etc.

Configuration Questions

Q: What secrets do I need to change?

A: Search for changeme_* in all .env files:

grep -r "changeme_" compose/

Critical secrets:

• LLDAP_LDAP_USER_PASS: Admin password for LLDAP
• LLDAP_JWT_SECRET: 64-character hex string
• SESSION_SECRET: 64-character hex string for Tinyauth
• DB_PASSWORD: Database passwords (Immich, Vikunja, Linkwarden)
• NEXTAUTH_SECRET: NextAuth secret for Linkwarden
• VIKUNJA_SERVICE_JWTSECRET: JWT secret for Vikunja

Q: How do I generate secure secrets?

A: Use these commands:

# 64-character hex (for JWT secrets, session secrets)
openssl rand -hex 32

# 32-character password (for databases)
openssl rand -base64 32 | tr -d /=+ | cut -c1-32

# 32-character hex (for API keys)
openssl rand -hex 16

See Secrets Management Guide for details.

Q: Can I change the domains from fig.systems to my own?

A: Yes! You need to:

1. Find and replace in all compose.yaml files:

   find compose -name "compose.yaml" -exec sed -i 's/fig\.systems/yourdomain.com/g' {} \;
   find compose -name "compose.yaml" -exec sed -i 's/edfig\.dev/yourotherdomain.com/g' {} \;
   

2. Update DNS records to point to your server
3. Update .env files with new URLs (e.g., NEXTAUTH_URL, VIKUNJA_SERVICE_PUBLICURL)

Q: Do all passwords need to match?

A: No, but some must match:

• LLDAP_LDAP_USER_PASS must equal LDAP_BIND_PASSWORD (in tinyauth)
• VIKUNJA_DATABASE_PASSWORD must equal POSTGRES_PASSWORD (in vikunja)
• Linkwarden POSTGRES_PASSWORD is used in DATABASE_URL

All other passwords should be unique!

SSL/TLS Questions

Q: Why am I getting SSL certificate errors?

A: Common causes:

1. DNS not configured: Ensure domains point to your server
2. Ports not accessible: Let's Encrypt needs port 80 for HTTP challenge
3. Rate limiting: Let's Encrypt has rate limits (5 certs per domain/week)
4. First startup: Certs take a few minutes to generate

Debug:

docker logs traefik | grep -i error
docker logs traefik | grep -i certificate

Q: How long do SSL certificates last?

A: Let's Encrypt certificates:

• Valid for 90 days
• Traefik auto-renews at 30 days before expiration
• Renewals happen automatically in the background

Q: Can I use my own SSL certificates?

A: Yes, but it requires modifying Traefik configuration. The default Let's Encrypt setup is recommended.

SSO Questions

Q: What is SSO and do I need it?

A: SSO (Single Sign-On) lets you log in once and access all services:

• LLDAP: Stores users and passwords
• Tinyauth: Authenticates users before allowing service access
• Benefits: One login for all services, centralized user management
• Optional: Some services can work without SSO (have their own auth)

Q: Why can't I log into SSO-protected services?

A: Check:

1. LLDAP is running: docker ps | grep lldap
2. Tinyauth is running: docker ps | grep tinyauth
3. User exists in LLDAP: Go to https://lldap.fig.systems and verify
4. Passwords match: LDAP_BIND_PASSWORD = LLDAP_LDAP_USER_PASS
5. User in correct group: Check user is in lldap_admin group

Debug:

cd compose/core/tinyauth
docker compose logs -f

Q: Can I disable SSO for a service?

A: Yes! Comment out the middleware line in compose.yaml:

# traefik.http.routers.servicename.middlewares: tinyauth

Then restart the service:

docker compose up -d

Q: How do I reset my LLDAP admin password?

A:

1. Stop LLDAP: cd compose/core/lldap && docker compose down
2. Update LLDAP_LDAP_USER_PASS in .env
3. Remove the database: rm -rf data/
4. Restart: docker compose up -d
5. Recreate users in LLDAP UI

⚠️ Warning: This deletes all users!

Service-Specific Questions

Q: Jellyfin shows "Playback Error" - what's wrong?

A: Common causes:

1. Media file corrupt: Test file with VLC
2. Permissions: Check file ownership (ls -la /media/movies)
3. Codec not supported: Enable transcoding or use different file
4. GPU not configured: If using GPU, verify NVIDIA Container Toolkit

Q: Immich won't upload photos - why?

A: Check:

1. Database connected: docker logs immich_postgres
2. Upload directory writable: Check permissions on ./upload
3. Disk space: df -h
4. File size limits: Check browser console for errors

Q: Why isn't Homarr showing my services?

A: Homarr needs:

1. Docker socket access: Volume mount /var/run/docker.sock
2. Labels on services: Each service needs homarr.name label
3. Same network: Homarr must be on homelab network
4. Time to detect: Refresh page or wait 30 seconds

Q: Backrest shows "Repository not initialized" - what do I do?

A:

1. Go to https://backup.fig.systems
2. Click "Add Repository"
3. Configure Backblaze B2 settings
4. Click "Initialize Repository"

See Backup Guide for detailed setup.

Q: Sonarr/Radarr can't find anything - help!

A:

1. Add indexers: Settings → Indexers → Add indexer
2. Configure download client: Settings → Download Clients → Add
3. Set root folder: Series/Movies → Add Root Folder → /media/tv or /media/movies
4. Test indexers: Settings → Indexers → Test

Q: qBittorrent shows "Unauthorized" - what's the password?

A: Default credentials:

• Username: admin
• Password: adminadmin

⚠️ Change this immediately in qBittorrent settings!

Media Questions

Q: Where should I put my media files?

A: Use the /media directory structure:

• Movies: /media/movies/Movie Name (Year)/movie.mkv
• TV: /media/tv/Show Name/Season 01/episode.mkv
• Music: /media/music/Artist/Album/song.flac
• Photos: /media/photos/ (any structure)
• Books: /media/books/ (any structure)

Q: How do I add more media storage?

A:

1. Mount additional drive to /media2 (or any path)
2. Update compose files to include new volume:

   volumes:
     - /media:/media:ro
     - /media2:/media2:ro  # Add this
   

3. Restart service: docker compose up -d
4. Add new library in service UI

Q: Can Sonarr/Radarr automatically download shows/movies?

A: Yes! That's their purpose:

1. Add indexers (for searching)
2. Add download client (SABnzbd or qBittorrent)
3. Add a series/movie
4. Enable monitoring
5. Sonarr/Radarr will search, download, and organize automatically

Q: How do I enable hardware transcoding in Jellyfin?

A: See GPU Setup Guide for full instructions.

Quick steps:

1. Install NVIDIA Container Toolkit on host
2. Uncomment GPU sections in jellyfin/compose.yaml
3. Restart Jellyfin
4. Enable in Jellyfin: Dashboard → Playback → Hardware Acceleration → NVIDIA NVENC

Network Questions

Q: Can I access services only from my local network?

A: Yes, don't expose ports 80/443 to internet:

1. Use firewall to block external access
2. Use local DNS (Pi-hole, AdGuard Home)
3. Point domains to local IP (192.168.x.x)
4. Use self-signed certs or no HTTPS

Or use Traefik's IP allowlist middleware.

Q: Can I use a VPN with these services?

A: Yes, options:

1. VPN on download clients: Add VPN container for qBittorrent/SABnzbd
2. VPN to access homelab: Use WireGuard/Tailscale to access from anywhere
3. VPN for entire server: All traffic goes through VPN (not recommended)

Q: Why can't I access services from outside my network?

A: Check:

1. Port forwarding: Ports 80 and 443 forwarded to homelab server
2. Firewall: Allow ports 80/443 through firewall
3. DNS: Domains point to your public IP
4. ISP: Some ISPs block ports 80/443 (use CloudFlare Tunnel)

Backup Questions

Q: What should I backup?

A: Priority order:

1. High: Immich photos (compose/media/frontend/immich/upload)
2. High: Configuration files (all .env files, compose files)
3. Medium: Service data directories (./config, ./data in each service)
4. Low: Media files (usually have source elsewhere)

Q: How do I restore from backup?

A: See Backup Operations Guide.

Quick steps:

1. Install fresh homelab setup
2. Restore .env files and configs
3. Use Backrest to restore data
4. Restart services

Q: Does Backrest backup everything automatically?

A: Only what you configure:

• Default: Immich photos and homelab configs
• Add more paths in backrest/compose.yaml volumes
• Create backup plans in Backrest UI for each path

Performance Questions

Q: Services are running slow - how do I optimize?

A:

1. Check resources: docker stats - are you out of RAM/CPU?
2. Reduce services: Stop unused services
3. Use SSD: Move Docker to SSD storage
4. Add RAM: Minimum 8GB, 16GB+ recommended
5. Enable GPU: For Jellyfin and Immich

Q: Docker is using too much disk space - what do I do?

A:

# Check Docker disk usage
docker system df

# Clean up
docker system prune -a --volumes

# WARNING: This removes all stopped containers and unused volumes!

Better approach - clean specific services:

cd compose/path/to/service
docker compose down
docker volume rm $(docker volume ls -q | grep servicename)
docker compose up -d

Q: How do I limit RAM/CPU for a service?

A: Add resource limits to compose.yaml:

services:
  servicename:
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 4G
        reservations:
          memory: 2G

Update Questions

Q: How do I update a service?

A:

cd compose/path/to/service
docker compose pull
docker compose up -d

See Updates Guide for details.

Q: How often should I update?

A:

• Security updates: Weekly
• Feature updates: Monthly
• Major versions: When stable

Use Watchtower for automatic updates (optional).

Q: Will updating break my configuration?

A: Usually no, but:

• Always backup before major updates
• Check release notes for breaking changes
• Test in staging environment if critical

Security Questions

Q: Is this setup secure?

A: Reasonably secure with best practices:

• ✅ SSL/TLS encryption
• ✅ SSO authentication
• ✅ Secrets in environment files
• ⚠️ Some services exposed to internet
• ⚠️ Depends on keeping services updated

See Security Guide for hardening.

Q: Should I expose my homelab to the internet?

A: Depends on your risk tolerance:

• Yes: Convenient access from anywhere, Let's Encrypt works
• No: More secure, requires VPN for external access
• Hybrid: Expose only essential services, use VPN for sensitive ones

Q: What if someone gets my LLDAP password?

A: They can access all SSO-protected services. Mitigations:

• Use strong, unique passwords
• Enable 2FA where supported
• Review LLDAP access logs
• Use fail2ban to block brute force
• Consider VPN-only access

Troubleshooting

For specific error messages and debugging, see:

• Common Issues
• Debugging Guide

Still stuck? Check:

1. Service logs: docker compose logs
2. Traefik logs: docker logs traefik
3. Container status: docker ps -a
4. Network connectivity: docker network inspect homelab