From 25277530b394cff8456e6baa032f15c871e2ac35 Mon Sep 17 00:00:00 2001
From: wizzdom <wizzdom@redbrick.dcu.ie>
Date: Sun, 31 Mar 2024 18:48:31 +0100
Subject: [PATCH] api: refactor, add nomad docs (#34)

---
 docs/services/api.md | 80 +++++++++++++++++++++++++++++++++++---------
 1 file changed, 64 insertions(+), 16 deletions(-)

diff --git a/docs/services/api.md b/docs/services/api.md
index 8772af2d..fb01da0f 100644
--- a/docs/services/api.md
+++ b/docs/services/api.md
@@ -3,33 +3,81 @@ title: API
 tags:
   - services
   - api
+  - ldap
 ---
 
-# API
-
-## Redbrick Administrator Web API
+# Redbrick Administrative Web API
 
 The source code for the API can be found [here](https://github.com/redbrick/api/).
 
-The Redbrick web API serves as an easy interface to carry out administrator tasks (mainly LDAP related), and for use in automation. This saves time instead of accessing machines, and formulating and executing manual LDAP queries or scripts.
+The Redbrick web API serves as an easy interface to carry out administrator tasks *(mainly LDAP related)*, and for use in automation. This saves time instead of accessing machines, and formulating and executing manual LDAP queries or scripts.
+
+The server code for the API is hosted on [`aperture`](../hardware/aperture/index.md) in a docker container deployed with [`nomad`](nomad.md), the job file for which is [here](https://github.com/redbrick/nomad/blob/master/jobs/services/api.hcl). It is written in Python with [FastAPI](https://fastapi.tiangolo.com/). This container is then served to the public using [`traefik`](traefik.md).
+
+## Nomad Job File
+
+The [nomad job for Redbrick's API](https://github.com/redbrick/nomad/blob/master/jobs/services/api.hcl) is similar to most other web servers for the most part. As always, all secrets are stored in [`consul`](consul.md). Some things to watch out for are:
+
+- The docker image on ghcr.io is private and therefore requires credentials to access.
+
+```hcl title="Nomad"
+auth {
+    username = "${DOCKER_USER}"
+    password = "${DOCKER_PASS}"
+}
+```
+
+```hcl title="Nomad"
+template {
+  data        = <<EOH
+DOCKER_USER={{ key "api/ghcr/username" }}
+DOCKER_PASS={{ key "api/ghcr/password" }}
+...
+EOH
+```
+
+- The docker container must access `/home` and `/storage` on [`icarus`](../hardware/nix/icarus.md) to configure users' home directory and webtree. This is mounted onto the [`aperture`](../hardware/aperture/index.md) boxes at `/oldstorage` and is mounted to the containers like this:
+
+```hcl title="Nomad"
+volumes = [
+          "/oldstorage:/storage",
+          "/oldstorage/home:/home",
+]
+```
+
+- The container requires the LDAP secret at `/etc/ldap.secret` to auth with LDAP. This is stored in [`consul`](consul.md), placed in a template and mounted to the container like this:
 
-The server code for the API is hosted on Zeus in a docker container called 'api-redbrick', written in Python with [FastAPI](https://fastapi.tiangolo.com/). This container is then served to the public using traefik, you can view the dashboard [here](https://traefik.zeus.redbrick.dcu.ie/dashboard/#/).
+```hcl title="Nomad"
+template {
+    destination = "local/ldap.secret"
+    data = "{{ key \"api/ldap/secret\" }}" # this is necessary as the secret has no EOF
+    }
+```
+
+- The container is quite RAM intensive, regularly using `700-800MB`. The job has been configured to allocate `1GB` RAM to the container so it does not OOM. The default `cpu` allocation of `300` is fine.
+
+```hcl title="Nomad"
+resources {
+    cpu = 300
+    memory = 1024
+    }
+```
 
-### Reference
+## Reference
 
 For the most up to date, rich API reference please visit [https://api.redbrick.dcu.ie/docs](https://api.redbrick.dcu.ie/docs)
 
 All requests are validated with Basic Auth for access. [See example.](https://docs.python-requests.org/en/master/user/authentication/#basic-authentication)
 
-|   Method   |         Route          |           URL Parameters             |        Body       |
-| :--------: | :--------------------: | :----------------------------------: | :---------------: |
-|  GET       |  **/users/**`username` | `username` - Redbrick username       | N/A               |
-|  PUT       |  **/users/**`username` | `username` - Redbrick username       | `ldap_key`   |
-|  POST      |  **/users/register**   | N/A                                  | `ldap_value` |
+| Method |         Route         |         URL Parameters         |     Body     |
+| :----: | :-------------------: | :----------------------------: | :----------: |
+|  GET   | **/users/**`username` | `username` - Redbrick username |     N/A      |
+|  PUT   | **/users/**`username` | `username` - Redbrick username |  `ldap_key`  |
+|  POST  |  **/users/register**  |              N/A               | `ldap_value` |
 
-#### Examples
+## Examples
 
-- GET a user's LDAP data
+- `GET` a user's LDAP data
 
 ```python
 import requests
@@ -45,7 +93,7 @@ response = requests.request("GET", url, headers=headers)
 print(response.text)
 ```
 
-- PUT a user's LDAP data to change their `loginShell` to `/usr/local/shells/zsh`
+- `PUT` a user's LDAP data to change their `loginShell` to `/usr/local/shells/zsh`
 
 ```python
 import requests
@@ -66,7 +114,7 @@ response = requests.request("GET", url, headers=headers, data=payload)
 print(response.text)
 ```
 
-### Important Notes and Caveats
+## Important Notes and Caveats
 
 As the FastAPI server for the API is hosted inside of a Docker container, there are limitations to the commands we can execute that affect the "outside" world.
 
@@ -90,4 +138,4 @@ chown 13371337:103 /storage/webtree/U/USERNAME
 # Where 13371337 is userid and 103 is the id for the 'member' group.
 ```
 
-Note that USERNAME can be used to refer to the user's web directory here since it is the name of the directory and doesn't refer to the user object.
+> Note that `USERNAME` can be used to refer to the user's web directory here since it is the name of the directory and doesn't refer to the user object.