nixos/modules/services/development/jupyterhub/default.nix

   1 { config, lib, pkgs, ... }:
   2 let
   3
   4   cfg = config.services.jupyterhub;
   5
   6   kernels = (pkgs.jupyter-kernel.create  {
   7     definitions = if cfg.kernels != null
   8       then cfg.kernels
   9       else  pkgs.jupyter-kernel.default;
  10   });
  11
  12   jupyterhubConfig = pkgs.writeText "jupyterhub_config.py" ''
  13     c.JupyterHub.bind_url = "http://${cfg.host}:${toString cfg.port}"
  14
  15     c.JupyterHub.authenticator_class = "${cfg.authentication}"
  16     c.JupyterHub.spawner_class = "${cfg.spawner}"
  17
  18     c.SystemdSpawner.default_url = '/lab'
  19     c.SystemdSpawner.cmd = "${cfg.jupyterlabEnv}/bin/jupyterhub-singleuser"
  20     c.SystemdSpawner.environment = {
  21       'JUPYTER_PATH': '${kernels}'
  22     }
  23
  24     ${cfg.extraConfig}
  25   '';
  26 in {
  27   meta.maintainers = with lib.maintainers; [ costrouc ];
  28
  29   options.services.jupyterhub = {
  30     enable = lib.mkEnableOption "Jupyterhub development server";
  31
  32     authentication = lib.mkOption {
  33       type = lib.types.str;
  34       default = "jupyterhub.auth.PAMAuthenticator";
  35       description = ''
  36         Jupyterhub authentication to use
  37
  38         There are many authenticators available including: oauth, pam,
  39         ldap, kerberos, etc.
  40       '';
  41     };
  42
  43     spawner = lib.mkOption {
  44       type = lib.types.str;
  45       default = "systemdspawner.SystemdSpawner";
  46       description = ''
  47         Jupyterhub spawner to use
  48
  49         There are many spawners available including: local process,
  50         systemd, docker, kubernetes, yarn, batch, etc.
  51       '';
  52     };
  53
  54     extraConfig = lib.mkOption {
  55       type = lib.types.lines;
  56       default = "";
  57       description = ''
  58         Extra contents appended to the jupyterhub configuration
  59
  60         Jupyterhub configuration is a normal python file using
  61         Traitlets. https://jupyterhub.readthedocs.io/en/stable/getting-started/config-basics.html. The
  62         base configuration of this module was designed to have sane
  63         defaults for configuration but you can override anything since
  64         this is a python file.
  65       '';
  66       example = ''
  67         c.SystemdSpawner.mem_limit = '8G'
  68         c.SystemdSpawner.cpu_limit = 2.0
  69       '';
  70     };
  71
  72     jupyterhubEnv = lib.mkOption {
  73       type = lib.types.package;
  74       default = pkgs.python3.withPackages (p: with p; [
  75         jupyterhub
  76         jupyterhub-systemdspawner
  77       ]);
  78       defaultText = lib.literalExpression ''
  79         pkgs.python3.withPackages (p: with p; [
  80           jupyterhub
  81           jupyterhub-systemdspawner
  82         ])
  83       '';
  84       description = ''
  85         Python environment to run jupyterhub
  86
  87         Customizing will affect the packages available in the hub and
  88         proxy. This will allow packages to be available for the
  89         extraConfig that you may need. This will not normally need to
  90         be changed.
  91       '';
  92     };
  93
  94     jupyterlabEnv = lib.mkOption {
  95       type = lib.types.package;
  96       default = pkgs.python3.withPackages (p: with p; [
  97         jupyterhub
  98         jupyterlab
  99       ]);
 100       defaultText = lib.literalExpression ''
 101         pkgs.python3.withPackages (p: with p; [
 102           jupyterhub
 103           jupyterlab
 104         ])
 105       '';
 106       description = ''
 107         Python environment to run jupyterlab
 108
 109         Customizing will affect the packages available in the
 110         jupyterlab server and the default kernel provided. This is the
 111         way to customize the jupyterlab extensions and jupyter
 112         notebook extensions. This will not normally need to
 113         be changed.
 114       '';
 115     };
 116
 117     kernels = lib.mkOption {
 118       type = lib.types.nullOr (lib.types.attrsOf(lib.types.submodule (import ../jupyter/kernel-options.nix {
 119         inherit lib pkgs;
 120       })));
 121
 122       default = null;
 123       example = lib.literalExpression ''
 124         {
 125           python3 = let
 126             env = (pkgs.python3.withPackages (pythonPackages: with pythonPackages; [
 127                     ipykernel
 128                     pandas
 129                     scikit-learn
 130                   ]));
 131           in {
 132             displayName = "Python 3 for machine learning";
 133             argv = [
 134               "''${env.interpreter}"
 135               "-m"
 136               "ipykernel_launcher"
 137               "-f"
 138               "{connection_file}"
 139             ];
 140             language = "python";
 141             logo32 = "''${env}/''${env.sitePackages}/ipykernel/resources/logo-32x32.png";
 142             logo64 = "''${env}/''${env.sitePackages}/ipykernel/resources/logo-64x64.png";
 143           };
 144         }
 145       '';
 146       description = ''
 147         Declarative kernel config
 148
 149         Kernels can be declared in any language that supports and has
 150         the required dependencies to communicate with a jupyter server.
 151         In python's case, it means that ipykernel package must always be
 152         included in the list of packages of the targeted environment.
 153       '';
 154     };
 155
 156     port = lib.mkOption {
 157       type = lib.types.port;
 158       default = 8000;
 159       description = ''
 160         Port number Jupyterhub will be listening on
 161       '';
 162     };
 163
 164     host = lib.mkOption {
 165       type = lib.types.str;
 166       default = "0.0.0.0";
 167       description = ''
 168         Bind IP JupyterHub will be listening on
 169       '';
 170     };
 171
 172     stateDirectory = lib.mkOption {
 173       type = lib.types.str;
 174       default = "jupyterhub";
 175       description = ''
 176         Directory for jupyterhub state (token + database)
 177       '';
 178     };
 179   };
 180
 181   config = lib.mkMerge [
 182     (lib.mkIf cfg.enable  {
 183       systemd.services.jupyterhub = {
 184         description = "Jupyterhub development server";
 185
 186         after = [ "network.target" ];
 187         wantedBy = [ "multi-user.target" ];
 188
 189         serviceConfig = {
 190           Restart = "always";
 191           ExecStart = "${cfg.jupyterhubEnv}/bin/jupyterhub --config ${jupyterhubConfig}";
 192           User = "root";
 193           StateDirectory = cfg.stateDirectory;
 194           WorkingDirectory = "/var/lib/${cfg.stateDirectory}";
 195         };
 196       };
 197     })
 198   ];
 199 }