Nix Deployment Quick Reference

TL;DR

# Just run it - zero configuration needed!
nix run --extra-experimental-features 'nix-command flakes' .#gitea-mirror

Secrets auto-generate, database auto-initializes, and the web UI starts at http://localhost:4321.

Note: If you have flakes enabled in your nix config, you can omit --extra-experimental-features 'nix-command flakes'

Installation Options

1. Run Without Installing

nix run --extra-experimental-features 'nix-command flakes' .#gitea-mirror

2. Install to Profile

nix profile install --extra-experimental-features 'nix-command flakes' .#gitea-mirror
gitea-mirror

3. NixOS System Service

# configuration.nix
{
  inputs.gitea-mirror.url = "github:RayLabsHQ/gitea-mirror";

  services.gitea-mirror = {
    enable = true;
    betterAuthUrl = "https://mirror.example.com";  # For production
    openFirewall = true;
  };
}

4. Development

nix develop --extra-experimental-features 'nix-command flakes'
# or
direnv allow  # Handles experimental features automatically

Enable Flakes Permanently (Recommended)

To avoid typing --extra-experimental-features every time, add to ~/.config/nix/nix.conf:

experimental-features = nix-command flakes

What Gets Auto-Generated?

On first run, the wrapper automatically:

Creates ~/.local/share/gitea-mirror/ (or $DATA_DIR)
Generates BETTER_AUTH_SECRET → .better_auth_secret
Generates ENCRYPTION_SECRET → .encryption_secret
Initializes SQLite database
Runs startup recovery and repair scripts
Starts the application

Key Commands

# Database management
gitea-mirror-db init      # Initialize database
gitea-mirror-db check     # Health check
gitea-mirror-db fix       # Fix issues

# Development (add --extra-experimental-features 'nix-command flakes' if needed)
nix develop               # Enter dev shell
nix build                 # Build package
nix flake check           # Validate flake
nix flake update          # Update dependencies

Environment Variables

All vars from docker-compose.alt.yml are supported:

DATA_DIR="$HOME/.local/share/gitea-mirror"
PORT=4321
HOST="0.0.0.0"
BETTER_AUTH_URL="http://localhost:4321"

# Secrets (auto-generated if not set)
BETTER_AUTH_SECRET=auto-generated
ENCRYPTION_SECRET=auto-generated

# Concurrency (for perfect ordering, set both to 1)
MIRROR_ISSUE_CONCURRENCY=3
MIRROR_PULL_REQUEST_CONCURRENCY=5

NixOS Module Options

services.gitea-mirror = {
  enable = true;
  package = ...;                        # Override package
  dataDir = "/var/lib/gitea-mirror";   # Data location
  user = "gitea-mirror";               # Service user
  group = "gitea-mirror";              # Service group
  host = "0.0.0.0";                    # Bind address
  port = 4321;                         # Listen port
  betterAuthUrl = "http://...";        # External URL
  betterAuthTrustedOrigins = "...";    # CORS origins
  mirrorIssueConcurrency = 3;          # Concurrency
  mirrorPullRequestConcurrency = 5;    # Concurrency
  environmentFile = null;              # Optional secrets file
  openFirewall = true;                 # Open firewall
};

Comparison: Docker vs Nix

Feature	Docker	Nix
Config Required	BETTER_AUTH_SECRET	None (auto-generated)
Startup	`docker-compose up`	`nix run .#gitea-mirror`
Service	Docker daemon	systemd (NixOS)
Updates	`docker pull`	`nix flake update`
Reproducible	Image-based	Hash-based

Full Documentation

See docs/NIX_DEPLOYMENT.md for:

Complete NixOS module configuration
Home Manager integration
Production deployment examples
Migration from Docker
Troubleshooting guide

Key Features

Zero-config deployment - Runs immediately without setup
Auto-secret generation - Secure secrets created and persisted
Startup recovery - Handles interrupted jobs automatically
Graceful shutdown - Proper signal handling
Health checks - Built-in monitoring support
Security hardening - NixOS module includes systemd protections
Docker parity - Same behavior as docker-compose.alt.yml

4.2 KiB Raw Blame History