lightscale/nixos/README.md

NixOS Modules

This flake exports two modules:

• lightscale.nixosModules.lightscale-server
• lightscale.nixosModules.lightscale-client

Server example

{
  imports = [
    lightscale.nixosModules.lightscale-server
  ];

  services.lightscale-server = {
    enable = true;
    listen = "0.0.0.0:8080";
    stateFile = "/var/lib/lightscale-server/state.json";
    # Or use dbUrl / dbUrlFile for shared DB:
    # dbUrlFile = "/run/secrets/lightscale-db-url";
    openFirewall = true;
    firewallTCPPorts = [ 8080 ];
    # Optional relay advertisement/listeners:
    # streamRelayServers = [ "vpn.example.com:443" ];
    # streamRelayListen = "0.0.0.0:443";
    # udpRelayServers = [ "vpn.example.com:3478" ];
    # udpRelayListen = "0.0.0.0:3478";
    # Optional inter-server relay mesh (mTLS):
    # meshServerId = "vpn-a.example.com";
    # meshListen = "0.0.0.0:7443";
    # meshPeers = [ "vpn-b.example.com=10.0.0.12:7443" ];
    # meshCaCert = "/run/secrets/lightscale-mesh-ca.pem";
    # meshCert = "/run/secrets/lightscale-mesh-vpn-a.pem";
    # meshKey = "/run/secrets/lightscale-mesh-vpn-a-key.pem";
    # meshMaxHops = 4;
    environmentFiles = [ "/run/secrets/lightscale-server.env" ];
  };
}

/run/secrets/lightscale-server.env should include:

LIGHTSCALE_ADMIN_TOKEN=replace-me

Optional DB URL secret file example:

postgres://lightscale:secret@db.internal/lightscale?sslmode=require

Client agent example

{
  imports = [
    lightscale.nixosModules.lightscale-client
  ];

  services.lightscale-client = {
    enable = true;
    profile = "prod";
    controlUrls = [ "https://vpn.example.com:8080" ];
    stateDir = "/var/lib/lightscale-client";
    listenPort = 51820;
    applyRoutes = true;
    streamRelay = true;
    relayReprobeAfter = 60;
    openFirewall = true;
    # listenPort is opened automatically when openFirewall=true.
    environmentFiles = [ "/run/secrets/lightscale-client.env" ];
    autoRegister = true;
    enrollmentTokenFile = "/run/secrets/lightscale-enroll-token";
    registerNodeName = "host-01";
  };
}

Optional secret env file for admin endpoints:

LIGHTSCALE_ADMIN_TOKEN=replace-me

Bootstrap note

lightscale-client.service starts only after state.json exists for the profile.

When autoRegister = true, a one-shot service registers the node once and then the agent runs.

If you keep autoRegister = false, run registration manually once (same profile/state directory):

lightscale-client --profile prod --state-dir /var/lib/lightscale-client/prod \
  --control-url https://vpn.example.com:8080 register <enrollment-token>