Delmar/bikinibottom

Fork 0

Files

julien e19aff248d Added gitea-mirror

2026-01-19 08:34:20 +01:00

7.4 KiB

Raw Blame History

Nix Package Distribution Guide

This guide explains how Gitea Mirror is distributed via Nix and how users can consume it.

Distribution Methods

Method 1: Direct GitHub Usage (Zero Infrastructure)

No CI, releases, or setup needed! Users can consume directly from GitHub:

# Latest from main branch
nix run --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror

# Pin to specific commit
nix run github:RayLabsHQ/gitea-mirror/abc123def

# Pin to git tag
nix run github:RayLabsHQ/gitea-mirror/v3.8.11

How it works:

Nix fetches the repository from GitHub
Nix reads flake.nix and flake.lock
Nix builds the package locally on the user's machine
Package is cached in /nix/store for reuse

Pros:

Zero infrastructure needed
Works immediately after pushing code
Users always get reproducible builds

Cons:

Users must build from source (slower first time)
Requires build dependencies (Bun, etc.)

Method 2: CI Build Caching

The GitHub Actions workflow uses Magic Nix Cache (by Determinate Systems) to cache builds:

Zero configuration required - no accounts or tokens needed
Automatic - CI workflow handles everything
Uses GitHub Actions cache - fast, reliable, free

How It Works:

GitHub Actions builds the package on each push/PR
Build artifacts are cached in GitHub Actions cache
Subsequent builds reuse cached dependencies (faster CI)

Note: This caches CI builds. Users still build locally, but the flake.lock ensures reproducibility.

Method 3: nixpkgs Submission (Official Distribution)

Submit to the official Nix package repository for maximum visibility.

Process:

Prepare package (already done with flake.nix)
Test thoroughly
Submit PR to nixpkgs: https://github.com/NixOS/nixpkgs

User Experience:

# After acceptance into nixpkgs
nix run nixpkgs#gitea-mirror

# NixOS configuration
environment.systemPackages = [ pkgs.gitea-mirror ];

Pros:

Maximum discoverability (official repo)
Trusted by Nix community
Included in NixOS search
Binary caching by cache.nixos.org

Cons:

Submission/review process
Must follow nixpkgs guidelines
Updates require PRs

Current Distribution Strategy

Phase 1: Direct GitHub (Immediate) ✅

Already working! Users can:

nix run github:RayLabsHQ/gitea-mirror

Phase 2: CI Build Validation ✅

GitHub Actions workflow validates builds on every push/PR:

Uses Magic Nix Cache for fast CI builds
Tests on both Linux and macOS
No setup required - works automatically

Phase 3: Version Releases (Optional)

Tag releases for version pinning:

git tag v3.8.11
git push origin v3.8.11

# Users can then pin:
nix run github:RayLabsHQ/gitea-mirror/v3.8.11

Phase 4: nixpkgs Submission (Long Term)

Once package is stable and well-tested, submit to nixpkgs.

User Documentation

For Users: How to Install

Add this to your docs/NIX_DEPLOYMENT.md:

Option 1: Direct Install (No Configuration)

# Run immediately
nix run --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror

# Install to profile
nix profile install --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror

Option 2: Pin to Specific Version

# Pin to git tag
nix run github:RayLabsHQ/gitea-mirror/v3.8.11

# Pin to commit
nix run github:RayLabsHQ/gitea-mirror/abc123def

# Lock in flake.nix
inputs.gitea-mirror.url = "github:RayLabsHQ/gitea-mirror/v3.8.11";

Option 3: NixOS Configuration

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    gitea-mirror.url = "github:RayLabsHQ/gitea-mirror";
    # Or pin to version:
    # gitea-mirror.url = "github:RayLabsHQ/gitea-mirror/v3.8.11";
  };

  outputs = { nixpkgs, gitea-mirror, ... }: {
    nixosConfigurations.your-host = nixpkgs.lib.nixosSystem {
      modules = [
        gitea-mirror.nixosModules.default
        {
          services.gitea-mirror = {
            enable = true;
            betterAuthUrl = "https://mirror.example.com";
            openFirewall = true;
          };
        }
      ];
    };
  };
}

Maintaining the Distribution

Releasing New Versions

# 1. Update version in package.json
vim package.json  # Update version field

# 2. Update flake.nix version (line 17)
vim flake.nix  # Update version = "X.Y.Z";

# 3. Commit changes
git add package.json flake.nix
git commit -m "chore: bump version to vX.Y.Z"

# 4. Create git tag
git tag vX.Y.Z
git push origin main
git push origin vX.Y.Z

# 5. GitHub Actions builds and caches automatically

Users can then pin to the new version:

nix run github:RayLabsHQ/gitea-mirror/vX.Y.Z

Updating Flake Lock

The flake.lock file pins all dependencies. Update it periodically:

# Update all inputs
nix flake update

# Update specific input
nix flake lock --update-input nixpkgs

# Test after update
nix build
nix flake check

# Commit the updated lock file
git add flake.lock
git commit -m "chore: update flake dependencies"
git push

Troubleshooting Distribution Issues

Users Report Build Failures

Check GitHub Actions: Ensure CI is passing
Test locally: nix flake check
Check flake.lock: May need update if dependencies changed

CI Cache Not Working

Check workflow logs: Review GitHub Actions for errors
Clear cache: GitHub Actions → Caches → Delete relevant cache
Verify flake.lock: May need nix flake update if dependencies changed

Version Pinning Not Working

# Verify tag exists
git tag -l

# Ensure tag is pushed
git ls-remote --tags origin

# Test specific tag
nix run github:RayLabsHQ/gitea-mirror/v3.8.11

Advanced: Custom Binary Cache

If you prefer self-hosting instead of Cachix:

Option 1: S3-Compatible Storage

# Generate signing key
nix-store --generate-binary-cache-key cache.example.com cache-priv-key.pem cache-pub-key.pem

# Push to S3
nix copy --to s3://my-nix-cache?region=us-east-1 $(nix-build)

Users configure:

substituters = https://my-bucket.s3.amazonaws.com/nix-cache
trusted-public-keys = cache.example.com:BASE64_PUBLIC_KEY

Option 2: Self-Hosted Nix Store

Run nix-serve on your server:

# On server
nix-serve -p 8080

# Behind nginx/caddy
proxy_pass http://localhost:8080;