Merge pull request #2 from sown/random-docs

Random docs

docs/infrastructure/servers/containers.md

@@ -0,0 +1,13 @@
+# Container Servers
+
+## containers-dev (containers-1)
+
+If a service is considered to be experimental, it should be hosted on this containers host.
+
+## containers-prod (containers-2)
+
+If a service is considered to be critical, it should be hosted on this separate containers host so that we can reduce the number of people that have access to it.
+
+## containers-secure (containers-3)
+
+If a service is considered to required additional security, it should be hosted on this separate containers host so that we can reduce the number of people that have access to it.

docs/services/kmibot.md

@@ -0,0 +1,17 @@
+# KMIBot
+
+KMIBot is the bot that does things for the [SUWS / SOWN Discord](https://sown.org.uk/discord).
+
+It is written in Python using discord.py, and the source code is available on GitHub: [`sown/kmibot`](https://github.com/sown/kmibot).
+
+## Hosting
+
+KMIBot is hosted on [`containers-dev`](../infrastructure/servers/containers.md#containers-dev-containers-1).
+
+It is not currently managed by ansible.
+
+## Backend and Web Interface
+
+The bot has a REST API backend and database that is used to store stateful information. It is also available for users to log into to interface with the bot without using Discord.
+
+It is available at [ferry.containers-dev.sown.org.uk](https://ferry.containers-dev.sown.org.uk).

docs/services/kmicms.md

@@ -0,0 +1,37 @@
+# KMICMS - Wagtail CMS
+
+KMICMS is our [Wagtail](https://wagtail.org) content management system (CMS) for managing and serving the content on the [SOWN website](https://www.sown.org.uk).
+
+The source code is available on GitHub: [sown/kmicms](https://github.com/sown/kmicms).
+
+## Access
+
+The admin interface is accessible at [https://www.sown.org.uk/admin](https://www.sown.org.uk/admin).
+
+This service is publicly accessible, but requires authentication.
+
+## Permissions
+
+Wagtail has a flexible permissions model, but at a basic level we have two groups integrated with [SOWN SSO](./sso.md):
+
+* `kmicms:staff` - grants permission to access Wagtail Admin.
+* `kmicms:superuser` - grants superuser permissions.
+
+These permissions are refreshed on login, so if you have additional permissions granted you may need to logout and log back in.
+
+## Hosting
+
+KMICMS is hosted on [`containers-prod`](../infrastructure/servers/containers.md#containers-prod-containers-2).
+
+It is not currently managed by ansible.
+
+## Staging
+
+There is additionally a staging instance of KMICMS, for testing purposes. It is hosted on [`containers-dev`](../infrastructure/servers/containers.md#containers-dev-containers-1).
+
+The staging site can be accessed at [https://sown-staging.containers-dev.sown.org.uk](https://sown-staging.containers-dev.sown.org.uk).
+
+The permissions groups for the staging site are:
+
+* `kmicms:staging:staff` - grants permission to access Wagtail Admin.
+* `kmicms:staging:superuser` - grants superuser permissions.

docs/services/netbox.md

@@ -0,0 +1,27 @@
+# Netbox
+
+SOWN uses [Netbox](https://github.com/netbox-community/netbox) to record information about our servers and infrastructure. It provides both Data Center Infrastructure Management (DCIM) and IP Address Management (IPAM) sources of truth which are then used by other systems to drive automation.
+
+If you are looking for more information about a VM, Server, IP Address, etc., Netbox is the correct place to look.
+
+## Access
+
+Our Netbox instance can be accessed at [netbox.sown.org.uk](https://netbox.sown.org.uk). If prompted for a password, select `OpenID Connect` to login with [SOWN SSO](./sso.md).
+
+This service is publicly accessible, but requires authentication.
+
+## Hosting
+
+Netbox is hosted on it's own VM, aptly called [`netbox`](https://netbox.sown.org.uk/virtualization/virtual-machines/1/).
+
+Netbox is installed at /opt/netbox and runs as the `netbox` user.
+
+For upgrades, see netbox upgrade guide roughly:
+
+```
+cd /opt/netbox/
+sudo -Hu netbox git fetch
+sudo -Hu netbox git checkout vx.y.z
+sudo -Hu netbox ./upgrade.sh
+systemctl restart netbox netbox-rq
+```

docs/services/sso.md

@@ -0,0 +1,55 @@
+# Single Sign-On (SSO)
+
+SOWN uses [Authentik](https://goauthentik.io) for single sign-on (SSO), using OpenID Connect (OIDC), SAML2 or in some cases forward proxy authentication.
+
+## Access
+
+SSO is accessed at [sso.sown.org.uk](https://sso.sown.org.uk). You can log in with your SOWN account credentials or a University of Southampton iSolutions account.
+
+This service is publicly accessible, but requires authentication.
+
+## Permissions
+
+Access to applications is configured using groups. Some applications will require you to be a member of a group in order to access it, whereas others will allow you access and set your permissions depending on the groups that you are a member of.
+
+Group names must be in the format: `<app-name>:<role>`, e.g `kmicms:superuser`.
+
+## Hosting
+
+SSO is hosted on [`containers-secure`](../infrastructure/servers/containers.md#containers-secure-containers-3).
+
+It is not currently managed by ansible.
+
+There is an upgrade script that will automatically check for an update and deploy it when run:
+
+```shell
+root@containers-3:/docker/authentik# ./upgrade.py
+
+SOWN SSO Upgrade Script
+Current Version is Authentik 2024.10.2
+The latest version is Release 2024.10.4, which was released on 2024-11-21T18:47:39Z
+
+Please read the following release notes:
+
+See https://docs.goauthentik.io/docs/releases/2024.10#fixed-in-2024104
+
+What's Changed
+
+...
+
+Full Changelog: https://github.com/goauthentik/authentik/compare/version/2024.10.3...version/2024.10.4
+
+
+Would you like to attempt an update? [y/n]: y
+[+] Running 30/12
+ ✔ worker Pulled                               37.6s
+ ✔ server Pulled                               37.6s
+
+[+] Running 4/4
+ ✔ Container authentik-redis-1       Running   0.0s
+ ✔ Container authentik-postgresql-1  Running   0.0s
+ ✔ Container authentik-worker-1      Started   4.4s
+ ✔ Container authentik-server-1      Started
+```
+
+Please note that it can take up to a minute after Authentik has restarted before it will be fully started and ready to log users in.

mkdocs.yml

@@ -5,9 +5,8 @@ repo_url: https://github.com/sown/docs
 theme:
   name: material
   favicon: images/logo-small.png
-  feature:
-    tabs: true
   features:
+    - navigation.tabs
     - search.suggest
   font:
     text: Open Sans