LNBits NixOS Installation Guide

This guide shows how to install LNBits on a fresh NixOS system.

Quick Start (Recommended)

Add this to your NixOS configuration (/etc/nixos/configuration.nix):

{ config, lib, pkgs, ... }:

let
  lnbitsFlake = builtins.getFlake "github:lnbits/lnbits";
in
{
  imports = [
    # Import LNBits service module directly from GitHub
    "${lnbitsFlake}/nix/modules/lnbits-service.nix"
  ];

  # Enable flakes (required)
  nix.settings.experimental-features = [ "nix-command" "flakes" ];

  # Configure LNBits service
  services.lnbits = {
    enable = true;
    host = "0.0.0.0";        # Listen on all interfaces
    port = 5000;             # Default port
    openFirewall = true;     # Open firewall port automatically

    # Use package from the same flake (adjust system architecture as needed)
    package = lnbitsFlake.packages.x86_64-linux.lnbits;

    env = {
      LNBITS_ADMIN_UI = "true";
      # Configure your Lightning backend:
      # LNBITS_BACKEND_WALLET_CLASS = "LndRestWallet";
      # LND_REST_ENDPOINT = "https://localhost:8080";
      # LND_REST_CERT = "/path/to/tls.cert";
      # LND_REST_MACAROON = "/path/to/admin.macaroon";
    };
  };

  # Rebuild and switch
  # sudo nixos-rebuild switch
}

⚠️ System Architecture Note: The examples above use x86_64-linux. Replace this with your system architecture:

x86_64-linux - Intel/AMD 64-bit Linux

aarch64-linux - ARM 64-bit Linux (e.g., Raspberry Pi 4, Apple Silicon under Linux)

x86_64-darwin - Intel Mac

aarch64-darwin - Apple Silicon Mac

You can check your system with: nix eval --impure --raw --expr 'builtins.currentSystem'

Alternative: Using Your Own Flake

Create a flake.nix for your system configuration:

{
  description = "My NixOS configuration with LNBits";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";
    lnbits.url = "github:lnbits/lnbits";
  };

  outputs = { self, nixpkgs, lnbits }: {
    nixosConfigurations.myserver = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";  # Adjust architecture as needed
      modules = [
        ./hardware-configuration.nix
        {
          services.lnbits = {
            enable = true;
            host = "0.0.0.0";
            port = 5000;
            openFirewall = true;
            package = lnbits.packages.x86_64-linux.lnbits;  # Adjust architecture as needed
            env = {
              LNBITS_ADMIN_UI = "true";
              # Add your Lightning backend configuration
            };
          };
        }
      ];
    };
  };
}

Then deploy with:

sudo nixos-rebuild switch --flake .#myserver

Configuration Options

Basic Options

enable: Enable the LNBits service (default: false)
host: Host to bind to (default: "127.0.0.1")
port: Port to run on (default: 8231)
openFirewall: Automatically open firewall port (default: false)
user: User to run as (default: "lnbits")
group: Group to run as (default: "lnbits")
stateDir: State directory (default: "/var/lib/lnbits")

Environment Variables

Configure LNBits through the env option. Common variables:

services.lnbits.env = {
  # Admin UI
  LNBITS_ADMIN_UI = "true";

  # LND Backend Example:

  # LND
  LNBITS_BACKEND_WALLET_CLASS = "LndRestWallet";
  LND_REST_ENDPOINT = "https://localhost:8080";
  LND_REST_CERT = "/path/to/tls.cert";
  LND_REST_MACAROON = "/path/to/admin.macaroon";
};

See the LNBits documentation for all supported backends.

State Directory Structure

LNBits data is stored in /var/lib/lnbits (default) with this structure:

/var/lib/lnbits/
├── data/                       # Application data
│   ├── database.sqlite3        # Main database
│   ├── ext_<extension>.sqlite3 # Extension database
│   ├── images/                 # Uploaded images
│   ├── logs/                   # Log files
│   └── upgrades/               # Migration files
└── extensions/                 # Installed extensions

First Time Setup

Deploy the configuration:
```
sudo nixos-rebuild switch
```
Check service status:
```
systemctl status lnbits
```
Access the web interface:
```
http://your-server-ip:5000
```
Follow the first-time setup wizard to configure your Lightning backend and create your first wallet.
Bonus Add Reverse Proxy with generated SSL Cert

{
# Enable nginx
  services.nginx = {
    enable = true;

    virtualHosts."lnbits.mydomain.com" = {
      forceSSL = true;
      enableACME = true;
      locations."/" = {
        proxyPass = "http://127.0.0.1:5000";
        proxyWebsockets = true;
      };
    };
  };
}

Troubleshooting

Service won't start

# Check service logs
journalctl -u lnbits -f

# Check if port is available
ss -tlnp | grep 5000

Can't access web interface

Ensure openFirewall = true is set
Check if the port is correct: services.lnbits.port
Verify host binding: services.lnbits.host = "0.0.0.0"

README.md