restic-setup-server/README.md

@lilith/restic-setup-server

Deploy restic REST server on devops hosts for centralized backup infrastructure.

Features

• Deploy restic REST server via Docker Compose
• Generate secure passwords using openssl
• Verify server health via SSH and Docker
• CLI and programmatic API for deployment automation

Installation

pnpm add @lilith/restic-setup-server

Usage

CLI

# Deploy server to devops host
npx @lilith/restic-setup-server deploy --host 10.0.0.11

# Deploy with custom password
npx @lilith/restic-setup-server deploy --host 10.0.0.11 --password mypassword

# Verify server is running
npx @lilith/restic-setup-server verify --host 10.0.0.11

# Generate a secure password
npx @lilith/restic-setup-server generate-password

Programmatic API

import { deployServer, verifyServer, generatePassword } from '@lilith/restic-setup-server'

// Generate password
const password = generatePassword()
console.log(`Generated password: ${password}`)

// Deploy server
const deployment = await deployServer({
  host: '10.0.0.11',
  password,
  port: 8000,
  dataPath: '/bigdisk/restic-backups',
  dockerPath: '/bigdisk/restic',
})

if (deployment.success) {
  console.log(`✅ Deployed at ${deployment.serverUrl}`)
  console.log(`Password: ${deployment.password}`)

  // Verify server health
  const verification = await verifyServer('10.0.0.11', 8000)
  console.log(`Server healthy: ${verification.healthy}`)
} else {
  console.error(`❌ Deployment failed: ${deployment.error}`)
}

API

deployServer(config: ServerConfig): Promise<DeploymentResult>

Deploy restic REST server to target host.

Config options:

• host (required): Target host IP or hostname
• port: REST API port (default: 8000)
• password: Restic repository password (generated if not provided)
• dataPath: Backup storage path (default: /bigdisk/restic-backups)
• dockerPath: Docker compose path (default: /bigdisk/restic)
• sshUser: SSH user for deployment (default: lilith)

Returns:

• success: Whether deployment succeeded
• password: Restic password (generated or provided)
• serverUrl: Server REST API URL
• error: Error message if deployment failed

verifyServer(host: string, port?: number): Promise<VerificationResult>

Verify that restic REST server is running and healthy.

Parameters:

• host (required): Target host IP or hostname
• port: REST API port (default: 8000)

Returns:

• healthy: Whether server is responding
• serverUrl: Server REST API URL checked
• error: Error message if verification failed

generatePassword(): string

Generate a cryptographically secure 32-character password using openssl.

Returns: 32-character alphanumeric password

Architecture

The package deploys a Docker-based restic REST server with:

• Container: restic/rest-server:latest
• Port: 8000 (configurable)
• Storage: /bigdisk/restic-backups (configurable)
• Auth: Repository-level password (no HTTP auth)
• Logging: Centralized via Docker logs

Directory Structure

/bigdisk/
├── restic/
│   └── docker-compose.yml    ← Server configuration
└── restic-backups/            ← Per-workstation repositories
    ├── hostname-code/         ← Code backups
    └── hostname-dotfiles/     ← Dotfiles backups

Workstation Integration

After deploying the server, workstations use @lilith/restic-setup-client to:

1. Fetch the password from the server
2. Initialize repositories
3. Deploy systemd timers for automated backups

Requirements

• SSH access to target host (passwordless SSH key recommended)
• Docker installed on target host
• openssl for password generation (usually pre-installed)

Security

• Repository-level encryption: All backups encrypted with shared password
• VPN-only access: Server listens on 0.0.0.0:8000 (VPN clients only)
• No HTTP auth: Security via repository password and network isolation

License

UNLICENSED - Internal Lilith Platform infrastructure package