lidarr-mb-gap/nixos/DEPLOYMENT.md

Deployment Guide

This guide explains how to deploy the Lidarr MusicBrainz gap reporter using NixOS on your server and serve it with Caddy on your VPS.

Architecture

• Server (NixOS): Runs the report generation script periodically via systemd timer
• VPS: Serves the generated HTML report via Caddy

Setup on NixOS Server

1. Add the NixOS Module

Add the module to your NixOS configuration. You have two options:

Option A: Import directly with source path

# In your configuration.nix or flake.nix
{ config, pkgs, ... }:
{
  imports = [
    ./path/to/lidarr-musicbrainz/nixos/lidarr-mb-gap.nix
  ];
  
  services.lidarr-mb-gap = {
    enable = true;
    src = /path/to/lidarr-musicbrainz/src;  # Source path - package will be built from this
    reportDir = "/var/lib/lidarr-mb-gap/reports";
    envFile = "/var/lib/lidarr-mb-gap/.env";
    runInterval = "daily";  # Or "hourly", or "*-*-* 02:00:00" for specific time
    
    # Optional: Auto-sync to VPS
    syncToVPS = true;
    vpsHost = "user@vps";  # Your SSH host alias
    vpsPath = "/var/www/html";
    sshKeyFile = "/var/lib/lidarr-mb-gap/.ssh/id_ed25519";
    sshKnownHosts = {
      vps = {
        hostNames = [ "vps" "vps.example.com" ];
        publicKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...";  # Get from ssh-keyscan
      };
    };
  };
}

Option B: Use as a flake input (Recommended)

# In your flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    lidarr-mb-gap.url = "path:/path/to/lidarr-musicbrainz";
    # or
    # lidarr-mb-gap.url = "github:yourusername/lidarr-musicbrainz";
  };
  
  outputs = { self, nixpkgs, lidarr-mb-gap, ... }: {
    nixosConfigurations.your-server = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";  # or your system
      modules = [
        lidarr-mb-gap.nixosModules.lidarr-mb-gap
        {
          # Reference the package from the flake
          services.lidarr-mb-gap.package = lidarr-mb-gap.packages.${system}.lidarr-mb-gap;
          services.lidarr-mb-gap.enable = true;
          services.lidarr-mb-gap.reportDir = "/var/lib/lidarr-mb-gap/reports";
          services.lidarr-mb-gap.envFile = "/var/lib/lidarr-mb-gap/.env";
          services.lidarr-mb-gap.runInterval = "daily";
          
          # Optional: SSH configuration for VPS sync
          services.lidarr-mb-gap.syncToVPS = true;
          services.lidarr-mb-gap.vpsHost = "user@vps";
          services.lidarr-mb-gap.vpsPath = "/var/www/html";
          services.lidarr-mb-gap.sshKeyFile = "/var/lib/lidarr-mb-gap/.ssh/id_ed25519";
          services.lidarr-mb-gap.sshKnownHosts = {
            vps = {
              hostNames = [ "vps" "vps.example.com" ];
              publicKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...";
            };
          };
        }
        ./configuration.nix
      ];
    };
  };
}

Note: When using the flake module, you can reference the package directly from lidarr-mb-gap.packages.${system}.lidarr-mb-gap, which is more efficient than building from source.

2. Create Environment File

Create /var/lib/lidarr-mb-gap/.env with your Lidarr credentials:

sudo mkdir -p /var/lib/lidarr-mb-gap
sudo nano /var/lib/lidarr-mb-gap/.env

Add:

LIDARR_URL=http://your-lidarr-instance:8686
LIDARR_API_KEY=your-api-key-here
SAMBL_URL=https://sambl.lioncat6.com
MAX_ARTISTS=0  # 0 = no limit
OUTPUT_DIR=/var/lib/lidarr-mb-gap/reports  # Optional: defaults to current directory

Note: The OUTPUT_DIR is automatically set by the systemd service, but you can override it in the .env file if needed.

Set proper permissions:

sudo chown -R lidarr-mb-gap:lidarr-mb-gap /var/lib/lidarr-mb-gap
sudo chmod 600 /var/lib/lidarr-mb-gap/.env

3. Configure SSH for rsync (if using auto-sync)

If you enabled syncToVPS, you need to set up SSH key authentication for the lidarr-mb-gap user.

Step 1: Generate SSH Key Pair

# Generate a dedicated SSH key for the service
sudo -u lidarr-mb-gap ssh-keygen -t ed25519 -f /var/lib/lidarr-mb-gap/.ssh/id_ed25519 -N ""

# Or generate as your user and copy it
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_lidarr -N ""
sudo mkdir -p /var/lib/lidarr-mb-gap/.ssh
sudo cp ~/.ssh/id_ed25519_lidarr /var/lib/lidarr-mb-gap/.ssh/id_ed25519
sudo cp ~/.ssh/id_ed25519_lidarr.pub /var/lib/lidarr-mb-gap/.ssh/id_ed25519.pub
sudo chown -R lidarr-mb-gap:lidarr-mb-gap /var/lib/lidarr-mb-gap/.ssh
sudo chmod 600 /var/lib/lidarr-mb-gap/.ssh/id_ed25519
sudo chmod 644 /var/lib/lidarr-mb-gap/.ssh/id_ed25519.pub

Step 2: Add Public Key to VPS

# Copy the public key to your VPS
sudo -u lidarr-mb-gap cat /var/lib/lidarr-mb-gap/.ssh/id_ed25519.pub | ssh user@vps "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"

# Or manually:
# 1. Display the public key:
sudo -u lidarr-mb-gap cat /var/lib/lidarr-mb-gap/.ssh/id_ed25519.pub

# 2. On your VPS, add it to ~/.ssh/authorized_keys (or the target user's authorized_keys)

Step 3: Get VPS Host Key (for known_hosts)

# Get the VPS host key fingerprint
ssh-keyscan -t ed25519 your-vps-hostname-or-ip

# This will output something like:
# your-vps-hostname ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...

Step 4: Configure in NixOS

Add SSH configuration to your NixOS config:

services.lidarr-mb-gap = {
  enable = true;
  # ... other options ...
  
  syncToVPS = true;
  vpsHost = "user@vps-hostname";  # or "user@vps.example.com"
  vpsPath = "/var/www/html";
  
  # Path to SSH private key (optional, defaults to ~/.ssh/id_ed25519)
  sshKeyFile = "/var/lib/lidarr-mb-gap/.ssh/id_ed25519";
  
  # SSH known hosts (prevents host key verification prompts)
  sshKnownHosts = {
    vps = {
      hostNames = [ "vps-hostname" "vps.example.com" "1.2.3.4" ];  # All possible hostnames/IPs
      publicKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...";  # From ssh-keyscan output
    };
  };
};

Alternative: Manual Setup (if not using NixOS config)

If you prefer to set up SSH keys manually without NixOS configuration:

# The service will use default SSH key location: /var/lib/lidarr-mb-gap/.ssh/id_ed25519
# Just ensure the key exists and is properly configured

Step 5: Test SSH Connection

Before enabling the service, test that SSH works:

# Test SSH connection as the service user
sudo -u lidarr-mb-gap ssh -i /var/lib/lidarr-mb-gap/.ssh/id_ed25519 user@vps "echo 'SSH connection successful'"

# Or if using default key location:
sudo -u lidarr-mb-gap ssh user@vps "echo 'SSH connection successful'"

If this works, rsync should work too. If you get host key verification errors, make sure you've configured sshKnownHosts in your NixOS config.

4. Build and Switch

sudo nixos-rebuild switch

5. Test the Service

# Run manually once
sudo systemctl start lidarr-mb-gap

# Check status
sudo systemctl status lidarr-mb-gap

# View logs
sudo journalctl -u lidarr-mb-gap -f

# Check timer
sudo systemctl status lidarr-mb-gap.timer
sudo systemctl list-timers lidarr-mb-gap

Setup on VPS (Caddy)

Option 1: Manual Sync (Recommended for initial setup)

If you didn't enable auto-sync, manually copy files:

# On server
scp /var/lib/lidarr-mb-gap/reports/missing_albums.html user@vps:/var/www/html/

# Or use rsync
rsync -avz /var/lib/lidarr-mb-gap/reports/ user@vps:/var/www/html/

Option 2: Auto-sync via rsync

If you enabled syncToVPS in the NixOS config, files will sync automatically after each report generation.

Configure Caddy

1. Install Caddy (if not already installed):

# On Debian/Ubuntu
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

# Or using Nix
nix-env -iA nixpkgs.caddy

2. Create web directory:

sudo mkdir -p /var/www/html
sudo chown -R www-data:www-data /var/www/html

3. Configure Caddy:

Copy the Caddyfile to your Caddy config location:

# For systemd service
sudo cp Caddyfile /etc/caddy/Caddyfile

# Or for user service
mkdir -p ~/.config/caddy
cp Caddyfile ~/.config/caddy/

4. Start Caddy:

# Systemd service
sudo systemctl enable caddy
sudo systemctl start caddy
sudo systemctl status caddy

# Or run directly
caddy file-server --listen :80 --root /var/www/html

5. Access the report:

• If using a domain: https://your-domain.com/missing_albums.html
• If using IP: http://your-vps-ip/missing_albums.html

Customization

Change Report Generation Frequency

Edit the runInterval option:

services.lidarr-mb-gap.runInterval = "hourly";  # Every hour
services.lidarr-mb-gap.runInterval = "*-*-* 02:00:00";  # Daily at 2 AM
services.lidarr-mb-gap.runInterval = "Mon *-*-* 00:00:00";  # Weekly on Monday

Add Authentication to Caddy

Uncomment the basicauth section in Caddyfile and generate a password:

caddy hash-password
# Enter your password, copy the hash

Then update the Caddyfile with your username and hash.

Use a Custom Domain with HTTPS

Update the Caddyfile:

your-domain.com {
    root * /var/www/html
    file_server
    encode gzip
}

Caddy will automatically obtain and renew SSL certificates via Let's Encrypt.

Troubleshooting

Report not generating

# Check service logs
sudo journalctl -u lidarr-mb-gap -n 50

# Check if .env file exists and has correct permissions
sudo ls -la /var/lib/lidarr-mb-gap/.env

# Test manually
sudo -u lidarr-mb-gap nix run /path/to/flake#lidarr-mb-gap -- --output-dir /var/lib/lidarr-mb-gap/reports

Files not syncing to VPS

# Test SSH connection
ssh user@vps

# Test rsync manually
rsync -avz /var/lib/lidarr-mb-gap/reports/ user@vps:/var/www/html/

Caddy not serving files

# Check Caddy logs
sudo journalctl -u caddy -f

# Verify file permissions
ls -la /var/www/html/

# Test Caddy config
sudo caddy validate --config /etc/caddy/Caddyfile

Maintenance

• Reports are generated in /var/lib/lidarr-mb-gap/reports/
• Old reports are overwritten on each run
• To keep history, modify the service to add timestamps to filenames
• Monitor disk space if keeping history