From e9f5b4a4108454b3cc667ad9395b1e12915ad3e7 Mon Sep 17 00:00:00 2001
From: Jack Hadrill <jack@hadrill.co.uk>
Date: Wed, 24 Aug 2022 23:35:11 +0000
Subject: [PATCH] Update documentation and variable names (breaking).

---
 Dockerfile    |  5 ++---
 README.md     | 58 ++++++++++++++++++++++++++++++++++++++++++++++-----
 director.conf |  4 ++--
 3 files changed, 57 insertions(+), 10 deletions(-)

diff --git a/Dockerfile b/Dockerfile
index 9aceb4a..407415d 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,9 +1,8 @@
 FROM nginx:alpine
 
-ENV LISTEN_PORT="80"
+ENV SPAWNER_HOST="container-spawner"
 ENV CONTAINER_PREFIX="vscode"
-ENV CONTAINER_PORT="80"
-ENV SPAWNER_URL="http://container-spawner"
+ENV CONTAINER_PORT="8080"
 
 RUN rm -rf /etc/nginx/conf.d/default.conf
 COPY director.conf /etc/nginx/templates/director.conf.template
diff --git a/README.md b/README.md
index e7ec5dc..ec011c7 100644
--- a/README.md
+++ b/README.md
@@ -6,17 +6,65 @@ A tool to proxy an HTTP backend, and failover to a "container spawner" if the ba
 
 ## Usage
 
+This container listens on port 8080, and relies on [**OAuth2 Proxy**](https://github.com/oauth2-proxy/oauth2-proxy) for authentication.
+
+Environment variables:
+| Variable name | Example value | Description |
+| ------------- | ------------- | ----------- |
+| SPAWNER_HOST | `container-spawner` | The hostname of the [**Container Spawner**](https://git.jacknet.io/jackhadrill/container-spawner), responsible for spawning new containers. |
+| CONTAINER_HOST_PREFIX | `vscode` | A prefix used by the [**Container Spawner**](https://git.jacknet.io/jackhadrill/container-spawner) which, when prepended to the user's username, represents the user's bespoke container hostname.<br />Example: `vscode-jack` |
+| CONTAINER_PORT | `8080` | The port number used by the spawned container for incoming connections. |
+
+An example `docker-compose.yml` is shown below.
+
 ```yml
 version: '3'
 services:
-  ...
+  auth:
+    image: bitnami/oauth2-proxy:latest
+    restart: always
+    networks:
+      - proxy
+      - backend
+    command:
+      - '--upstream=http://container-director:8080/'
+      - '--http-address=0.0.0.0:4180'
+      - '--skip-provider-button=true'
+      - '--whitelist-domain=...'
+    environment:
+      OAUTH2_PROXY_COOKIE_SECRET: '...'
+      OAUTH2_PROXY_INSECURE_OIDC_ALLOW_UNVERIFIED_EMAIL: 'true'
+      OAUTH2_PROXY_EMAIL_DOMAINS: '*'
+      OAUTH2_PROXY_PROVIDER: 'oidc'
+      OAUTH2_PROXY_OIDC_ISSUER_URL: '...'
+      OAUTH2_PROXY_CLIENT_ID: '...'
+      OAUTH2_PROXY_CLIENT_SECRET: '...'
   container-director:
     image: git.jacknet.io/jackhadrill/container-director:latest
     restart: always
     environment:
-      LISTEN_PORT: 80
-      CONTAINER_PORT: 80
-      CONTAINER_PREFIX: "container"
-      SPAWNER_URL: "http://container-spawner"
+      SPAWNER_HOST: "container-spawner"
+      CONTAINER_HOST_PREFIX: "vscode"
+      CONTAINER_PORT: 8080
   ...
+networks:
+  backend:
+  proxy:
+    name: web_proxy
+    external: True
 ```
+
+## Process description
+
+The following steps describe how [**Container Spawner**](https://git.jacknet.io/jackhadrill/container-spawner) and **Container Director** work together in order to spawn bespoke containers, on behalf of users authenticated through **OAuth2 Proxy**.
+
+1. A user logs in via **OAuth2 Proxy**.
+   - After a successful login **OAuth2 Proxy** proxies the original request to **Container Director**, adding a `X-Forwarded-Preferred-Username` request header, which contains the user's username.
+2. **Container Director** tries to proxy the original request once more to the user's bespoke container `http://<CONTAINER_HOST_PREFIX>-<X-Forwarded-Preferred-Username>:<CONTAINER_PORT>`.
+   - For example: `http://vscode-jack:8080`.
+3. If the bespoke container does not respond, **Container Director** will proxy the same request to [**Container Spawner**](https://git.jacknet.io/jackhadrill/container-spawner).
+4. [**Container Spawner**](https://git.jacknet.io/jackhadrill/container-spawner) returns a loading page with a refresh timer. Meanwhile, it will check to see if the user's bespoke container exists.
+   - If not, the user's bespoke container will be created.
+   - If it does, something has gone wrong. Return a useful error message!
+
+
diff --git a/director.conf b/director.conf
index f8a361a..eda9224 100644
--- a/director.conf
+++ b/director.conf
@@ -1,5 +1,5 @@
 server {
-    listen       ${LISTEN_PORT};
+    listen       8080;
     server_name  _;
 
     resolver 127.0.0.11 valid=1s;
@@ -10,6 +10,6 @@ server {
     }
     
     location @spawner {
-        proxy_pass ${SPAWNER_URL}$uri;
+        proxy_pass http://${SPAWNER_HOST}:8080$uri;
     }
 }