Framerr Deployment & Usage Guide

Self-hosted homelab dashboard with drag-and-drop widgets, Plex SSO, and deep integrations for Sonarr, Radarr, Overseerr, and more.

1. Prerequisites

Required

• Docker & Docker Compose (recommended) OR a system with Node.js 20+ (for development)
• 64-bit Linux, macOS, or Windows (with WSL2)
• At least 512MB RAM (1GB+ recommended for multiple integrations)
• 500MB disk space for application + database

Optional (for integrations)

• Plex, Jellyfin, or Emby server
• Sonarr, Radarr, Overseerr, qBittorrent, etc.
• Existing reverse proxy (Nginx, Traefik, Caddy) for SSL termination

2. Installation

Option A: Docker Compose (Recommended)

1. Create a docker-compose.yml file:

services:
  framerr:
    image: pickels23/framerr:latest
    container_name: framerr
    environment:
      - PUID=1000                    # Your user ID (run: id -u)
      - PGID=1000                    # Your group ID (run: id -g)
      - TZ=America/New_York          # Your timezone
      - SECRET_ENCRYPTION_KEY=       # Generate: openssl rand -hex 32
    volumes:
      - /path/to/appdata/framerr:/config
    ports:
      - "3001:3001"                  # Host:Container port mapping
    restart: unless-stopped

2. Generate encryption key:

openssl rand -hex 32

Copy the output and paste it as the value for SECRET_ENCRYPTION_KEY.

3. Start the container:

docker-compose up -d

4. Access at http://your-server-ip:3001

Option B: Unraid

1. Download docs/unraid/Framerr.xml
2. Copy to /boot/config/plugins/dockerMan/templates/ on your Unraid server
3. Add container from Docker tab → "Add Container" → select "Framerr"
4. Set SECRET_ENCRYPTION_KEY (generate as above) and volume paths
5. Apply and start

Option C: Development (Local)

# Clone repository
git clone https://github.com/Framerrr/Framerr.git
cd Framerr

# Install dependencies
npm install
cd server && npm install && cd ..

# Run in development mode (hot reload)
npm run dev:all

Access at http://localhost:3001

3. Configuration

Environment Variables

First-Run Setup Wizard

1. Open http://your-server:3001
2. Create admin account (username/password)
3. Configure basic settings:
   • Application URL (for SSO callbacks)
   • Email settings (for notifications)
   • Default theme
4. Complete setup → redirected to dashboard

Integration Configuration

After setup, add integrations via Settings → Integrations:

1. Plex SSO (optional but recommended):

   • Plex URL: http://plex:32400 (or your Plex URL)
   • Plex Token: Get from Plex.tv → Account → API
   • Enable "Allow Plex login" in Settings → Authentication

2. Sonarr/Radarr:

   • URL: http://sonarr:8989 (or your instance URL)
   • API Key: From Sonarr/Radarr → Settings → General → Security → API Key

3. Overseerr:

   • URL: http://overseerr:5055
   • API Key: Overseerr → Settings → General → API Key

4. qBittorrent:

   • URL: http://qbittorrent:8080
   • Username/Password: Your qBittorrent credentials

Note: Integration URLs must be reachable from the Framerr container. Use Docker network names (e.g., http://sonarr:8989) if on same Docker network.

4. Build & Run

Development Build

# Install all dependencies (root + server)
npm install
cd server && npm install && cd ..

# Start both frontend (Vite) and backend (Express) with hot reload
npm run dev:all

# Or separately:
# Terminal 1: npm run dev (frontend)
# Terminal 2: npm run server:dev (backend)

Production Build

# Build frontend
npm run build

# Build server (creates dist/ folder)
npm run build:server

# Start production server
npm start

Docker Build (Custom)

docker build -t framerr:custom .

5. Deployment

Docker Compose (Production)

Use the same docker-compose.yml as installation, but add:

services:
  framerr:
    # ... existing config ...
    networks:
      - homelab  # Use your existing Docker network
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.framerr.rule=Host(`framerr.yourdomain.com`)"
      - "traefik.http.services.framerr.loadbalancer.server.port=3001"
    # Optional: resource limits
    deploy:
      resources:
        limits:
          memory: 1G

Behind Reverse Proxy

Framerr works with:

• Authelia/Authentik: Set AUTH_PROXY_MODE=true and whitelist proxy IPs
• Nginx Proxy Manager: Add custom Nginx config:

  location / {
      proxy_pass http://framerr:3001;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_set_header Host $host;
  }
  

• Cloudflare Tunnel: Create tunnel to framerr:3001

Backup Strategy

Persistent data is in /config (or $DATA_DIR). Backup:

# Stop container
docker-compose stop framerr

# Backup entire config directory
tar -czf framerr-backup-$(date +%Y%m%d).tar.gz /path/to/appdata/framerr/

# Restore: extract to same location and restart
docker-compose start framerr

6. Troubleshooting

Container Won't Start

• Check logs: docker logs framerr
• Missing SECRET_ENCRYPTION_KEY: Ensure it's set and is 32-byte hex (64 characters)
• Permission errors: Set PUID/PGID to your user's IDs (id -u and id -g)
• Port conflict: Change host port mapping ("8080:3001" instead of "3001:3001")

Integrations Not Working

1. Verify connectivity from inside container:

   docker exec framerr curl -I http://sonarr:8989
   

2. Check API keys in Framerr integration settings
3. Ensure services on same Docker network (use docker network ls and docker network inspect)
4. Review service logs in Framerr: Settings → System Logs

Dashboard Not Loading / Blank Screen

• Browser console errors: Check for CORS or mixed-content (HTTP vs HTTPS)
• Clear browser cache and localStorage (Application tab → Clear storage)
• Check backend logs for startup errors

Mobile Layout Issues

• Framerr uses a separate mobile layout. Ensure widgets are added to mobile view via:
  1. Enter edit mode (pencil icon)
  2. Switch to mobile view (phone icon)
  3. Drag widgets to mobile grid
  4. Save layout

Database Corruption

If /config/framerr.db is corrupted:

1. Stop container
2. Backup current /config folder
3. Delete framerr.db (Framerr will recreate empty DB on startup)
4. Restart and reconfigure integrations (widget configurations are stored in DB)

Performance Issues

• High CPU: Reduce polling intervals in integration settings (default: 10-30s)
• Memory: Limit number of real-time widgets (Plex streams, qBittorrent)
• History data: Metric history retention defaults to 3 days. Adjust in Settings → System → Metric History

Support & Updates

• Documentation: https://framerrr.github.io/Framerr/
• Changelog: CHANGELOG.md
• Issues: GitHub Issues
• Donate: Buy Me a Coffee

Warning: Framerr is in early development (0.x.x). Breaking changes may occur between minor releases. Pin your Docker image version (e.g., pickels23/framerr:0.2.1) for production stability.