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";
  };
}

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";
        }
        ./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, set up SSH key authentication:

# On the server
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_lidarr
ssh-copy-id -i ~/.ssh/id_ed25519_lidarr.pub user@vps

# Add to ~/.ssh/config
Host vps
    HostName your-vps-ip-or-domain
    User your-username
    IdentityFile ~/.ssh/id_ed25519_lidarr

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