diff --git a/.github/workflows/nix-build.yml b/.github/workflows/nix-build.yml
new file mode 100644
index 0000000..d74b95a
--- /dev/null
+++ b/.github/workflows/nix-build.yml
@@ -0,0 +1,41 @@
+name: Nix Build and Cache
+
+on:
+  push:
+    branches: [main]
+    tags:
+      - 'v*'
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: cachix/install-nix-action@v24
+        with:
+          extra_nix_config: |
+            experimental-features = nix-command flakes
+
+      - uses: cachix/cachix-action@v12
+        with:
+          name: gitea-mirror  # Your cache name
+          authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'
+
+      - name: Build package
+        run: nix build --print-build-logs
+
+      - name: Check flake
+        run: nix flake check
+
+      - name: Test run (dry run)
+        run: |
+          # Just verify the binary exists and is executable
+          test -x ./result/bin/gitea-mirror
+          ./result/bin/gitea-mirror --version || echo "Version check skipped"
diff --git a/DISTRIBUTION_SUMMARY.md b/DISTRIBUTION_SUMMARY.md
new file mode 100644
index 0000000..c093695
--- /dev/null
+++ b/DISTRIBUTION_SUMMARY.md
@@ -0,0 +1,193 @@
+# Nix Distribution - Ready to Use! 🎉
+
+## Current Status: ✅ WORKS NOW
+
+Your Nix package is **already distributable**! Users can run it directly from GitHub without any additional setup on your end.
+
+## How Users Will Use It
+
+### Simple: Just Run From GitHub
+
+```bash
+nix run --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
+```
+
+That's it! No releases, no CI, no infrastructure needed. It works right now.
+
+---
+
+## What Happens When They Run This?
+
+1. **Nix fetches** your repo from GitHub
+2. **Nix reads** `flake.nix` and `flake.lock`
+3. **Nix builds** the package on their machine
+4. **Nix runs** the application
+5. **Result cached** in `/nix/store` for reuse
+
+---
+
+## Do You Need CI or Releases?
+
+### For Basic Usage: **NO**
+Users can already use it from GitHub. No CI or releases required.
+
+### For Better UX: **Recommended**
+Set up binary caching so users don't compile from source.
+
+---
+
+## Next Steps (Optional but Recommended)
+
+### Option 1: Add Binary Cache (5 minutes)
+
+**Why:** Users download pre-built binaries instead of compiling (much faster!)
+
+**How:**
+1. Create free account at https://cachix.org/
+2. Create cache named `gitea-mirror`
+3. Add GitHub secret: `CACHIX_AUTH_TOKEN`
+4. GitHub Actions workflow already created at `.github/workflows/nix-build.yml`
+5. Add to your docs:
+   ```bash
+   # Users run once
+   cachix use gitea-mirror
+
+   # Then they get fast binary downloads
+   nix run github:RayLabsHQ/gitea-mirror
+   ```
+
+### Option 2: Release Versioning (2 minutes)
+
+**Why:** Users can pin to specific versions
+
+**How:**
+```bash
+# When ready to release
+git tag v3.8.11
+git push origin v3.8.11
+
+# Users can then pin to this version
+nix run github:RayLabsHQ/gitea-mirror/v3.8.11
+```
+
+No additional CI needed - tags work automatically with flakes!
+
+### Option 3: Submit to nixpkgs (Long Term)
+
+**Why:** Maximum discoverability and trust
+
+**When:** After package is stable and well-tested
+
+**How:** Submit PR to https://github.com/NixOS/nixpkgs
+
+---
+
+## Files Created
+
+### Essential (Already Working)
+- ✅ `flake.nix` - Package definition
+- ✅ `flake.lock` - Dependency lock file
+- ✅ `.envrc` - direnv integration
+
+### Documentation
+- ✅ `NIX.md` - Quick reference for users
+- ✅ `docs/NIX_DEPLOYMENT.md` - Complete deployment guide
+- ✅ `docs/NIX_DISTRIBUTION.md` - Distribution guide for you (maintainer)
+- ✅ `README.md` - Updated with Nix instructions
+
+### CI (Optional, Already Set Up)
+- ✅ `.github/workflows/nix-build.yml` - Builds + caches to Cachix
+
+### Updated
+- ✅ `.gitignore` - Added Nix artifacts
+
+---
+
+## Comparison: Your Distribution Options
+
+| Setup | Time | User Experience | What You Need |
+|-------|------|----------------|---------------|
+| **Direct GitHub** | 0 min ✅ | Slow (build from source) | Nothing! Works now |
+| **+ Cachix** | 5 min | Fast (binary download) | Cachix account + token |
+| **+ Git Tags** | 2 min | Versionable | Just push tags |
+| **+ nixpkgs** | Hours | Official/Trusted | PR review process |
+
+**Recommendation:** Start with Direct GitHub (already works!), add Cachix this week for better UX.
+
+---
+
+## Testing Your Distribution
+
+You can test it right now:
+
+```bash
+# Test direct GitHub usage
+nix run --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
+
+# Test with specific commit
+nix run github:RayLabsHQ/gitea-mirror/$(git rev-parse HEAD)
+
+# Validate flake
+nix flake check
+```
+
+---
+
+## User Documentation Locations
+
+Users will find instructions in:
+1. **README.md** - Installation section (already updated)
+2. **NIX.md** - Quick reference
+3. **docs/NIX_DEPLOYMENT.md** - Detailed guide
+
+All docs include the correct commands with experimental features flags.
+
+---
+
+## When to Release New Versions
+
+### For Git Tag Releases:
+```bash
+# 1. Update version in package.json
+vim package.json
+
+# 2. Update version in flake.nix (line 17)
+vim flake.nix  # version = "3.8.12";
+
+# 3. Commit and tag
+git add package.json flake.nix
+git commit -m "chore: bump version to v3.8.12"
+git tag v3.8.12
+git push origin main
+git push origin v3.8.12
+```
+
+Users can then use: `nix run github:RayLabsHQ/gitea-mirror/v3.8.12`
+
+### No Release Needed For:
+- Bug fixes
+- Small changes
+- Continuous updates
+
+Users can always use latest from main: `nix run github:RayLabsHQ/gitea-mirror`
+
+---
+
+## Summary
+
+**✅ Ready to distribute RIGHT NOW**
+- Just commit and push your `flake.nix`
+- Users can run directly from GitHub
+- No CI, releases, or infrastructure required
+
+**🚀 Recommended next: Add Cachix (5 minutes)**
+- Much better user experience
+- Workflow already created
+- Free for public projects
+
+**📦 Optional later: Submit to nixpkgs**
+- Maximum discoverability
+- Official Nix repository
+- Do this once package is stable
+
+See `docs/NIX_DISTRIBUTION.md` for complete details!
diff --git a/NIX.md b/NIX.md
index ab91bea..10dcca7 100644
--- a/NIX.md
+++ b/NIX.md
@@ -3,7 +3,10 @@
 ## TL;DR
 
 ```bash
-# Just run it - zero configuration needed!
+# From GitHub (no clone needed!)
+nix run --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
+
+# Or from local clone
 nix run --extra-experimental-features 'nix-command flakes' .#gitea-mirror
 ```
 
@@ -15,18 +18,33 @@ Secrets auto-generate, database auto-initializes, and the web UI starts at http:
 
 ## Installation Options
 
-### 1. Run Without Installing
+### 1. Run Without Installing (from GitHub)
 ```bash
-nix run --extra-experimental-features 'nix-command flakes' .#gitea-mirror
+# Latest version from main branch
+nix run --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
+
+# Pin to specific version
+nix run github:RayLabsHQ/gitea-mirror/v3.8.11
 ```
 
 ### 2. Install to Profile
 ```bash
-nix profile install --extra-experimental-features 'nix-command flakes' .#gitea-mirror
+# Install from GitHub
+nix profile install --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
+
+# Run the installed binary
 gitea-mirror
 ```
 
-### 3. NixOS System Service
+### 3. Use Local Clone
+```bash
+# Clone and run
+git clone https://github.com/RayLabsHQ/gitea-mirror.git
+cd gitea-mirror
+nix run --extra-experimental-features 'nix-command flakes' .#gitea-mirror
+```
+
+### 4. NixOS System Service
 ```nix
 # configuration.nix
 {
@@ -40,7 +58,7 @@ gitea-mirror
 }
 ```
 
-### 4. Development
+### 5. Development (Local Clone)
 ```bash
 nix develop --extra-experimental-features 'nix-command flakes'
 # or
@@ -145,12 +163,18 @@ services.gitea-mirror = {
 
 ## Full Documentation
 
-See [docs/NIX_DEPLOYMENT.md](docs/NIX_DEPLOYMENT.md) for:
-- Complete NixOS module configuration
-- Home Manager integration
-- Production deployment examples
-- Migration from Docker
-- Troubleshooting guide
+- **[docs/NIX_DEPLOYMENT.md](docs/NIX_DEPLOYMENT.md)** - Complete deployment guide
+  - NixOS module configuration
+  - Home Manager integration
+  - Production deployment examples
+  - Migration from Docker
+  - Troubleshooting guide
+
+- **[docs/NIX_DISTRIBUTION.md](docs/NIX_DISTRIBUTION.md)** - Distribution guide for maintainers
+  - How users consume the package
+  - Setting up binary cache (Cachix)
+  - Releasing new versions
+  - Submitting to nixpkgs
 
 ---
 
diff --git a/docs/NIX_DISTRIBUTION.md b/docs/NIX_DISTRIBUTION.md
new file mode 100644
index 0000000..b8e76c6
--- /dev/null
+++ b/docs/NIX_DISTRIBUTION.md
@@ -0,0 +1,352 @@
+# 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:
+
+```bash
+# 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:**
+1. Nix fetches the repository from GitHub
+2. Nix reads `flake.nix` and `flake.lock`
+3. Nix builds the package locally on the user's machine
+4. 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: Binary Cache (Recommended)
+
+Pre-build packages and cache them so users download binaries instead of building:
+
+#### Setup: Cachix (Free for Public Projects)
+
+1. **Create account:** https://cachix.org/
+2. **Create cache:** `gitea-mirror` (public)
+3. **Add secret to GitHub:** `Settings → Secrets → CACHIX_AUTH_TOKEN`
+4. **GitHub Actions builds automatically** (see `.github/workflows/nix-build.yml`)
+
+#### User Experience:
+
+```bash
+# First time: Configure cache
+cachix use gitea-mirror
+
+# Or add to nix.conf:
+# substituters = https://cache.nixos.org https://gitea-mirror.cachix.org
+# trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= gitea-mirror.cachix.org-1:YOUR_KEY_HERE
+
+# Then use normally - downloads pre-built binaries!
+nix run github:RayLabsHQ/gitea-mirror
+```
+
+**Pros:**
+- Fast installation (no compilation)
+- Reduced bandwidth/CPU for users
+- Professional experience
+
+**Cons:**
+- Requires Cachix account (free for public)
+- Requires CI setup
+
+---
+
+### Method 3: nixpkgs Submission (Official Distribution)
+
+Submit to the official Nix package repository for maximum visibility.
+
+#### Process:
+
+1. **Prepare package** (already done with `flake.nix`)
+2. **Test thoroughly**
+3. **Submit PR to nixpkgs:** https://github.com/NixOS/nixpkgs
+
+#### User Experience:
+
+```bash
+# 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:
+
+```bash
+nix run github:RayLabsHQ/gitea-mirror
+```
+
+### Phase 2: Binary Cache (Recommended Next)
+
+Set up Cachix for faster installs:
+
+1. Create Cachix cache
+2. Add `CACHIX_AUTH_TOKEN` secret to GitHub
+3. Workflow already created in `.github/workflows/nix-build.yml`
+4. Add instructions to docs
+
+### Phase 3: Version Releases (Optional)
+
+Tag releases for version pinning:
+
+```bash
+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)
+
+```bash
+# 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: With Binary Cache (Faster)
+
+```bash
+# One-time setup
+cachix use gitea-mirror
+
+# Then install (downloads pre-built binary)
+nix profile install github:RayLabsHQ/gitea-mirror
+```
+
+#### Option 3: Pin to Specific Version
+
+```bash
+# 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 4: NixOS Configuration
+
+```nix
+{
+  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
+
+```bash
+# 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:
+```bash
+nix run github:RayLabsHQ/gitea-mirror/vX.Y.Z
+```
+
+### Updating Flake Lock
+
+The `flake.lock` file pins all dependencies. Update it periodically:
+
+```bash
+# 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
+
+1. **Check GitHub Actions:** Ensure CI is passing
+2. **Test locally:** `nix flake check`
+3. **Check flake.lock:** May need update if dependencies changed
+
+### Cachix Not Working
+
+1. **Verify cache exists:** https://gitea-mirror.cachix.org
+2. **Check GitHub secret:** `CACHIX_AUTH_TOKEN` is set
+3. **Review workflow logs:** Ensure build + push succeeded
+
+### Version Pinning Not Working
+
+```bash
+# 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
+
+```nix
+# 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:
+```nix
+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:
+
+```bash
+# On server
+nix-serve -p 8080
+
+# Behind nginx/caddy
+proxy_pass http://localhost:8080;
+```
+
+Users configure:
+```nix
+substituters = https://cache.example.com
+trusted-public-keys = YOUR_KEY
+```
+
+---
+
+## Comparison: Distribution Methods
+
+| Method | Setup Time | User Speed | Cost | Discoverability |
+|--------|-----------|------------|------|-----------------|
+| Direct GitHub | 0 min | Slow (build) | Free | Low |
+| Cachix | 5 min | Fast (binary) | Free (public) | Medium |
+| nixpkgs | Hours/days | Fast (binary) | Free | High |
+| Self-hosted | 30+ min | Fast (binary) | Server cost | Low |
+
+**Recommendation:** Start with **Direct GitHub** (works now), add **Cachix** for better UX (5 min), consider **nixpkgs** later for maximum reach.
+
+---
+
+## Resources
+
+- [Nix Flakes Documentation](https://nixos.wiki/wiki/Flakes)
+- [Cachix Documentation](https://docs.cachix.org/)
+- [nixpkgs Contributing Guide](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md)
+- [Nix Binary Cache Setup](https://nixos.org/manual/nix/stable/package-management/binary-cache-substituter.html)