Installation

Minimal Setup

To run a dummy Juxl-Hub-Auth using docker-compose create a docker-compose file containing

version: "3"
services:
  juxl_hub_auth:
    image: juxl/juxl_hub_auth
    environment:
      - HTTP_LIBRARY=dummy
      - LOG_LEVEL=DEBUG
      - CACHE_USERNAME=False
    ports:
      - "3333:443"

and run docker-compose up

This should output:

[2021-07-23 13:12:17 +0000] [1] [INFO] Starting gunicorn 20.1.0
[2021-07-23 13:12:17 +0000] [1] [INFO] Listening at: http://0.0.0.0:443 (1)
[2021-07-23 13:12:17 +0000] [1] [INFO] Using worker: sync
[2021-07-23 13:12:17 +0000] [8] [INFO] Booting worker with pid: 8
INFO:root:set LogLevel to DEBUG
INFO:root:Use DummyJupyterHub Interface
WARNING:root:Using a Dummy JupyterHub! No real authentication provided.
INFO:root:Use DummyLrs Interface
WARNING:root:Using a Dummy LRS! No statements are saved.

Because we set the HTTP_LIBRARY=dummy option, we do not need to configure any JupyterHub or LRS jet. The Juxl-Hub-Auth accepts all request and dismisses all received statements.

To ensure the Juxl-Hub-Auth is running and accessible, visit http://127.0.0.1:3333. The website should repond with Everything OK :D.

Now you can configure Juxl to send statements to the Juxl-Hub-Auth. To do that set the lrs-url in the juxl-config. For more information see the Juxl Configuration documentation.

{
  "lrs": {
    "url":"http://127.0.0.1:3333"
  }
}

Afterwards, we will see a short description of the inserted statements in the Juxl-Hub-Auth log

DEBUG:root:insert statement 'anonymous accessed JupyterLab'
DEBUG:root:insert statement 'anonymous opened Jupyter Notebook'

Advanced Setup

A more zadvanced configuration could look like the following.

version: "2.2"
services:
  # Redis for JupyterHub username caching
  redis:
    image: redis
  
  juxl_hub_auth:
    image: juxl/juxl_hub_auth
    ports:
      - "3333:443"
    # Mount ssl-certificates
    volumes:
      - ./ssl:/app/ssl
    environment:
      - LOG_LEVEL=DEBUG
      - JUPYTER_HUB_URL=https://my_jupyter_domain.com/hub
      - XAPI_LRS_AUTH_TOKEN=Basic MY_LRS_AUTH_TOKEN_ABCDEFGHIJKLMNOP
      - XAPI_LRS_URL=https://my_lrs_domain.com:8080/xAPI
    # Mounted certificate location
      - CERTFILE=./ssl/localhost.crt
      - KEYFILE=./ssl/localhost.key
    # Enable username caching
      - CACHE_USERNAME=True
    # Configure Redis database using docker-network
      - REDIS_HOST=redis
      - REDIS_PORT=6379
    depends_on:
      - redis

The following sections describe how to configure a JupyterHub instance for authentication, how to configure a LRS for statement-forwarding and other configurations.