updated docs

NIX.md

@@ -4,23 +4,25 @@
 
 ```bash
 # Just run it - zero configuration needed!
-nix run .#gitea-mirror
+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
 ```bash
-nix run .#gitea-mirror
+nix run --extra-experimental-features 'nix-command flakes' .#gitea-mirror
 ```
 
 ### 2. Install to Profile
 ```bash
-nix profile install .#gitea-mirror
+nix profile install --extra-experimental-features 'nix-command flakes' .#gitea-mirror
 gitea-mirror
 ```
 
@@ -40,9 +42,18 @@ gitea-mirror
 
 ### 4. Development
 ```bash
-nix develop
+nix develop --extra-experimental-features 'nix-command flakes'
 # or
-direnv allow
+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
 ```
 
 ---
@@ -68,10 +79,11 @@ gitea-mirror-db init      # Initialize database
 gitea-mirror-db check     # Health check
 gitea-mirror-db fix       # Fix issues
 
-# Development
+# 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
 ```
 
 ---

README.md

@@ -156,10 +156,14 @@ Zero-configuration deployment with Nix:
 
 ```bash
 # Run immediately - no setup needed!
-nix run github:RayLabsHQ/gitea-mirror
+nix run --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
+
+# Or build and run locally
+nix build --extra-experimental-features 'nix-command flakes'
+./result/bin/gitea-mirror
 
 # Or install to profile
-nix profile install github:RayLabsHQ/gitea-mirror
+nix profile install --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
 gitea-mirror
 ```
 

docs/NIX_DEPLOYMENT.md

@@ -4,24 +4,31 @@ This guide covers deploying Gitea Mirror using Nix flakes. The Nix deployment fo
 
 ## Prerequisites
 
-- Nix with flakes enabled (Nix 2.4+)
+- Nix 2.4+ installed
 - For NixOS module: NixOS 23.05+
 
-To enable flakes, add to `/etc/nix/nix.conf` or `~/.config/nix/nix.conf`:
+### Enable Flakes (Recommended)
+
+To enable flakes permanently and avoid typing flags, add to `/etc/nix/nix.conf` or `~/.config/nix/nix.conf`:
 ```
 experimental-features = nix-command flakes
 ```
 
+**Note:** If you don't enable flakes globally, add `--extra-experimental-features 'nix-command flakes'` to all nix commands shown below.
+
 ## Quick Start (Zero Configuration!)
 
 ### Run Immediately - No Setup Required
 
 ```bash
-# Run directly from the flake
+# Run directly from the flake (local)
-nix run .#gitea-mirror
+nix run --extra-experimental-features 'nix-command flakes' .#gitea-mirror
 
 # Or from GitHub (once published)
-nix run github:RayLabsHQ/gitea-mirror
+nix run --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
+
+# If you have flakes enabled globally, simply:
+nix run .#gitea-mirror
 ```
 
 That's it! On first run:
@@ -36,9 +43,9 @@ Everything else (GitHub credentials, Gitea settings, mirror options) is configur
 
 ```bash
 # Enter development shell with all dependencies
-nix develop
+nix develop --extra-experimental-features 'nix-command flakes'
 
-# Or use direnv for automatic environment loading
+# Or use direnv for automatic environment loading (handles flags automatically)
 echo "use flake" > .envrc
 direnv allow
 ```
@@ -47,13 +54,13 @@ direnv allow
 
 ```bash
 # Build the package
-nix build
+nix build --extra-experimental-features 'nix-command flakes'
 
 # Run the built package
 ./result/bin/gitea-mirror
 
 # Install to your profile
-nix profile install .#gitea-mirror
+nix profile install --extra-experimental-features 'nix-command flakes' .#gitea-mirror
 ```
 
 ## What Happens on First Run?
@@ -312,7 +319,7 @@ dockerImage = pkgs.dockerTools.buildLayeredImage {
 
 Build and load:
 ```bash
-nix build .#dockerImage
+nix build --extra-experimental-features 'nix-command flakes' .#dockerImage
 docker load < result
 docker run -p 4321:4321 -v gitea-mirror-data:/data gitea-mirror:latest
 ```
@@ -384,22 +391,22 @@ sudo journalctl -u gitea-mirror -f --since "5 minutes ago"
 ### Standalone Installation
 ```bash
 # Update flake lock
-nix flake update
+nix flake update --extra-experimental-features 'nix-command flakes'
 
 # Rebuild
-nix build
+nix build --extra-experimental-features 'nix-command flakes'
 
 # Or update profile
-nix profile upgrade gitea-mirror
+nix profile upgrade --extra-experimental-features 'nix-command flakes' gitea-mirror
 ```
 
 ### NixOS
 ```bash
 # Update input
-sudo nix flake lock --update-input gitea-mirror
+sudo nix flake lock --update-input gitea-mirror --extra-experimental-features 'nix-command flakes'
 
 # Rebuild system
-sudo nixos-rebuild switch
+sudo nixos-rebuild switch --flake .#your-hostname
 ```
 
 ## Migration from Docker
@@ -464,6 +471,7 @@ jobs:
         authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'
     - run: nix build
     - run: nix flake check
+    # Note: GitHub Actions runner usually has flakes enabled by install-nix-action
 ```
 
 ## Resources

flake.lock

@@ -0,0 +1,61 @@
+{
+  "nodes": {
+    "flake-utils": {
+      "inputs": {
+        "systems": "systems"
+      },
+      "locked": {
+        "lastModified": 1731533236,
+        "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1761672384,
+        "narHash": "sha256-o9KF3DJL7g7iYMZq9SWgfS1BFlNbsm6xplRjVlOCkXI=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "08dacfca559e1d7da38f3cf05f1f45ee9bfd213c",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "flake-utils": "flake-utils",
+        "nixpkgs": "nixpkgs"
+      }
+    },
+    "systems": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}