From de7f95d7ed674ff0f6623ea34870cf02293d4707 Mon Sep 17 00:00:00 2001 From: TheUsernameOrSmth <105546141+TheUsernameOrSmth@users.noreply.github.com> Date: Fri, 17 Jul 2026 18:13:46 +0200 Subject: [PATCH 01/14] Network and server infrastructure --- content/docs/infrastructure/in-smn/docker.mdx | 27 +++ content/docs/infrastructure/in-smn/meta.json | 4 + .../docs/infrastructure/in-smn/traefik.mdx | 56 +++++ content/docs/infrastructure/index.mdx | 6 - content/docs/infrastructure/meta.json | 12 +- content/docs/infrastructure/network.mdx | 34 +++ .../docs/infrastructure/networkexample.svg | 221 ++++++++++++++++++ content/docs/infrastructure/sso/index.mdx | 17 ++ 8 files changed, 369 insertions(+), 8 deletions(-) create mode 100644 content/docs/infrastructure/in-smn/docker.mdx create mode 100644 content/docs/infrastructure/in-smn/meta.json create mode 100644 content/docs/infrastructure/in-smn/traefik.mdx delete mode 100644 content/docs/infrastructure/index.mdx create mode 100644 content/docs/infrastructure/network.mdx create mode 100644 content/docs/infrastructure/networkexample.svg diff --git a/content/docs/infrastructure/in-smn/docker.mdx b/content/docs/infrastructure/in-smn/docker.mdx new file mode 100644 index 0000000..f9186c6 --- /dev/null +++ b/content/docs/infrastructure/in-smn/docker.mdx @@ -0,0 +1,27 @@ +--- +title: Docker +icon: Container +description: Running the software +--- + + + This page is intended for people with SSH access to IN-SMN + + +We use [Docker](https://www.docker.com/) to host almost all of our software. + +There are two locations we store docker-compose.yml files. `/root/SMN/docker-compose.yml` and `/home/deploy/*/docker-compose.yml`, the later is for auto deployment. + +If a container has a website then it needs to have [Traefik](./traefik) configured using container labels. + +If you change a `docker-compose.yml` file, then you can run `docker compose up -d` to restart only the affected containers. + +## Auto deployment + +We use Github Actions to automatically build, push, and restart containers on the server whenever something gets pushed to `main`. + +To setup Auto Deployment, copy `/home/deploy/example-app` and modify it as needed. Then copy the workflow file from a suitable repository and modify the +directory path (i.e. the final line should start with `script: cd `) + +The automation requires an SSH login which we store as Github Secrets. +If the repository is public then Github handles these for you, however, if the repository to private then you need to manually add the SSH keys. diff --git a/content/docs/infrastructure/in-smn/meta.json b/content/docs/infrastructure/in-smn/meta.json new file mode 100644 index 0000000..86b076a --- /dev/null +++ b/content/docs/infrastructure/in-smn/meta.json @@ -0,0 +1,4 @@ +{ + "title": "IN-SMN", + "icon": "Server" +} \ No newline at end of file diff --git a/content/docs/infrastructure/in-smn/traefik.mdx b/content/docs/infrastructure/in-smn/traefik.mdx new file mode 100644 index 0000000..89d9169 --- /dev/null +++ b/content/docs/infrastructure/in-smn/traefik.mdx @@ -0,0 +1,56 @@ +--- +title: Traefik +icon: TrafficCone +description: Routing the web requests +--- + + + This page is intended for people with SSH access to IN-SMN + + +We use [Traefik](https://doc.traefik.io/traefik/) to route and protect our websites. +We almost always use [container labels](https://doc.traefik.io/traefik/reference/routing-configuration/other-providers/docker/) in our docker compose files. + +The exception to this is when we need to route data to IN-ITK. Here we use .yaml config files located in `/root/SMN/traefik/conf/`. + +You can find the admin panel for traefik at [traefik.kth.it](https://traefik.kth.it/) + +## Label configuration + +Most of the labels are just boilerplate, as such the easiest approach is to copy `/home/deploy/example-app` and modify it to the new app + +## Adding authentication + +We currently support two types of authentication: Basic HTTP auth, and Authentik. + +Both of these are middleware that is specified as container labels: + +Basic auth: + +```yaml +- "traefik.http.routers..middlewares=basic-auth@docker" +``` + +Authentik: + +```yaml +- "traefik.http.routers..middlewares=authentik@docker" +``` + + + To use Authentik, the website needs to be configured on the Authentik dashboard. + See [Auth proxy](../sso#auth-proxy) + + + + Basic Auth is not secure! While it is significantly better than nothing, for + anything critical Authentik should be used. + + +To not have any authentication (and thus have the website accessible to the public internet!) simply omit the middlewares line. + +## SSL Encryption + +We use [Lets Encrypt](https://letsencrypt.org/) to get signed SSL certificates. Traefik automatically requests these for the subdomains we use. + +Since these are per subdomain and not for all \*.kth.it, if subdomain isn't used then the browser warns about a self signed certificate. diff --git a/content/docs/infrastructure/index.mdx b/content/docs/infrastructure/index.mdx deleted file mode 100644 index 9ec7b0f..0000000 --- a/content/docs/infrastructure/index.mdx +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Infrastructure -icon: ServerCog ---- - -Documentation for everything directly related to the chapter's digital infrastructure. diff --git a/content/docs/infrastructure/meta.json b/content/docs/infrastructure/meta.json index 9474153..8368ad7 100644 --- a/content/docs/infrastructure/meta.json +++ b/content/docs/infrastructure/meta.json @@ -2,5 +2,13 @@ "title": "Infrastructure", "description": "Docs for the chapter's digital infrastructure", "root": true, - "icon": "ServerCog" -} + "icon": "ServerCog", + "pages": [ + "---Local Server---", + "servers", + "...", + "in-smn", + "---External---", + "sso" + ] +} \ No newline at end of file diff --git a/content/docs/infrastructure/network.mdx b/content/docs/infrastructure/network.mdx new file mode 100644 index 0000000..7ffcded --- /dev/null +++ b/content/docs/infrastructure/network.mdx @@ -0,0 +1,34 @@ +--- +title: Networking +icon: Network +description: How data gets to the right place +--- + +As listed in [Servers](./servers), we have two main servers: IN-SMN and IN-ITK. + +IN-SMN is the primary server and runs the vast majority of our self-hosted infrastructure. + +IN-ITK is managed by [ITK](https://itk.gg), and is primarily used to host game servers using Pterodactyl. + +The router has port forwarding setup to both IN-SMN and IN-ITK for their respective ports. + +Since most games use higher ports numbers, a range of these ports have been forwarded to IN-ITK, thereby not requiring configuration of the router +for most games. + +Since port 22 (standard SSH port) goes to IN-SMN, port 2222 is the port used for SSH to IN-ITK. + + + Since HTTP(S) traffic (port 80 and 443) goes to IN-SMN, hosting websites on + IN-ITK requires IN-SMN to forward it to IN-ITK using + [traefik](in-smn/traefik). + + +![Server data is sent to IN-ITK. Http, mqtt, and ssh is sent to IN-SMN. Some HTTP traffic is forwarded to IN-ITK by IN-SMN](networkexample.svg) + +## Netlify + +Some services/websites need higher availability, such as [kth.it](kth.it) and the major committee websites. +These should be hosted on a high availability service, commonly [Netlify](https://www.netlify.com/). + +Since kth.it is on Netlify and not hosted on IN-SMN, we have two DNS records. One for `kth.it` that goes to Netlify, and a wildcard `*.kth.it` that goes to our servers. +As such, when using SSH to the server, use `server.kth.it` as the IP instead of `kth.it`. The DNS records are configured on Netlify. diff --git a/content/docs/infrastructure/networkexample.svg b/content/docs/infrastructure/networkexample.svg new file mode 100644 index 0000000..8c2aa60 --- /dev/null +++ b/content/docs/infrastructure/networkexample.svg @@ -0,0 +1,221 @@ + + + + + + + + + + + + + + + + + + + + + + Internet + Router + + + IN-SMN + IN-ITK + Game +servers + http(s), +ssh, mqtt + traefik +forwarding + + + + + + + + + diff --git a/content/docs/infrastructure/sso/index.mdx b/content/docs/infrastructure/sso/index.mdx index a896a50..878e845 100644 --- a/content/docs/infrastructure/sso/index.mdx +++ b/content/docs/infrastructure/sso/index.mdx @@ -20,6 +20,23 @@ Services that needs to be controlled by auth that we host ourselves can add authentication using the [Traefik][3] proxy. The app also needs to be added with access control to the SSO service to be allowed in the proxy. +This is done in the admin interface by creating an application and proxy provider for it. +The provider needs to be "Forward auth (single application)" and the sites URL specified as the host. (e.g. `https://shit.kth.it`) +Finally you need to bind a group that has access to it. You should choose the most suitable group. You can use any exported Google group - their names should be self explanatory, but there are also group which are not from Google Workspace: + + +| Group | What | Use | +| ------------------ | -------------------------------------------------------------------------- | ------------------------------------------------------------------------ | +| itsektionen | This is everyone with a kth.it account. | Used as the default when anyone active in the chapter should have access | +| Server Maintainers | This is the people who maintain our infrastructure (i.e. **init** and SMN) | Used for more sensitive and critical websites | + +In addition, any exported google group can be specified if needed. + +Finally, the traefik router must have Authentik added as a middleware. For docker containers, the label looks like the following: +```yaml +- "traefik.http.routers..middlewares=authentik@docker" +``` + [1]: https://goauthentik.io/ [2]: https://sso.kth.it [3]: https://traefik.io From 8c549156c167fc3593a2813fdcab86770dd09e23 Mon Sep 17 00:00:00 2001 From: Fripe070 <72686066+Fripe070@users.noreply.github.com> Date: Mon, 3 Aug 2026 21:26:36 +0200 Subject: [PATCH 02/14] Rewrite docker guide --- content/docs/infrastructure/in-smn/docker.mdx | 63 +++++++++++++++---- 1 file changed, 50 insertions(+), 13 deletions(-) diff --git a/content/docs/infrastructure/in-smn/docker.mdx b/content/docs/infrastructure/in-smn/docker.mdx index f9186c6..cdbdf08 100644 --- a/content/docs/infrastructure/in-smn/docker.mdx +++ b/content/docs/infrastructure/in-smn/docker.mdx @@ -1,27 +1,64 @@ --- -title: Docker +title: Containers icon: Container -description: Running the software +description: How to run software in containers on the IN-SMN server using Docker Compose --- +import { Step, Steps } from "fumadocs-ui/components/steps"; + - This page is intended for people with SSH access to IN-SMN + This page assumes that you have SSH access to the IN-SMN server. It may still + be useful if you do not have access but are developing software that will be + deployed to our servers. -We use [Docker](https://www.docker.com/) to host almost all of our software. +Almost all software hosted on the IN-SMN server runs in Docker containers managed with [Docker Compose](https://docs.docker.com/compose/). + +Compose files are stored in two main locations: + +- `/root/SMN/docker-compose.yml` contains the configuration for core/static services that do not require automatic updates. + These include + [Traefik](./traefik), + [Authentik](../sso), + [Mosquitto](https://github.com/eclipse-mosquitto/mosquitto), + [LMixer](../../locale/software/lmixer), + and others. + +- `/home/deploy/` holds directories for automatically deployed applications, + which each have their own compose file that references a published docker image. + For details, see [Automatic deployment](#automatic-deployment). + +If a container hosts a website that should be accessible, it should define labels as detailed on the [Traefik page](./traefik). + +If you change a `docker-compose.yml` file, you can run `docker compose up -d` in its directory to restart only the affected containers. -There are two locations we store docker-compose.yml files. `/root/SMN/docker-compose.yml` and `/home/deploy/*/docker-compose.yml`, the later is for auto deployment. +## Automatic deployment -If a container has a website then it needs to have [Traefik](./traefik) configured using container labels. +We use Github Actions to automatically build, push, pull and restart containers +on the server whenever changes are made to a project repository's main branch. -If you change a `docker-compose.yml` file, then you can run `docker compose up -d` to restart only the affected containers. +To set up automatic deployment: -## Auto deployment + + +Copy `/home/deploy/example-app` modify its configuration as needed. + + +Copy a suitable workflow file from an existing repository in the chapter org. +For example the [one from shIT](https://github.com/itsektionen/shIT/blob/main/.github/workflows/deploy.yml). + + +Update the directory being accessed in the workflow. +```yaml +script: cd && +``` -We use Github Actions to automatically build, push, and restart containers on the server whenever something gets pushed to `main`. +The workflow connects to the server over SSH as the `deploy` user. +Its credentials are stored as secrets in the chapter's [GitHub organization](https://github.com/itsektionen) +and are exposed to workflows as `SSH_HOST`, `SSH_USERNAME`, and `SSH_KEY`. -To setup Auto Deployment, copy `/home/deploy/example-app` and modify it as needed. Then copy the workflow file from a suitable repository and modify the -directory path (i.e. the final line should start with `script: cd `) +These secrets will be made available automatically to actions running on public repositories. +If the repository to private, you need to manually add the SSH credentials. -The automation requires an SSH login which we store as Github Secrets. -If the repository is public then Github handles these for you, however, if the repository to private then you need to manually add the SSH keys. + + From 6c6cd397437972e119510301cd66802e4cb446ba Mon Sep 17 00:00:00 2001 From: TheUsernameOrSmth <105546141+TheUsernameOrSmth@users.noreply.github.com> Date: Fri, 14 Aug 2026 19:43:07 +0200 Subject: [PATCH 03/14] Added Andesite docs --- content/docs/infrastructure/in-smn/docker.mdx | 35 +++++++++++++++---- 1 file changed, 28 insertions(+), 7 deletions(-) diff --git a/content/docs/infrastructure/in-smn/docker.mdx b/content/docs/infrastructure/in-smn/docker.mdx index cdbdf08..0cc630d 100644 --- a/content/docs/infrastructure/in-smn/docker.mdx +++ b/content/docs/infrastructure/in-smn/docker.mdx @@ -37,6 +37,8 @@ If you change a `docker-compose.yml` file, you can run `docker compose up -d` in We use Github Actions to automatically build, push, pull and restart containers on the server whenever changes are made to a project repository's main branch. +Since we pretty much always do the same thing, we have a workflow that is reused. + To set up automatic deployment: @@ -44,15 +46,9 @@ To set up automatic deployment: Copy `/home/deploy/example-app` modify its configuration as needed. -Copy a suitable workflow file from an existing repository in the chapter org. -For example the [one from shIT](https://github.com/itsektionen/shIT/blob/main/.github/workflows/deploy.yml). +Copy the [workflow template](https://github.com/itsektionen/andesite) and modify it as listed in the readme. -Update the directory being accessed in the workflow. -```yaml -script: cd && -``` - The workflow connects to the server over SSH as the `deploy` user. Its credentials are stored as secrets in the chapter's [GitHub organization](https://github.com/itsektionen) and are exposed to workflows as `SSH_HOST`, `SSH_USERNAME`, and `SSH_KEY`. @@ -62,3 +58,28 @@ If the repository to private, you need to manually add the SSH credentials. + +### Configuring Andesite + +Andesite's behavior can be configured using inputs under `jobs.with`. + +**Example:** Enable caching with gha: + +```yaml +jobs: + secrets: inherit + with: + deploy-dir: docs + cache: "gha" + gha-mode: "min" +``` + +Here is a list of all options and their effects: + +| Key | Type | Default | Description | +| ---------------------- | -------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------ | +| deploy-dir | string | N/A (required) | The folder where the docker-compose.yaml is, i.e. `/home/deploy//docker-compose.yaml` | +| cache | "gha" or "" | "" | Enables caching on the docker build step. "gha" caches all intermediary steps. | +| gha-mode | "min" or "max" | "min" | How aggressively "gha" caching is done. See [gha caching mode](https://docs.docker.com/build/cache/backends/#cache-mode) | +| use-lfs | boolean | false | If the repository uses LFS to track files | +| limit-lfs-to-directory | string | "" | Only fetch the LFS files in a specific folder instead of the entire repositories. Useful for monorepos | From e90d90be3e530ff36c7373d06019d5833a769d2e Mon Sep 17 00:00:00 2001 From: TheUsernameOrSmth <105546141+TheUsernameOrSmth@users.noreply.github.com> Date: Fri, 14 Aug 2026 19:57:13 +0200 Subject: [PATCH 04/14] Add docs for context specifier --- content/docs/infrastructure/in-smn/docker.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/content/docs/infrastructure/in-smn/docker.mdx b/content/docs/infrastructure/in-smn/docker.mdx index 0cc630d..7ccf853 100644 --- a/content/docs/infrastructure/in-smn/docker.mdx +++ b/content/docs/infrastructure/in-smn/docker.mdx @@ -79,6 +79,7 @@ Here is a list of all options and their effects: | Key | Type | Default | Description | | ---------------------- | -------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------ | | deploy-dir | string | N/A (required) | The folder where the docker-compose.yaml is, i.e. `/home/deploy//docker-compose.yaml` | +| context-dir | string | "." | The folder with the dockerfile. Use if not placed in the root directory. Prefix with `./`, e.g. `./website/` | | cache | "gha" or "" | "" | Enables caching on the docker build step. "gha" caches all intermediary steps. | | gha-mode | "min" or "max" | "min" | How aggressively "gha" caching is done. See [gha caching mode](https://docs.docker.com/build/cache/backends/#cache-mode) | | use-lfs | boolean | false | If the repository uses LFS to track files | From f9c22beec260678b47bd5ee09e50f95c127c9a35 Mon Sep 17 00:00:00 2001 From: Fripe070 <72686066+Fripe070@users.noreply.github.com> Date: Sun, 16 Aug 2026 19:17:59 +0200 Subject: [PATCH 05/14] rename docker to containers --- content/docs/infrastructure/in-smn/{docker.mdx => containers.mdx} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename content/docs/infrastructure/in-smn/{docker.mdx => containers.mdx} (100%) diff --git a/content/docs/infrastructure/in-smn/docker.mdx b/content/docs/infrastructure/in-smn/containers.mdx similarity index 100% rename from content/docs/infrastructure/in-smn/docker.mdx rename to content/docs/infrastructure/in-smn/containers.mdx From 68a53b7052bbeea891877d41c5bb3693079fa5cf Mon Sep 17 00:00:00 2001 From: Fripe070 <72686066+Fripe070@users.noreply.github.com> Date: Sun, 16 Aug 2026 19:55:13 +0200 Subject: [PATCH 06/14] Polish traefik docs with auth methods in separate tabs --- .../docs/infrastructure/in-smn/containers.mdx | 3 +- .../docs/infrastructure/in-smn/traefik.mdx | 85 ++++++++++--------- mdx-components.tsx | 6 +- 3 files changed, 52 insertions(+), 42 deletions(-) diff --git a/content/docs/infrastructure/in-smn/containers.mdx b/content/docs/infrastructure/in-smn/containers.mdx index 7ccf853..60c633e 100644 --- a/content/docs/infrastructure/in-smn/containers.mdx +++ b/content/docs/infrastructure/in-smn/containers.mdx @@ -46,7 +46,7 @@ To set up automatic deployment: Copy `/home/deploy/example-app` modify its configuration as needed. -Copy the [workflow template](https://github.com/itsektionen/andesite) and modify it as listed in the readme. +Copy the [workflow template](https://github.com/itsektionen/andesite) and configure it as detailed in its readme. The workflow connects to the server over SSH as the `deploy` user. @@ -55,7 +55,6 @@ and are exposed to workflows as `SSH_HOST`, `SSH_USERNAME`, and `SSH_KEY`. These secrets will be made available automatically to actions running on public repositories. If the repository to private, you need to manually add the SSH credentials. - diff --git a/content/docs/infrastructure/in-smn/traefik.mdx b/content/docs/infrastructure/in-smn/traefik.mdx index 89d9169..4ec4357 100644 --- a/content/docs/infrastructure/in-smn/traefik.mdx +++ b/content/docs/infrastructure/in-smn/traefik.mdx @@ -1,56 +1,65 @@ --- -title: Traefik +title: Websites and routing icon: TrafficCone description: Routing the web requests --- - This page is intended for people with SSH access to IN-SMN + This page assumes that you have SSH access to the IN-SMN server. It may still + be useful if you do not have access but are developing software that will be + deployed to our servers. -We use [Traefik](https://doc.traefik.io/traefik/) to route and protect our websites. -We almost always use [container labels](https://doc.traefik.io/traefik/reference/routing-configuration/other-providers/docker/) in our docker compose files. +We use [Traefik](https://doc.traefik.io/traefik/) to handle routing to our websites and to apply middleware. +It is usualy configured through [container labels](https://doc.traefik.io/traefik/reference/routing-configuration/other-providers/docker/) +defined in project compose files, with the exception of when we need to route data to [IN-ITK](../servers#server-in-itk). +{/* TODO: Document yaml config */} In this case we use YAML configs located in `/root/SMN/traefik/conf/`. -The exception to this is when we need to route data to IN-ITK. Here we use .yaml config files located in `/root/SMN/traefik/conf/`. +The traefik admin dashboard is hosted at [traefik.kth.it](https://traefik.kth.it/) for those with access. -You can find the admin panel for traefik at [traefik.kth.it](https://traefik.kth.it/) +## Basic configuration -## Label configuration - -Most of the labels are just boilerplate, as such the easiest approach is to copy `/home/deploy/example-app` and modify it to the new app +Most required labelss are just boilerplate and will not vary significantly between deployments. +The easiest approach to get up and running is to copy the labels of `/home/deploy/example-app` and modify them to fit the new deployment. ## Adding authentication -We currently support two types of authentication: Basic HTTP auth, and Authentik. - -Both of these are middleware that is specified as container labels: - -Basic auth: - -```yaml -- "traefik.http.routers..middlewares=basic-auth@docker" -``` - -Authentik: - -```yaml -- "traefik.http.routers..middlewares=authentik@docker" -``` - - - To use Authentik, the website needs to be configured on the Authentik dashboard. - See [Auth proxy](../sso#auth-proxy) - - - - Basic Auth is not secure! While it is significantly better than nothing, for - anything critical Authentik should be used. - - -To not have any authentication (and thus have the website accessible to the public internet!) simply omit the middlewares line. +There are two types of authentication commonly used for deployments: Basic HTTP auth and Authentik. +Both are added through defining middleware with a traefik label. +To not have any authentication (and leave the site available to the entire internet) just omit a middlewares label. + + + + + To be able to acess a site with the authentik middleware, it needs to be + properly configured through the authetik dashboard. + For details see: [Auth proxy](../sso#auth-proxy). + + + ```yaml + # Label + - "traefik.http.routers..middlewares=authentik@docker" + ``` + + + + + Basic Auth is not secure! While it is significantly better than nothing, + anything critical should prefer Authentik. + + + ```yaml + # Label + - "traefik.http.routers..middlewares=basic-auth@docker" + ``` + + + ## SSL Encryption -We use [Lets Encrypt](https://letsencrypt.org/) to get signed SSL certificates. Traefik automatically requests these for the subdomains we use. +We use [Lets Encrypt](https://letsencrypt.org/) to get signed SSL certificates. +Traefik automatically requests these for the subdomains we use. -Since these are per subdomain and not for all \*.kth.it, if subdomain isn't used then the browser warns about a self signed certificate. +Since these are per subdomain and not for all of \*.kth.it, +if nothing is served on a subdomain the browser will warn about a self-signed certificate. diff --git a/mdx-components.tsx b/mdx-components.tsx index b0ecaa7..daca472 100644 --- a/mdx-components.tsx +++ b/mdx-components.tsx @@ -1,13 +1,15 @@ +import * as TabsComponents from "fumadocs-ui/components/tabs"; import defaultMdxComponents from "fumadocs-ui/mdx"; import type { MDXComponents } from "mdx/types"; -import ExclusiveTo from "./components/generic/callout/exclusive-to"; import CalloutExt from "./components/generic/callout/callout-ext"; -import Icon from "./components/generic/icon"; +import ExclusiveTo from "./components/generic/callout/exclusive-to"; import Card from "./components/generic/card"; +import Icon from "./components/generic/icon"; export function getMDXComponents(components?: MDXComponents): MDXComponents { return { ...defaultMdxComponents, + ...TabsComponents, ...components, ExclusiveTo: ExclusiveTo, CalloutExt: CalloutExt, From 73130bd62480e3627e5fa5a6495e3cab2f3d2777 Mon Sep 17 00:00:00 2001 From: Fripe070 <72686066+Fripe070@users.noreply.github.com> Date: Sun, 16 Aug 2026 20:49:32 +0200 Subject: [PATCH 07/14] Expose steps components for mdx by default --- content/docs/(docs)/writing-documentation/dev-enviroment.mdx | 2 -- content/docs/(docs)/writing-documentation/index.mdx | 2 -- content/docs/(docs)/writing-documentation/pull-requests.mdx | 2 -- content/docs/infrastructure/in-smn/containers.mdx | 2 -- content/docs/infrastructure/sso/loginflow.mdx | 2 -- content/docs/locale/guides/soundmixer.mdx | 2 -- content/docs/software/(software)/index.mdx | 2 -- content/docs/software/(software)/starting-a-project.mdx | 2 -- mdx-components.tsx | 2 ++ 9 files changed, 2 insertions(+), 16 deletions(-) diff --git a/content/docs/(docs)/writing-documentation/dev-enviroment.mdx b/content/docs/(docs)/writing-documentation/dev-enviroment.mdx index 1b5401b..0649865 100644 --- a/content/docs/(docs)/writing-documentation/dev-enviroment.mdx +++ b/content/docs/(docs)/writing-documentation/dev-enviroment.mdx @@ -4,8 +4,6 @@ icon: GitFork description: Getting the documentation ready for you --- -import { Step, Steps } from "fumadocs-ui/components/steps"; - If you are new to Git and/or Github, welcome! This page should get you started. diff --git a/content/docs/(docs)/writing-documentation/index.mdx b/content/docs/(docs)/writing-documentation/index.mdx index 549c878..ec9cbb5 100644 --- a/content/docs/(docs)/writing-documentation/index.mdx +++ b/content/docs/(docs)/writing-documentation/index.mdx @@ -4,8 +4,6 @@ icon: PenLine description: How to contribute --- -import { Step, Steps } from "fumadocs-ui/components/steps"; - Documentation is an integral part of ensuring the longevity of our systems, and it should not be taken lightly. Our goal is to document all systems as we develop them through prose, and for relevant software, through [OpenAPI](https://www.openapis.org/). diff --git a/content/docs/(docs)/writing-documentation/pull-requests.mdx b/content/docs/(docs)/writing-documentation/pull-requests.mdx index b314e2d..f620319 100644 --- a/content/docs/(docs)/writing-documentation/pull-requests.mdx +++ b/content/docs/(docs)/writing-documentation/pull-requests.mdx @@ -4,8 +4,6 @@ icon: GitPullRequest description: Getting your code back to use --- -import { Step, Steps } from "fumadocs-ui/components/steps"; - ## Commit your changes diff --git a/content/docs/infrastructure/in-smn/containers.mdx b/content/docs/infrastructure/in-smn/containers.mdx index 60c633e..9496c53 100644 --- a/content/docs/infrastructure/in-smn/containers.mdx +++ b/content/docs/infrastructure/in-smn/containers.mdx @@ -4,8 +4,6 @@ icon: Container description: How to run software in containers on the IN-SMN server using Docker Compose --- -import { Step, Steps } from "fumadocs-ui/components/steps"; - This page assumes that you have SSH access to the IN-SMN server. It may still be useful if you do not have access but are developing software that will be diff --git a/content/docs/infrastructure/sso/loginflow.mdx b/content/docs/infrastructure/sso/loginflow.mdx index 4f444f7..00dade5 100644 --- a/content/docs/infrastructure/sso/loginflow.mdx +++ b/content/docs/infrastructure/sso/loginflow.mdx @@ -2,8 +2,6 @@ title: Login flow --- -import { Step, Steps } from "fumadocs-ui/components/steps"; - User navigates to app domain. Ex. [https://lmixer.kth.it][1]. User is redirected to the SSO service at [https://sso.kth.it][2]. diff --git a/content/docs/locale/guides/soundmixer.mdx b/content/docs/locale/guides/soundmixer.mdx index 6b33018..cd4c1ec 100644 --- a/content/docs/locale/guides/soundmixer.mdx +++ b/content/docs/locale/guides/soundmixer.mdx @@ -2,8 +2,6 @@ title: Sound Mixer --- -import { Step, Steps } from "fumadocs-ui/components/steps"; - ## Loading default settings diff --git a/content/docs/software/(software)/index.mdx b/content/docs/software/(software)/index.mdx index 6fa643c..000fe1f 100644 --- a/content/docs/software/(software)/index.mdx +++ b/content/docs/software/(software)/index.mdx @@ -3,8 +3,6 @@ title: Software icon: Hammer --- -import { Step, Steps } from "fumadocs-ui/components/steps"; - The IT chapter maintains a lot of different software systems made to ease operations. Most software can be found on the chapter's [GitHub organization](https://github.com/itsektionen). diff --git a/content/docs/software/(software)/starting-a-project.mdx b/content/docs/software/(software)/starting-a-project.mdx index ade10df..6b52f6a 100644 --- a/content/docs/software/(software)/starting-a-project.mdx +++ b/content/docs/software/(software)/starting-a-project.mdx @@ -4,8 +4,6 @@ icon: Rocket description: Guidelines and general tips for starting a project --- -import { Step, Steps } from "fumadocs-ui/components/steps"; - No two projects are the same. However, one can still apply lessons learned from other projects to make the process smoother. Here are some general tips that can help you get started: diff --git a/mdx-components.tsx b/mdx-components.tsx index daca472..a579dff 100644 --- a/mdx-components.tsx +++ b/mdx-components.tsx @@ -1,4 +1,5 @@ import * as TabsComponents from "fumadocs-ui/components/tabs"; +import * as StepComponents from "fumadocs-ui/components/steps"; import defaultMdxComponents from "fumadocs-ui/mdx"; import type { MDXComponents } from "mdx/types"; import CalloutExt from "./components/generic/callout/callout-ext"; @@ -10,6 +11,7 @@ export function getMDXComponents(components?: MDXComponents): MDXComponents { return { ...defaultMdxComponents, ...TabsComponents, + ...StepComponents, ...components, ExclusiveTo: ExclusiveTo, CalloutExt: CalloutExt, From 639ab2cb8604c56fe9f0cc1904d4f0f633c45f28 Mon Sep 17 00:00:00 2001 From: Fripe070 <72686066+Fripe070@users.noreply.github.com> Date: Sun, 16 Aug 2026 22:20:21 +0200 Subject: [PATCH 08/14] Proofreading fixes yay --- .../docs/infrastructure/in-smn/containers.mdx | 31 ++++++++++--------- .../docs/infrastructure/in-smn/traefik.mdx | 28 ++++++++--------- 2 files changed, 30 insertions(+), 29 deletions(-) diff --git a/content/docs/infrastructure/in-smn/containers.mdx b/content/docs/infrastructure/in-smn/containers.mdx index 9496c53..2c3bac2 100644 --- a/content/docs/infrastructure/in-smn/containers.mdx +++ b/content/docs/infrastructure/in-smn/containers.mdx @@ -23,7 +23,7 @@ Compose files are stored in two main locations: and others. - `/home/deploy/` holds directories for automatically deployed applications, - which each have their own compose file that references a published docker image. + which each have their own Compose file that references a published Docker image. For details, see [Automatic deployment](#automatic-deployment). If a container hosts a website that should be accessible, it should define labels as detailed on the [Traefik page](./traefik). @@ -32,7 +32,7 @@ If you change a `docker-compose.yml` file, you can run `docker compose up -d` in ## Automatic deployment -We use Github Actions to automatically build, push, pull and restart containers +We use GitHub Actions to automatically build, push, pull, and restart containers on the server whenever changes are made to a project repository's main branch. Since we pretty much always do the same thing, we have a workflow that is reused. @@ -41,18 +41,19 @@ To set up automatic deployment: -Copy `/home/deploy/example-app` modify its configuration as needed. +Copy `/home/deploy/example-app` and modify its configuration as needed. -Copy the [workflow template](https://github.com/itsektionen/andesite) and configure it as detailed in its readme. +Copy the [workflow template](https://github.com/itsektionen/andesite) and configure it as detailed in its README. The workflow connects to the server over SSH as the `deploy` user. Its credentials are stored as secrets in the chapter's [GitHub organization](https://github.com/itsektionen) and are exposed to workflows as `SSH_HOST`, `SSH_USERNAME`, and `SSH_KEY`. -These secrets will be made available automatically to actions running on public repositories. -If the repository to private, you need to manually add the SSH credentials. +These secrets are made available automatically to workflows running on public repositories. +If the repository is private, you need to add the SSH credentials manually. + @@ -60,7 +61,7 @@ If the repository to private, you need to manually add the SSH credentials. Andesite's behavior can be configured using inputs under `jobs.with`. -**Example:** Enable caching with gha: +**Example:** Enable caching with GHA: ```yaml jobs: @@ -73,11 +74,11 @@ jobs: Here is a list of all options and their effects: -| Key | Type | Default | Description | -| ---------------------- | -------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------ | -| deploy-dir | string | N/A (required) | The folder where the docker-compose.yaml is, i.e. `/home/deploy//docker-compose.yaml` | -| context-dir | string | "." | The folder with the dockerfile. Use if not placed in the root directory. Prefix with `./`, e.g. `./website/` | -| cache | "gha" or "" | "" | Enables caching on the docker build step. "gha" caches all intermediary steps. | -| gha-mode | "min" or "max" | "min" | How aggressively "gha" caching is done. See [gha caching mode](https://docs.docker.com/build/cache/backends/#cache-mode) | -| use-lfs | boolean | false | If the repository uses LFS to track files | -| limit-lfs-to-directory | string | "" | Only fetch the LFS files in a specific folder instead of the entire repositories. Useful for monorepos | +| Key | Type | Default | Description | +| ---------------------- | -------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| deploy-dir | string | N/A (required) | The folder containing `docker-compose.yaml`, e.g. `/home/deploy//docker-compose.yaml` | +| context-dir | string | "." | The folder containing the Dockerfile. Use this if it is not in the root directory. Prefix it with `./`, e.g. `./website/` | +| cache | "gha" or "" | "" | Enables caching during the Docker build step. "gha" caches all intermediate steps. | +| gha-mode | "min" or "max" | "min" | Controls how aggressively "gha" caching is performed. See [GHA caching mode](https://docs.docker.com/build/cache/backends/#cache-mode) | +| use-lfs | boolean | false | Whether the repository uses LFS to track files | +| limit-lfs-to-directory | string | "" | Fetches LFS files only from a specific folder rather than the entire repository. Useful for monorepos | diff --git a/content/docs/infrastructure/in-smn/traefik.mdx b/content/docs/infrastructure/in-smn/traefik.mdx index 4ec4357..0b0222f 100644 --- a/content/docs/infrastructure/in-smn/traefik.mdx +++ b/content/docs/infrastructure/in-smn/traefik.mdx @@ -1,7 +1,7 @@ --- title: Websites and routing icon: TrafficCone -description: Routing the web requests +description: Routing web requests --- @@ -11,29 +11,29 @@ description: Routing the web requests We use [Traefik](https://doc.traefik.io/traefik/) to handle routing to our websites and to apply middleware. -It is usualy configured through [container labels](https://doc.traefik.io/traefik/reference/routing-configuration/other-providers/docker/) +It is usually configured through [container labels](https://doc.traefik.io/traefik/reference/routing-configuration/other-providers/docker/) defined in project compose files, with the exception of when we need to route data to [IN-ITK](../servers#server-in-itk). {/* TODO: Document yaml config */} In this case we use YAML configs located in `/root/SMN/traefik/conf/`. -The traefik admin dashboard is hosted at [traefik.kth.it](https://traefik.kth.it/) for those with access. +The Traefik admin dashboard is hosted at [traefik.kth.it](https://traefik.kth.it/) for those with access. ## Basic configuration -Most required labelss are just boilerplate and will not vary significantly between deployments. +Most required labels are boilerplate and will not vary significantly between deployments. The easiest approach to get up and running is to copy the labels of `/home/deploy/example-app` and modify them to fit the new deployment. ## Adding authentication -There are two types of authentication commonly used for deployments: Basic HTTP auth and Authentik. -Both are added through defining middleware with a traefik label. -To not have any authentication (and leave the site available to the entire internet) just omit a middlewares label. +There are two types of authentication commonly used for deployments: HTTP Basic Auth and Authentik. +Both are added by defining middleware with a Traefik label. +To leave a site available to the entire internet, omit the middleware label. - To be able to acess a site with the authentik middleware, it needs to be - properly configured through the authetik dashboard. - For details see: [Auth proxy](../sso#auth-proxy). + To access a site with the Authentik middleware, it must be properly + configured through the Authentik dashboard. For details, see + [the SSO docs](../sso#configuration). ```yaml @@ -56,10 +56,10 @@ To not have any authentication (and leave the site available to the entire inter -## SSL Encryption +## SSL encryption -We use [Lets Encrypt](https://letsencrypt.org/) to get signed SSL certificates. +We use [Let's Encrypt](https://letsencrypt.org/) to obtain signed SSL certificates. Traefik automatically requests these for the subdomains we use. -Since these are per subdomain and not for all of \*.kth.it, -if nothing is served on a subdomain the browser will warn about a self-signed certificate. +Since these certificates are issued per subdomain rather than for all of `*.kth.it`, +the browser will warn about a self-signed certificate if visiting a subdomain where nothing is served. From cb11f9537422c335cf549d1a985e5eb3646efca0 Mon Sep 17 00:00:00 2001 From: Fripe070 <72686066+Fripe070@users.noreply.github.com> Date: Sun, 16 Aug 2026 22:20:48 +0200 Subject: [PATCH 09/14] Rewrite tons of the SSO/Authentik docs --- content/docs/infrastructure/sso/index.mdx | 80 +++++++++++++++-------- 1 file changed, 54 insertions(+), 26 deletions(-) diff --git a/content/docs/infrastructure/sso/index.mdx b/content/docs/infrastructure/sso/index.mdx index 878e845..2521823 100644 --- a/content/docs/infrastructure/sso/index.mdx +++ b/content/docs/infrastructure/sso/index.mdx @@ -5,38 +5,66 @@ icon: KeyRound ## Software -We use a software called [Authentik][1] to manage access to different resources. -It is hosted on the servers in Kistan and provides federated access to all -resources and apps. It can be used as a backend for both OAuth2, SAML and OIDC. +We use [Authentik](https://goauthentik.io/) to manage access to different resources. +It is hosted on [IN-SMN](../servers#server-in-smn) and provides federated access +to resources and apps. It can be used as a backend for OAuth2, SAML, and OIDC. This is supported by Google Workspace via LDAP as the source for accounts and groups. -The service is hosted on the domain [https://sso.kth.it/][2] where a login -will also show a dashboard with available apps. +It is hosted at [sso.kth.it](https://sso.kth.it/), which is used for logins +and displays a dashboard with apps available to the authenticated user. -## Auth proxy +## Configuration -Services that needs to be controlled by auth that we host ourselves can add -authentication using the [Traefik][3] proxy. The app also needs to be added with -access control to the SSO service to be allowed in the proxy. +Services that should require authentication to be accessed can use Authentik as +middleware through the Traefik proxy, as detailed in the [routing documentation](./in-smn/traefik#adding-authentication). +For the middleware to work, add an application with a corresponding proxy provider +linked to the embedded outpost for the site through the Authentik admin dashboard. -This is done in the admin interface by creating an application and proxy provider for it. -The provider needs to be "Forward auth (single application)" and the sites URL specified as the host. (e.g. `https://shit.kth.it`) -Finally you need to bind a group that has access to it. You should choose the most suitable group. You can use any exported Google group - their names should be self explanatory, but there are also group which are not from Google Workspace: + + + Go to the [Applications panel](https://sso.kth.it/if/admin/#/core/applications) + and click "Create with Provider". Give the application a name, slug, and optional icon. + + + Choose the provider type. When using the Traefik middleware this will be + "Proxy Provider". If the application itself allows for authentication + through OAuth, "OAuth2/OpenID Provider" can be used and the Traefik proxy + can be skipped. + The provider name can be kept as-is, and the authorization flow can be set to either explicit or implicit consent. + This controls whether the user is prompted to log in. Implicit consent is generally preferred. + + + + + The proxy provider allows protecting a page behind Authentik without requiring specific support from the application. + When used with the Traefik middleware, it should be set to "Forward auth (single application)", + with the external host set to the URL at which the site is served (e.g. `https://shit.kth.it`). + + + The provider requires a client ID and secret, as well as a URL for authentication. + The exact configuration values and the method for obtaining them vary by application; consult its documentation. -| Group | What | Use | -| ------------------ | -------------------------------------------------------------------------- | ------------------------------------------------------------------------ | -| itsektionen | This is everyone with a kth.it account. | Used as the default when anyone active in the chapter should have access | -| Server Maintainers | This is the people who maintain our infrastructure (i.e. **init** and SMN) | Used for more sensitive and critical websites | + The Authentik documentation has a general page on [OAuth2/OIDC authentication](https://docs.goauthentik.io/add-secure-apps/providers/oauth2/), + and a more specific guide on [setting up Grafana](https://integrations.goauthentik.io/monitoring/grafana/#create-an-application-and-provider-in-authentik), + which could be a useful reference. + + + + + To decide who has access, configure bindings for the application's provider. + You can create bindings for groups and specific users (also policies but we don't use them). -In addition, any exported google group can be specified if needed. - -Finally, the traefik router must have Authentik added as a middleware. For docker containers, the label looks like the following: -```yaml -- "traefik.http.routers..middlewares=authentik@docker" -``` - -[1]: https://goauthentik.io/ -[2]: https://sso.kth.it -[3]: https://traefik.io + Most groups are sourced from the chapter's [Google Workspace](./google-workspace.mdx) and sync automatically. + Their names should be largely self-explanatory. + A few groups are special and are not defined in Google Workspace, Notably: + | Group | Who | Why | + | ------------------ | ---------------------------------------------------------- | ------------------------------------------------------------------------- | + | itsektionen | Everyone who has logged in with a kth.it account | The preferred option when anyone active in the chapter should have access | + | Server Maintainers | People who maintain our infrastructure (i.e. init and SMN) | Used for more sensitive or critical systems such as Grafana | + + + If using a proxy provider, add it to the Embedded [Outpost](https://sso.kth.it/if/admin/#/outpost/outposts). + + From 76242d602df4da845d389e85c6585f8516410476 Mon Sep 17 00:00:00 2001 From: Fripe070 <72686066+Fripe070@users.noreply.github.com> Date: Sun, 16 Aug 2026 23:10:40 +0200 Subject: [PATCH 10/14] Rewrite network page --- content/docs/infrastructure/network.mdx | 45 +++++++++++++++---------- 1 file changed, 28 insertions(+), 17 deletions(-) diff --git a/content/docs/infrastructure/network.mdx b/content/docs/infrastructure/network.mdx index 7ffcded..04e7535 100644 --- a/content/docs/infrastructure/network.mdx +++ b/content/docs/infrastructure/network.mdx @@ -4,31 +4,42 @@ icon: Network description: How data gets to the right place --- -As listed in [Servers](./servers), we have two main servers: IN-SMN and IN-ITK. +As detailed in [Servers](./servers), the chapter has two main servers in our +locale: IN-SMN and IN-ITK. IN-SMN is the primary server and runs the vast +majority of our self-hosted infrastructure and services. IN-ITK is managed by +[ITK](https://itk.gg) and is primarily used to host game servers with +[Pterodactyl](https://pterodactyl.io). -IN-SMN is the primary server and runs the vast majority of our self-hosted infrastructure. +## Incoming traffic -IN-ITK is managed by [ITK](https://itk.gg), and is primarily used to host game servers using Pterodactyl. +The router forwards incoming traffic from the internet to IN-SMN or IN-ITK, +depending on the destination port. -The router has port forwarding setup to both IN-SMN and IN-ITK for their respective ports. +HTTP(S) traffic (ports `80` and `443`) and standard SSH (port `22`), is sent to IN-SMN. -Since most games use higher ports numbers, a range of these ports have been forwarded to IN-ITK, thereby not requiring configuration of the router -for most games. - -Since port 22 (standard SSH port) goes to IN-SMN, port 2222 is the port used for SSH to IN-ITK. +SSH for IN-ITK uses port `2222` instead. Since most games use higher-numbered +ports, a range of these ports is forwarded to IN-ITK. This avoids the need to +touch the router configuration for most games. - Since HTTP(S) traffic (port 80 and 443) goes to IN-SMN, hosting websites on - IN-ITK requires IN-SMN to forward it to IN-ITK using - [traefik](in-smn/traefik). + Since HTTP(S) traffic (ports 80 and 443) goes to IN-SMN, hosting websites on + IN-ITK requires IN-SMN to forward it to IN-ITK using [Traefik](in-smn/traefik). -![Server data is sent to IN-ITK. Http, mqtt, and ssh is sent to IN-SMN. Some HTTP traffic is forwarded to IN-ITK by IN-SMN](networkexample.svg) +![Traffic from the internet reaches the router. HTTP, MQTT, and SSH traffic is sent to IN-SMN; game-server traffic is sent to IN-ITK; and Traefik on IN-SMN can forward HTTP traffic to IN-ITK.](networkexample.svg) + +## External hosting -## Netlify +Some websites need better availability than our local servers can guarantee, +such as [kth.it](https://kth.it) and the major committee websites. +These should instead be hosted on an external hosting service, commonly +[Netlify](https://www.netlify.com/) or sometimes [Vercel](https://vercel.com). -Some services/websites need higher availability, such as [kth.it](kth.it) and the major committee websites. -These should be hosted on a high availability service, commonly [Netlify](https://www.netlify.com/). +Since the main [kth.it](https://kth.it) site ([Heim](../software/heim)) +is not hosted locally on IN-SMN, there are two separate DNS records. +One record points the apex domain (`kth.it`) to Netlify +and another points the wildcard `*.kth.it` to the chapter's public IP address. -Since kth.it is on Netlify and not hosted on IN-SMN, we have two DNS records. One for `kth.it` that goes to Netlify, and a wildcard `*.kth.it` that goes to our servers. -As such, when using SSH to the server, use `server.kth.it` as the IP instead of `kth.it`. The DNS records are configured on Netlify. +As a result, `kth.it` resolves to Netlify rather than the local router and +cannot be used to connect to the chapter servers over SSH. Use +`server.kth.it` instead. From 24e365637d3ab0b57789e28933d33bc1c1b4f660 Mon Sep 17 00:00:00 2001 From: Fripe070 <72686066+Fripe070@users.noreply.github.com> Date: Sun, 16 Aug 2026 23:11:07 +0200 Subject: [PATCH 11/14] polish --- .../docs/infrastructure/in-smn/traefik.mdx | 4 ++-- content/docs/infrastructure/servers.mdx | 22 ++++++++++--------- content/docs/infrastructure/sso/index.mdx | 8 +++---- 3 files changed, 18 insertions(+), 16 deletions(-) diff --git a/content/docs/infrastructure/in-smn/traefik.mdx b/content/docs/infrastructure/in-smn/traefik.mdx index 0b0222f..48e927f 100644 --- a/content/docs/infrastructure/in-smn/traefik.mdx +++ b/content/docs/infrastructure/in-smn/traefik.mdx @@ -44,8 +44,8 @@ To leave a site available to the entire internet, omit the middleware label. - Basic Auth is not secure! While it is significantly better than nothing, - anything critical should prefer Authentik. + Basic Auth uses shared, static credentials and does not provide per-user + access control. Use Authentik for sensitive services. ```yaml diff --git a/content/docs/infrastructure/servers.mdx b/content/docs/infrastructure/servers.mdx index 04004a6..4d9cbd1 100644 --- a/content/docs/infrastructure/servers.mdx +++ b/content/docs/infrastructure/servers.mdx @@ -4,6 +4,7 @@ icon: HardDrive --- ## Server: IN-SMN +`ssh @server.kth.it` ### Hardware @@ -19,17 +20,8 @@ OS: Linux Debian --- -## Server: IN-NAS - -### Hardware - -### Software - -OS: TrueNAS - ---- - ## Server: IN-ITK +`ssh -p 2222 @server.kth.it` ### Hardware @@ -42,3 +34,13 @@ Disk: 2 x 240GB Raid-1 (OS), 2 x Toshiba 960GB Raid-1 (storage) ### Software OS: Linux Debian + +--- + +## Server: IN-NAS + +### Hardware + +### Software + +OS: TrueNAS diff --git a/content/docs/infrastructure/sso/index.mdx b/content/docs/infrastructure/sso/index.mdx index 2521823..6e10de1 100644 --- a/content/docs/infrastructure/sso/index.mdx +++ b/content/docs/infrastructure/sso/index.mdx @@ -18,8 +18,8 @@ and displays a dashboard with apps available to the authenticated user. Services that should require authentication to be accessed can use Authentik as middleware through the Traefik proxy, as detailed in the [routing documentation](./in-smn/traefik#adding-authentication). -For the middleware to work, add an application with a corresponding proxy provider -linked to the embedded outpost for the site through the Authentik admin dashboard. +For the middleware to work, create an application with a corresponding proxy +provider, then add that provider to the embedded outpost as described below. @@ -56,9 +56,9 @@ linked to the embedded outpost for the site through the Authentik admin dashboar To decide who has access, configure bindings for the application's provider. You can create bindings for groups and specific users (also policies but we don't use them). - Most groups are sourced from the chapter's [Google Workspace](./google-workspace.mdx) and sync automatically. + Most groups are sourced from the chapter's [Google Workspace](./google-workspace) and sync automatically. Their names should be largely self-explanatory. - A few groups are special and are not defined in Google Workspace, Notably: + A few groups are special and are not defined in Google Workspace, notably: | Group | Who | Why | | ------------------ | ---------------------------------------------------------- | ------------------------------------------------------------------------- | | itsektionen | Everyone who has logged in with a kth.it account | The preferred option when anyone active in the chapter should have access | From 8f99daf9156fafe14055dad9fd32cbbb7afe330c Mon Sep 17 00:00:00 2001 From: TheUsernameOrSmth <105546141+TheUsernameOrSmth@users.noreply.github.com> Date: Mon, 17 Aug 2026 02:37:15 +0200 Subject: [PATCH 12/14] Some extra things --- .../docs/infrastructure/in-smn/traefik.mdx | 23 +++++++++++++++++- content/docs/infrastructure/network.mdx | 6 +++++ content/docs/infrastructure/sso/index.mdx | 2 +- content/docs/infrastructure/sso/loginflow.mdx | 24 ++++++++++++++----- content/docs/locale/guides/soundmixer.mdx | 16 +++++++++---- 5 files changed, 59 insertions(+), 12 deletions(-) diff --git a/content/docs/infrastructure/in-smn/traefik.mdx b/content/docs/infrastructure/in-smn/traefik.mdx index 48e927f..339e8c7 100644 --- a/content/docs/infrastructure/in-smn/traefik.mdx +++ b/content/docs/infrastructure/in-smn/traefik.mdx @@ -59,7 +59,28 @@ To leave a site available to the entire internet, omit the middleware label. ## SSL encryption We use [Let's Encrypt](https://letsencrypt.org/) to obtain signed SSL certificates. -Traefik automatically requests these for the subdomains we use. +Traefik automatically requests these for the domains and subdomains we use. Since these certificates are issued per subdomain rather than for all of `*.kth.it`, the browser will warn about a self-signed certificate if visiting a subdomain where nothing is served. + +### Adding new domains + + + + Ensure that the DNS record points to IN-SMN. + This can be checked by pinging both the domain and `server.kth.it` and comparing the IPs. + You might need to wait a long while for the DNS propagation to finish. + [Insert meme about DNS propagation being slow] + + Note that for unused `*.kth.it` domains this step is already taken care of. + + + Setup the `Host(...)` rule(s) on the traefik configuration. + + + Start the container. Traefik will automatically detect the Hosts and request SSL certificates for them. + + These certificates last for 90 days and are automatically renewed. + + diff --git a/content/docs/infrastructure/network.mdx b/content/docs/infrastructure/network.mdx index 04e7535..c6ae70e 100644 --- a/content/docs/infrastructure/network.mdx +++ b/content/docs/infrastructure/network.mdx @@ -43,3 +43,9 @@ and another points the wildcard `*.kth.it` to the chapter's public IP address. As a result, `kth.it` resolves to Netlify rather than the local router and cannot be used to connect to the chapter servers over SSH. Use `server.kth.it` instead. + +Some subdomains of `kth.it` are also hosted on Netlify, +such as [init.kth.it](https://init.kth.it). +An easy way to find out where a domain is hosted is to simply ping the domain. +If it matches the IP for `kth.it`, it is Netlify, and if it matches `server.kth.it` it is +IN-SMN (or IN-ITK). \ No newline at end of file diff --git a/content/docs/infrastructure/sso/index.mdx b/content/docs/infrastructure/sso/index.mdx index 6e10de1..661abe9 100644 --- a/content/docs/infrastructure/sso/index.mdx +++ b/content/docs/infrastructure/sso/index.mdx @@ -24,7 +24,7 @@ provider, then add that provider to the embedded outpost as described below. Go to the [Applications panel](https://sso.kth.it/if/admin/#/core/applications) - and click "Create with Provider". Give the application a name, slug, and optional icon. + and click "Create with Provider". Give the application a name, slug, and optionally an icon and group. Choose the provider type. When using the Traefik middleware this will be diff --git a/content/docs/infrastructure/sso/loginflow.mdx b/content/docs/infrastructure/sso/loginflow.mdx index 00dade5..daed570 100644 --- a/content/docs/infrastructure/sso/loginflow.mdx +++ b/content/docs/infrastructure/sso/loginflow.mdx @@ -3,15 +3,27 @@ title: Login flow --- - User navigates to app domain. Ex. [https://lmixer.kth.it][1]. - User is redirected to the SSO service at [https://sso.kth.it][2]. - User needs to log in and is redirected to Google sign in. - After sign in user is redirected back to the SSO service. - User is checked against group and roles. + + User navigates to app domain. Ex. [https://lmixer.kth.it][1]. + + + User is redirected to the SSO service at [https://sso.kth.it][2]. + + + User needs to log in and is redirected to Google sign in. + + + After sign in user is redirected back to the SSO service. + + + User is checked against group and roles. + If app is assigned to any group the user belongs to access is granted. - If all OK, redirect back to the app that was requested. + + If all OK, redirect back to the app that was requested. + [1]: https://lmixer.kth.it diff --git a/content/docs/locale/guides/soundmixer.mdx b/content/docs/locale/guides/soundmixer.mdx index cd4c1ec..b9ddf2d 100644 --- a/content/docs/locale/guides/soundmixer.mdx +++ b/content/docs/locale/guides/soundmixer.mdx @@ -5,13 +5,21 @@ title: Sound Mixer ## Loading default settings - Connect to mixer - Load settings + + Connect to mixe + + + Load setting + ## Bar computer input to Kitchen out - Connect to mixer - Set channel sends + + Connect to mixer + + + Set channel sends + From 58b978d40dc764868e32e04e44f6ed0dbdbeac02 Mon Sep 17 00:00:00 2001 From: Fripe070 <72686066+Fripe070@users.noreply.github.com> Date: Mon, 17 Aug 2026 15:19:15 +0200 Subject: [PATCH 13/14] Apply changes suggested by review --- content/docs/infrastructure/network.mdx | 7 +++---- content/docs/locale/guides/soundmixer.mdx | 2 +- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/content/docs/infrastructure/network.mdx b/content/docs/infrastructure/network.mdx index c6ae70e..2ad658f 100644 --- a/content/docs/infrastructure/network.mdx +++ b/content/docs/infrastructure/network.mdx @@ -17,9 +17,8 @@ depending on the destination port. HTTP(S) traffic (ports `80` and `443`) and standard SSH (port `22`), is sent to IN-SMN. -SSH for IN-ITK uses port `2222` instead. Since most games use higher-numbered -ports, a range of these ports is forwarded to IN-ITK. This avoids the need to -touch the router configuration for most games. +Since most games use higher-numbered ports, ports `>=2000` are directed to IN-ITK. +As a consequence, SSH for IN-ITK uses port `2222` instead of the default `22` taken by IN-SMN. Since HTTP(S) traffic (ports 80 and 443) goes to IN-SMN, hosting websites on @@ -48,4 +47,4 @@ Some subdomains of `kth.it` are also hosted on Netlify, such as [init.kth.it](https://init.kth.it). An easy way to find out where a domain is hosted is to simply ping the domain. If it matches the IP for `kth.it`, it is Netlify, and if it matches `server.kth.it` it is -IN-SMN (or IN-ITK). \ No newline at end of file +IN-SMN (or IN-ITK). diff --git a/content/docs/locale/guides/soundmixer.mdx b/content/docs/locale/guides/soundmixer.mdx index b9ddf2d..3046848 100644 --- a/content/docs/locale/guides/soundmixer.mdx +++ b/content/docs/locale/guides/soundmixer.mdx @@ -6,7 +6,7 @@ title: Sound Mixer - Connect to mixe + Connect to mixer Load setting From 5eb09bb0f70003d087d4a8f798806c16232fccaf Mon Sep 17 00:00:00 2001 From: Fripe <72686066+Fripe070@users.noreply.github.com> Date: Tue, 18 Aug 2026 02:24:35 +0000 Subject: [PATCH 14/14] Slightly clarify/reword login flow --- content/docs/infrastructure/sso/loginflow.mdx | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/content/docs/infrastructure/sso/loginflow.mdx b/content/docs/infrastructure/sso/loginflow.mdx index daed570..15f8b19 100644 --- a/content/docs/infrastructure/sso/loginflow.mdx +++ b/content/docs/infrastructure/sso/loginflow.mdx @@ -4,27 +4,25 @@ title: Login flow - User navigates to app domain. Ex. [https://lmixer.kth.it][1]. + User navigates to a protected deployment. Ex. [lmixer.kth.it](https://lmixer.kth.it). - User is redirected to the SSO service at [https://sso.kth.it][2]. + User is redirected to the SSO service at [sso.kth.it](https://sso.kth.it). - User needs to log in and is redirected to Google sign in. + if the user is not already authenticated, they are redirected to Google to sign in. - After sign in user is redirected back to the SSO service. + After signing in, the user is redirected back to the SSO service. - User is checked against group and roles. + Authentik checks whether the user is allowed to access the application. - If app is assigned to any group the user belongs to access is granted. + If the application allows a group the user belongs to, access is granted. - If all OK, redirect back to the app that was requested. + If all OK, redirect back to the original site that was requested. - -[1]: https://lmixer.kth.it -[2]: https://sso.kth.it +