From 4a8a7d686cf4a8ef65b9cee9443883950c722300 Mon Sep 17 00:00:00 2001 From: Pierre Penninckx Date: Thu, 30 Nov 2023 10:38:35 -0800 Subject: [PATCH] build docs and deploy to github pages --- .github/workflows/pages.yml | 69 ++++++++++++++++++++++++++++++ .github/workflows/test.yml | 7 ++- docs/man-pages.xml | 37 ++++++++++++++++ docs/manual.xml | 71 +++++++++++++++++++++++++++++++ flake.lock | 16 +++++++ flake.nix | 80 +++++++++++++++++++++++++---------- modules/blocks/authelia.nix | 18 +++++--- modules/blocks/postgresql.nix | 2 +- modules/blocks/vpn.nix | 2 +- 9 files changed, 272 insertions(+), 30 deletions(-) create mode 100644 .github/workflows/pages.yml create mode 100644 docs/man-pages.xml create mode 100644 docs/manual.xml diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 0000000..8b4fee3 --- /dev/null +++ b/.github/workflows/pages.yml @@ -0,0 +1,69 @@ +# Inspired from https://github.com/nix-community/nix-on-droid/blob/039379abeee67144d4094d80bbdaf183fb2eabe5/.github/workflows/docs.yml +name: Deploy docs + +on: + # Runs on pushes targeting the default branch + push: + branches: ["main"] + # TODO: needed ? + # schedule: + # - cron: 0 0 * * 1 + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + # Single deploy job since we're just deploying + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v3 + + - name: Install nix + uses: cachix/install-nix-action@v20 + + - name: Build docs + run: | + nix \ + --print-build-logs \ + --option keep-going true \ + --show-trace \ + build .#manualHtml + + # see https://github.com/actions/deploy-pages/issues/58 + cp \ + --recursive \ + --dereference \ + --no-preserve=mode,ownership \ + result/share/doc/selfhostblocks \ + public + + - name: Setup Pages + uses: actions/configure-pages@v3 + + - name: Upload artifact + uses: actions/upload-pages-artifact@v1 + with: + path: ./public + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v2 diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 7876779..1c2009b 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -14,4 +14,9 @@ jobs: with: name: selfhostblocks authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}' - - run: nix flake check -L + - run: | + nix flake \ + --print-build-logs \ + --option keep-going true \ + --show-trace \ + check diff --git a/docs/man-pages.xml b/docs/man-pages.xml new file mode 100644 index 0000000..cea8cb4 --- /dev/null +++ b/docs/man-pages.xml @@ -0,0 +1,37 @@ + + + Self Host Blocks Reference Pages + + Self Host Blocks contributors + + 2022Self Host Blocks contributors + + + + + selfhostblocks-options + 5 + Self Host Blocks + + + selfhostblocks-options + Self Host Blocks configuration specification + + + Description + + This contains the module options available for Self Host Blocks. + + + + Options + + You can use the following options after importing Self Host Blocks as a flake input, then + importing the default module for your system. + + + + + diff --git a/docs/manual.xml b/docs/manual.xml new file mode 100644 index 0000000..4bc81e1 --- /dev/null +++ b/docs/manual.xml @@ -0,0 +1,71 @@ + + + + Self Host Blocks manual + + + Preface + + Complete manual for Self Host Blocks, the building blocks for self-hosting with battery included. + + + If you encounter problems or bugs then please report them on the + issue tracker. + + + + + Self Host Blocks configuration options +
+ Usage + + + + + To use these options, import Self Host Blocks as a flake input, then import the default module for your system. + +{ + inputs = { + nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"; + sops-nix.url = "github:Mic92/sops-nix"; + + shb.url = "github:ibizaman/selfhostblocks"; + shb.inputs.nixpkgs.follows = "nixpkgs"; + shb.inputs.sops-nix.follows = "sops-nix"; + }; + + outputs = { self, nixpkgs, shb }: { + + nixosConfigurations.machine = nixpkgs.lib.nixosSystem { + system = "x86_64-linux"; + modules = [ + shb.nixosModules.x86_64-linux.default + ./machine.nix + ]; + }; + + }; +} + + +
+
+ Options + + +
+ + diff --git a/flake.lock b/flake.lock index 982099d..66e4a93 100644 --- a/flake.lock +++ b/flake.lock @@ -81,11 +81,27 @@ "type": "github" } }, + "nmd": { + "locked": { + "lastModified": 1672240039, + "narHash": "sha256-lmct89fYDOr9YdWVvdJgklv/7WttRSiDAkoi2cvvAW4=", + "owner": "gvolpe", + "repo": "nmd", + "rev": "a59e840c2e8d54415485f349760e1350cb80d911", + "type": "github" + }, + "original": { + "owner": "gvolpe", + "repo": "nmd", + "type": "github" + } + }, "root": { "inputs": { "flake-utils": "flake-utils", "nix-flake-tests": "nix-flake-tests", "nixpkgs": "nixpkgs", + "nmd": "nmd", "sops-nix": "sops-nix" } }, diff --git a/flake.nix b/flake.nix index 895028d..8c53fc7 100644 --- a/flake.nix +++ b/flake.nix @@ -6,36 +6,72 @@ sops-nix.url = "github:Mic92/sops-nix"; nix-flake-tests.url = "github:antifuchs/nix-flake-tests"; flake-utils.url = "github:numtide/flake-utils"; + nmd.url = "github:gvolpe/nmd"; }; - outputs = { nixpkgs, nix-flake-tests, flake-utils, ... }: flake-utils.lib.eachDefaultSystem (system: + outputs = { nixpkgs, nix-flake-tests, flake-utils, nmd, ... }: flake-utils.lib.eachDefaultSystem (system: let - pkgs = nixpkgs.legacyPackages.${system}; + pkgs = import nixpkgs { + inherit system; + overlays = [ nmd.overlays.default ]; + }; + + allModules = [ + modules/blocks/authelia.nix + modules/blocks/backup.nix + modules/blocks/davfs.nix + modules/blocks/ldap.nix + modules/blocks/monitoring.nix + modules/blocks/nginx.nix + modules/blocks/postgresql.nix + modules/blocks/ssl.nix + modules/blocks/tinyproxy.nix + modules/blocks/vpn.nix + + modules/services/arr.nix + modules/services/deluge.nix + modules/services/hledger.nix + modules/services/home-assistant.nix + modules/services/jellyfin.nix + modules/services/nextcloud-server.nix + modules/services/vaultwarden.nix + ]; in { nixosModules.default = { config, ... }: { - imports = [ - modules/blocks/authelia.nix - modules/blocks/backup.nix - modules/blocks/davfs.nix - modules/blocks/ldap.nix - modules/blocks/monitoring.nix - modules/blocks/nginx.nix - modules/blocks/postgresql.nix - modules/blocks/ssl.nix - modules/blocks/tinyproxy.nix - modules/blocks/vpn.nix - - modules/services/arr.nix - modules/services/deluge.nix - modules/services/hledger.nix - modules/services/home-assistant.nix - modules/services/jellyfin.nix - modules/services/nextcloud-server.nix - modules/services/vaultwarden.nix - ]; + imports = allModules; }; + # Inspiration from https://github.com/nix-community/nix-on-droid/blob/039379abeee67144d4094d80bbdaf183fb2eabe5/docs/default.nix#L22 + packages.manualHtml = let + setupModule = { + _module.args.pkgs = pkgs.lib.mkForce (pkgs.nmd.scrubDerivations "pkgs" pkgs); + _module.check = false; + }; + + modulesDocs = pkgs.nmd.buildModulesDocs { + modules = allModules ++ [ setupModule ]; + moduleRootPaths = [ ../. ]; + mkModuleUrl = path: "https://myproject.foo/${path}"; + channelName = "selfhostblocks"; + docBook = { id = "selfhostblocks-options"; optionIdPrefix = "shb-opt"; }; + }; + + manual = pkgs.nmd.buildDocBookDocs { + pathName = "SelfHostBlocks"; + modulesDocs = [ modulesDocs ]; + documentsDirectory = ./docs; + chunkToc = '' + + + + + + ''; + }; + in + manual.html; + checks = let importFiles = files: diff --git a/modules/blocks/authelia.nix b/modules/blocks/authelia.nix index 36b005e..ef1b112 100644 --- a/modules/blocks/authelia.nix +++ b/modules/blocks/authelia.nix @@ -14,7 +14,7 @@ in subdomain = lib.mkOption { type = lib.types.str; description = "Subdomain under which Authelia will be served."; - example = "ha"; + example = "auth"; }; domain = lib.mkOption { @@ -36,9 +36,17 @@ in }; autheliaUser = lib.mkOption { - type = lib.types.str; - description = "System user for this Authelia instance"; - default = "authelia_" + builtins.replaceStrings ["-" "."] ["_" "_"] fqdn; + type = lib.types.nullOr lib.types.str; + description = ''System user for this Authelia instance. + +If set to null, defaults to: + +"authelia_" + + (builtins.replaceStrings ["-" "."] ["_" "_"] + ''${shb.authelia.subdomain}.''${shb.authelia.domain}") + +''; + default = null; }; secrets = lib.mkOption { @@ -112,7 +120,7 @@ in services.authelia.instances.${fqdn} = { enable = true; - user = cfg.autheliaUser; + user = cfg.autheliaUser or "authelia_" + builtins.replaceStrings ["-" "."] ["_" "_"] fqdn; secrets = { inherit (cfg.secrets) jwtSecretFile storageEncryptionKeyFile; diff --git a/modules/blocks/postgresql.nix b/modules/blocks/postgresql.nix index 86b400c..55039e3 100644 --- a/modules/blocks/postgresql.nix +++ b/modules/blocks/postgresql.nix @@ -6,7 +6,7 @@ in options.shb.postgresql = { debug = lib.mkOption { type = lib.types.bool; - description = lib.mdDocs '' + description = lib.mdDoc '' Enable debugging options. Currently enables shared_preload_libraries = "auto_explain, pg_stat_statements" diff --git a/modules/blocks/vpn.nix b/modules/blocks/vpn.nix index 19e2b93..96c91ce 100644 --- a/modules/blocks/vpn.nix +++ b/modules/blocks/vpn.nix @@ -211,7 +211,7 @@ in provider = lib.mkOption { description = lib.mdDoc "VPN provider, if given uses ready-made configuration."; - type = lib.types.nullOf (lib.types.enum [ "nordvpn" ]); + type = lib.types.nullOr (lib.types.enum [ "nordvpn" ]); default = null; };