nixos/jellystat: init module

nixos/doc/manual/redirects.json

@@ -1,4 +1,28 @@
 {
+  "module-services-jellystat": [
+    "index.html#module-services-jellystat"
+  ],
+  "module-services-jellystat-configuration": [
+    "index.html#module-services-jellystat-configuration"
+  ],
+  "module-services-jellystat-database": [
+    "index.html#module-services-jellystat-database"
+  ],
+  "module-services-jellystat-environment": [
+    "index.html#module-services-jellystat-environment"
+  ],
+  "module-services-jellystat-geolite": [
+    "index.html#module-services-jellystat-geolite"
+  ],
+  "module-services-jellystat-paths": [
+    "index.html#module-services-jellystat-paths"
+  ],
+  "module-services-jellystat-quickstart": [
+    "index.html#module-services-jellystat-quickstart"
+  ],
+  "module-services-jellystat-troubleshooting": [
+    "index.html#module-services-jellystat-troubleshooting"
+  ],
   "module-services-portmaster": [
     "index.html#module-services-portmaster"
   ],

nixos/doc/manual/release-notes/rl-2611.section.md

@@ -78,6 +78,8 @@
 
 - [ioquake3](https://ioquake3.org), a open-source port of the 3D action shooter Quake 3 Arena. Available as [programs.ioquake3](#opt-programs.ioquake3.enable).
 
+- [Jellystat](https://github.com/CyferShepard/Jellystat), a free and open source Statistics App for Jellyfin [services.jellystat](#opt-services.jellystat.enable).
+
 - [Matrix Authentication Service](https://github.com/element-hq/matrix-authentication-service) is an OAuth2.0 and OpenID Connect provider for Matrix homeservers (such as Synapse). It replaces standard password authentication with modern OpenID Connect flows, and can delegate authentication to upstream OIDC providers. Available as [services.matrix-authentication-service](#opt-services.matrix-authentication-service.enable).
 
 - [stash-clipboard](https://github.com/NotAShelf/stash), a Wayland clipboard "manager" with fast persistent history and multi-media support. Available as [services.stash-clipboard](#opt-services.stash-clipboard.enable).

nixos/modules/module-list.nix

@@ -920,6 +920,7 @@
   ./services/misc/irkerd.nix
   ./services/misc/jackett.nix
   ./services/misc/jellyfin.nix
+  ./services/misc/jellystat.nix
   ./services/misc/kiwix-serve.nix
   ./services/misc/klipper.nix
   ./services/misc/languagetool.nix

nixos/modules/services/misc/jellystat.md

@@ -0,0 +1,171 @@
+# Jellystat {#module-services-jellystat}
+
+[Jellystat](https://github.com/CyferShepard/Jellystat) is a free and open source statistics and analytics application for Jellyfin servers.
+
+The NixOS module manages the Jellystat service, optional PostgreSQL provisioning, runtime directories, and secret injection through files rather than environment variables stored in the Nix store.
+
+## Quickstart {#module-services-jellystat-quickstart}
+
+A minimal configuration looks like this:
+
+```nix
+{
+  services.jellystat = {
+    enable = true;
+    openFirewall = true;
+
+    settings = {
+      jwtSecretFile = "jwt/secret/file/location";
+
+      database = {
+        host = "127.0.0.1";
+        passwordFile = "db/passsword/file/location";
+      };
+    };
+  };
+}
+```
+
+If you want NixOS to provision a local PostgreSQL database automatically:
+
+```nix
+{
+  services.jellystat = {
+    enable = true;
+
+    settings = {
+      jwtSecretFile = "jwt/secret/file/location";
+
+      database = {
+        createLocally = true;
+        passwordFile = "db/passsword/file/location";
+      };
+    };
+  };
+}
+```
+
+## Configuration {#module-services-jellystat-configuration}
+
+Jellystat is configured primarily through the {option}`services.jellystat.settings` option set, which maps directly onto the environment variables expected by the upstream application.
+
+The module requires both:
+
+- {option}`services.jellystat.settings.jwtSecretFile`
+- {option}`services.jellystat.settings.database.passwordFile`
+
+If either option is omitted, evaluation will fail with an assertion error.
+
+Secrets are read at service startup and are not embedded into the Nix store. This makes the module suitable for use with secret-management tools such as SOPS-Nix or agenix.
+
+::: {.note}
+Values supplied through {option}`services.jellystat.settings.environment` are merged into the generated environment after the module's built-in defaults. This can be used to expose upstream environment variables that are not yet available as dedicated NixOS options.
+:::
+
+The {option}`services.jellystat.settings.baseUrl` option should be adjusted when Jellystat is served from a subpath behind a reverse proxy.
+
+For example, to serve Jellystat from {file}`https://example.com/jellystat`:
+
+```nix
+{
+  services.jellystat.settings.baseUrl = "/jellystat";
+}
+```
+
+### Database Provisioning {#module-services-jellystat-database}
+
+When {option}`services.jellystat.settings.database.createLocally` is enabled, the module configures the NixOS PostgreSQL service and creates:
+
+- A PostgreSQL database named by {option}`services.jellystat.settings.database.name`
+- A PostgreSQL user named by {option}`services.jellystat.settings.database.user`
+
+The Jellystat service is automatically ordered after PostgreSQL and will wait for the database service before starting.
+
+::: {.warning}
+Enabling {option}`services.jellystat.settings.database.createLocally` does not automatically generate a database password. A password must still be supplied via {option}`services.jellystat.settings.database.passwordFile`.
+:::
+
+If {option}`services.jellystat.settings.database.createLocally` is disabled, the module assumes an external PostgreSQL server is available and reachable.
+
+### GeoLite Integration {#module-services-jellystat-geolite}
+
+Jellystat supports GeoLite lookups for geographic statistics.
+
+To enable GeoLite support, configure both:
+
+- {option}`services.jellystat.settings.geolite.accountId`
+- {option}`services.jellystat.settings.geolite.licenseKeyFile`
+
+If either option is omitted, GeoLite functionality remains disabled.
+
+### Additional Environment Variables {#module-services-jellystat-environment}
+
+The {option}`services.jellystat.settings.environment` option can be used to pass additional environment variables to Jellystat that are not exposed as dedicated NixOS options.
+
+Variables specified here are merged with the environment generated by the module. Values in `environment` take precedence over the corresponding module-generated variables.
+
+For example:
+
+```nix
+{
+  services.jellystat.settings.environment = {
+    JS_SOME_UPSTREAM_OPTION = "value";
+  };
+}
+```
+
+This can also be used to override a value provided by a dedicated module option:
+
+```nix
+{
+  services.jellystat.settings = {
+    timeZone = "Australia/Brisbane";
+
+    environment = {
+      TZ = "Etc/UTC";
+    };
+  };
+}
+```
+
+In this example, TZ will be Etc/UTC, because values in {option}`services.jellystat.settings.environment` take precedence.
+
+::: {.warning}
+Prefer the dedicated NixOS options when one exists. The environment option is primarily intended for Jellystat environment variables that are not otherwise exposed by the module.
+:::
+
+## Sockets and Directories {#module-services-jellystat-paths}
+
+By default, Jellystat stores its persistent state under:
+
+- State directory: {file}`/var/lib/jellystat`
+- Backup directory: {file}`/var/lib/jellystat/backups`
+- Environment directory: {file}`/var/lib/jellystat/env`
+
+The state directory can be changed with {option}`services.jellystat.dataDir`.
+
+The service listens on:
+
+- Address: {option}`services.jellystat.settings.listenAddress`
+- Port: {option}`services.jellystat.settings.port`
+
+Firewall access can be enabled using {option}`services.jellystat.openFirewall`.
+
+## Troubleshooting {#module-services-jellystat-troubleshooting}
+
+Check service status and logs with:
+
+```ShellSession
+systemctl status jellystat.service
+journalctl -u jellystat.service
+```
+
+Verify that the configured secret files exist and are readable by the service before starting Jellystat.
+
+If database connection errors occur, confirm that:
+
+- The PostgreSQL server is reachable.
+- The values of {option}`services.jellystat.settings.database.host` and {option}`services.jellystat.settings.database.port` are correct.
+- The password supplied through {option}`services.jellystat.settings.database.passwordFile` matches the configured PostgreSQL user.
+
+For additional configuration options and application-specific behavior, see the upstream Jellystat documentation.