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

```nix
# 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)

```nix
# 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:

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

Add:
```env
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:
```bash
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

```bash
# 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

```bash
# 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)

```bash
# 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:

```nix
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:

```bash
# 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:

```bash
# 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

```bash
sudo nixos-rebuild switch
```

### 5. Test the Service

```bash
# 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:

```bash
# 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):

```bash
# 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**:

```bash
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:

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

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

4. **Start Caddy**:

```bash
# 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:

```nix
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:

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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