improve public documentation

README.md

@@ -57,7 +57,8 @@ To integrate with GitHub:
 1. **GitHub App**: Set up a GitHub app for Buildbot to enable GitHub user
    authentication on the Buildbot dashboard.
 2. **OAuth Credentials**: After installing the app, generate OAuth credentials
-   and configure them in the buildbot-nix NixOS module.
+   and configure them in the buildbot-nix NixOS module. Set the callback url to
+   `https://<your-domain>/auth/login`.
 3. **GitHub Token**: Obtain a GitHub token with `admin:repo_hook` and `repo`
    permissions. For GitHub organizations, it's advisable to create a separate
    GitHub user for managing repository webhooks.

examples/default.nix

@@ -15,61 +15,47 @@ let
   inherit (lib) nixosSystem;
 in
 {
+  # This runs both master and worker on the same machine.
+  # As the actual build is offloaded with remote builder,
+  # this also works well for production setups.
+  "example-master-worker-combined-${system}" = nixosSystem {
+    inherit system;
+    modules = [
+      dummy
+      buildbot-nix.nixosModules.buildbot-master
+      buildbot-nix.nixosModules.buildbot-worker
+      ./master.nix
+      ./worker.nix
+    ];
+  };
   "example-master-${system}" = nixosSystem {
     inherit system;
     modules = [
       dummy
-      ({ pkgs, ... }: {
-        services.buildbot-nix.master = {
-          enable = true;
-          domain = "buildbot2.thalheim.io";
-          workersFile = pkgs.writeText "workers.json" ''
-            [
-              { "name": "eve", "pass": "XXXXXXXXXXXXXXXXXXXX", "cores": 16 }
-            ]
-          '';
-          github = {
-            tokenFile = pkgs.writeText "github-token" "ghp_000000000000000000000000000000000000";
-            webhookSecretFile = pkgs.writeText "webhookSecret" "00000000000000000000";
-            oauthSecretFile = pkgs.writeText "oauthSecret" "ffffffffffffffffffffffffffffffffffffffff";
-            oauthId = "aaaaaaaaaaaaaaaaaaaa";
-            user = "mic92-buildbot";
-            admins = [ "Mic92" ];
-            # All github projects with this topic will be added to buildbot.
-            # One can trigger a project scan by visiting the Builds -> Builders page and looking for the "reload-github-project" builder.
-            # This builder has a "Update Github Projects" button that everyone in the github organization can use.
-            topic = "buildbot-mic92";
-          };
-          # optional expose latest store path as text file
-          # outputsPath = "/var/www/buildbot/nix-outputs";
-
-          # optional nix-eval-jobs settings
-          # evalWorkerCount = 8; # limit number of concurrent evaluations
-          # evalMaxMemorySize = "2048"; # limit memory usage per evaluation
-
-          # optional cachix
-          #cachix = {
-          #  name = "my-cachix";
-          #  # One of the following is required:
-          #  signingKey = "/var/lib/secrets/cachix-key";
-          #  authToken = "/var/lib/secrets/cachix-token";
-          #};
-        };
-      })
       buildbot-nix.nixosModules.buildbot-master
+      ./master.nix
+      # When master and worker run on different machines,
+      # we need to configure the master to listen on a public address.
+      # Also check out the buildbot upstream documentation on the master-worker protocol,
+      # including tls encryption
+      {
+        # exposes the master build protocol on port 9989
+        services.buildbot-master.extraConfig = ''
+          c["protocols"] = {"pb": {"port": "tcp:9989:interface=\\:\\:"}}
+        '';
+        networking.firewall.allowedTCPPorts = [ 9989 ];
+      }
     ];
   };
+
   "example-worker-${system}" = nixosSystem {
     inherit system;
     modules = [
       dummy
-      ({ pkgs, ... }: {
-        services.buildbot-nix.worker = {
-          enable = true;
-          workerPasswordFile = pkgs.writeText "worker-password-file" "";
-        };
-      })
       buildbot-nix.nixosModules.buildbot-worker
+      ./worker.nix
+      # Connects to a master on the ipv6 address 2a09:80c0:102::1
+      { services.buildbot-nix.worker.masterUrl = ''tcp:host=2a09\:80c0\:102\:\:1:port=9989''; }
     ];
   };
 }

examples/master.nix

@@ -0,0 +1,59 @@
+{ pkgs, ... }:
+{
+  services.buildbot-nix.master = {
+    enable = true;
+    # Domain name under which the buildbot frontend is reachable
+    domain = "buildbot2.thalheim.io";
+    # The workers file configures credentials for the buildbot workers to connect to the master.
+    # "name" is the configured worker name in services.buildbot-nix.worker.name of a worker
+    # (defaults to the hostname of the machine)
+    # "pass" is the password for the worker configured in `services.buildbot-nix.worker.workerPasswordFile`
+    # "cores" is the number of cpu cores the worker has.
+    # The number must match as otherwise potentially not enought buildbot-workers are created.
+    workersFile = pkgs.writeText "workers.json" ''
+      [
+        { "name": "eve", "pass": "XXXXXXXXXXXXXXXXXXXX", "cores": 16 }
+      ]
+    '';
+    github = {
+      # Github user used as a CI identity
+      user = "mic92-buildbot";
+      # Github token of the same user
+      tokenFile = pkgs.writeText "github-token" "ghp_000000000000000000000000000000000000";
+      # A random secret used to verify incoming webhooks from GitHub
+      # buildbot-nix will set up a webhook for each project in the organization
+      webhookSecretFile = pkgs.writeText "webhookSecret" "00000000000000000000";
+      # Either create a GitHub app or an OAuth app
+      # After creating the app, press "Generate a new client secret" and fill in the client ID and secret below
+      oauthId = "aaaaaaaaaaaaaaaaaaaa";
+      oauthSecretFile = pkgs.writeText "oauthSecret" "ffffffffffffffffffffffffffffffffffffffff";
+      # Users in this list will be able to reload the project list.
+      # All other user in the organization will be able to restart builds or evaluations.
+      admins = [ "Mic92" ];
+      # All github projects with this topic will be added to buildbot.
+      # One can trigger a project scan by visiting the Builds -> Builders page and looking for the "reload-github-project" builder.
+      # This builder has a "Update Github Projects" button that everyone in the github organization can use.
+      topic = "buildbot-mic92";
+    };
+    # optional expose latest store path as text file
+    # outputsPath = "/var/www/buildbot/nix-outputs";
+
+    # optional nix-eval-jobs settings
+    # evalWorkerCount = 8; # limit number of concurrent evaluations
+    # evalMaxMemorySize = "2048"; # limit memory usage per evaluation
+
+    # optional cachix
+    #cachix = {
+    #  name = "my-cachix";
+    #  # One of the following is required:
+    #  signingKey = "/var/lib/secrets/cachix-key";
+    #  authToken = "/var/lib/secrets/cachix-token";
+    #};
+  };
+
+  # Optional: Enable acme/TLS in nginx (recommended)
+  #services.nginx.virtualHosts.${config.services.buildbot-nix.master.domain} = {
+  #  forceSSL = true;
+  #  useACME = true;
+  #};
+}

examples/worker.nix

@@ -0,0 +1,7 @@
+{ pkgs, ... }:
+{
+  services.buildbot-nix.worker = {
+    enable = true;
+    workerPasswordFile = pkgs.writeText "worker-password-file" "XXXXXXXXXXXXXXXXXXXX";
+  };
+}