From 43acb3bf76f0ec6ebafa33c4b8148d619b9406aa Mon Sep 17 00:00:00 2001 From: wizzdom Date: Wed, 13 Mar 2024 04:49:14 +0000 Subject: [PATCH] add QoL features: tags, social embed, better search, improved toc (#29) * mkdocs: add various quality of life features * add frontmatter, tags, fix links * fix excess newlines * tags.md: add comment on why it exists --- .github/workflows/ci.yml | 2 +- .gitignore | 2 ++ docs/hardware/aperture/about.md | 13 +++++++-- docs/hardware/aperture/chell.md | 9 ++++++ docs/hardware/aperture/glados.md | 9 ++++++ docs/hardware/aperture/images.md | 9 ++++++ docs/hardware/aperture/index.md | 8 ++++++ docs/hardware/aperture/johnson.md | 9 ++++++ docs/hardware/aperture/wheatley.md | 9 ++++++ docs/hardware/azazel.md | 10 +++++++ docs/hardware/nix/hardcase.md | 9 ++++++ docs/hardware/nix/icarus.md | 10 +++++++ docs/hardware/nix/motherlode.md | 11 ++++++++ docs/hardware/paphos.md | 11 ++++++++ docs/hardware/pygmalion.md | 9 ++++++ docs/hardware/zeus.md | 12 +++++++- docs/services/api.md | 7 +++++ docs/services/bastion-vm.md | 10 +++++++ docs/services/bind.md | 10 +++++++ docs/services/exposed.md | 11 +++++++- docs/services/index.md | 2 +- docs/services/irc.md | 44 ++++++++---------------------- docs/services/socs.md | 7 ++--- docs/stylesheets/extra.css | 12 ++++++++ docs/tags.md | 3 ++ mkdocs.yml | 12 ++++++++ requirements.txt | 8 ++++++ 27 files changed, 225 insertions(+), 43 deletions(-) create mode 100644 docs/tags.md create mode 100644 requirements.txt diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 68eb583f..30e00547 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -25,5 +25,5 @@ jobs: path: .cache restore-keys: | mkdocs-material- - - run: pip install mkdocs-material mkdocs-git-revision-date-localized-plugin mkdocs-awesome-pages-plugin mkdocs-callouts material-plausible-plugin mkdocs-glightbox mkdocs-redirects + - run: pip install -r requirements.txt - run: mkdocs gh-deploy --force diff --git a/.gitignore b/.gitignore index 9cb4c959..4ef0e600 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,5 @@ site/ docs/.obsidian/workspace.json docs/.obsidian/graph.json +.cache/ +venv/ diff --git a/docs/hardware/aperture/about.md b/docs/hardware/aperture/about.md index be488e3a..ed539778 100644 --- a/docs/hardware/aperture/about.md +++ b/docs/hardware/aperture/about.md @@ -1,3 +1,10 @@ +--- +title: About Aperture +tags: + - aperture + - hardware +--- + # About Aperture Aperture is Redbrick's fleet of hardware that was installed in May 2022 by `distro`, `pints`, `skins`, `cawnj`, `ymacomp` and `arkues`. @@ -6,9 +13,9 @@ It consists of: - 3x Dell R6515 - [`glados`](glados.md), [`wheatley`](wheatley.md), [`chell`](chell.md) - | CPU | RAM | Storage | - |:-----------------------------------------:|:---------------------------------:|:--------------------------------:| - | AMD 7302P 3GHz, 16C/32T, 128M, 155W, 3200 | 2x 16GB RDIMM, 3200MT/s Dual Rank | 4x 2TB SATA HDDs (hardware RAID) | +| CPU | RAM | Storage | +| ----------------------------------------- | --------------------------------- | -------------------------------- | +| AMD 7302P 3GHz, 16C/32T, 128M, 155W, 3200 | 2x 16GB RDIMM, 3200MT/s Dual Rank | 4x 2TB SATA HDDs (hardware RAID) | - 2x Ubiquiti USW Pro - `rivendell`, `isengard` - 1x Ubiquiti UDM Pro - `mordor` diff --git a/docs/hardware/aperture/chell.md b/docs/hardware/aperture/chell.md index 49ceb2c5..6b468769 100644 --- a/docs/hardware/aperture/chell.md +++ b/docs/hardware/aperture/chell.md @@ -1,3 +1,12 @@ +--- +title: Chell +tags: + - hardware + - aperture + - chell + - details +--- + # Chell ## Details diff --git a/docs/hardware/aperture/glados.md b/docs/hardware/aperture/glados.md index c69a58fe..5baeaf10 100644 --- a/docs/hardware/aperture/glados.md +++ b/docs/hardware/aperture/glados.md @@ -1,3 +1,12 @@ +--- +title: Glados +tags: + - hardware + - aperture + - glados + - details +--- + # Glados ## Details diff --git a/docs/hardware/aperture/images.md b/docs/hardware/aperture/images.md index 85a70d15..f2f6259e 100644 --- a/docs/hardware/aperture/images.md +++ b/docs/hardware/aperture/images.md @@ -1,3 +1,12 @@ +--- +title: Images +tags: + - hardware + - aperture + - install + - images +--- + # Images ## Servers diff --git a/docs/hardware/aperture/index.md b/docs/hardware/aperture/index.md index 41d3f4db..3af9fb68 100644 --- a/docs/hardware/aperture/index.md +++ b/docs/hardware/aperture/index.md @@ -1,3 +1,11 @@ +--- +title: Aperture +tags: + - aperture + - details + - getting-started +--- + # Aperture ## What is Aperture? diff --git a/docs/hardware/aperture/johnson.md b/docs/hardware/aperture/johnson.md index ab9d2d5f..46b6d99f 100644 --- a/docs/hardware/aperture/johnson.md +++ b/docs/hardware/aperture/johnson.md @@ -1,3 +1,12 @@ +--- +title: Johnson +tags: + - aperture + - hardware + - johnson + - details +--- + # Johnson ## Details diff --git a/docs/hardware/aperture/wheatley.md b/docs/hardware/aperture/wheatley.md index 75d37ba1..8da637e9 100644 --- a/docs/hardware/aperture/wheatley.md +++ b/docs/hardware/aperture/wheatley.md @@ -1,3 +1,12 @@ +--- +title: Wheatley +tags: + - aperture + - hardware + - wheatley + - details +--- + # Wheatley ## Details diff --git a/docs/hardware/azazel.md b/docs/hardware/azazel.md index b56604d9..8a7809ec 100644 --- a/docs/hardware/azazel.md +++ b/docs/hardware/azazel.md @@ -1,3 +1,13 @@ +--- +title: Azazel +tags: + - login-box + - hardware + - azazel + - details + - debian +--- + # Azazel ## Details diff --git a/docs/hardware/nix/hardcase.md b/docs/hardware/nix/hardcase.md index 44962f6a..1b2a16d1 100644 --- a/docs/hardware/nix/hardcase.md +++ b/docs/hardware/nix/hardcase.md @@ -1,3 +1,12 @@ +--- +title: Hardcase +tags: + - nixos + - hardware + - details + - hardcase +--- + # Hardcase ## Details diff --git a/docs/hardware/nix/icarus.md b/docs/hardware/nix/icarus.md index 948d37c3..2ab4b0dc 100644 --- a/docs/hardware/nix/icarus.md +++ b/docs/hardware/nix/icarus.md @@ -1,3 +1,13 @@ +--- +title: Icarus +tags: + - nixos + - hardware + - icarus + - daedalus + - details +--- + # Icarus Daedalus and Icarus ~~are~~ were twins ~~and thus share documentation.~~ diff --git a/docs/hardware/nix/motherlode.md b/docs/hardware/nix/motherlode.md index 46c88251..44ea4a19 100644 --- a/docs/hardware/nix/motherlode.md +++ b/docs/hardware/nix/motherlode.md @@ -1,3 +1,14 @@ +--- +title: Motherlode +tags: + - nixos + - hardware + - motherlode + - details + - qemu + - libvirt +--- + # Motherlode ## Details diff --git a/docs/hardware/paphos.md b/docs/hardware/paphos.md index bd5e06e2..efea1bf2 100644 --- a/docs/hardware/paphos.md +++ b/docs/hardware/paphos.md @@ -1,3 +1,14 @@ +--- +title: Paphos +tags: + - hardware + - paphos + - details + - dns + - bind + - ubuntu +--- + # Paphos ## Details diff --git a/docs/hardware/pygmalion.md b/docs/hardware/pygmalion.md index 4509418e..c83c63ee 100644 --- a/docs/hardware/pygmalion.md +++ b/docs/hardware/pygmalion.md @@ -1,3 +1,12 @@ +--- +title: Pygmalion +tags: + - login-box + - hardware + - pygmalion + - ubuntu +--- + # Pygmalion ## Details diff --git a/docs/hardware/zeus.md b/docs/hardware/zeus.md index 070b5caa..95ab58f5 100644 --- a/docs/hardware/zeus.md +++ b/docs/hardware/zeus.md @@ -1,3 +1,13 @@ +--- +title: Zeus +tags: + - hardware + - zeus + - details + - docker + - ubuntu +--- + # Zeus ## Details @@ -21,5 +31,5 @@ - [Admin API](../services/api.md) at: [api.redbrick.dcu.ie](https://api.redbrick.dcu.ie) - brickbot2 - Secretary's email generator at: [generator.redbrick.dcu.ie](https://generator.redbrick.dcu.ie) -- [CodiMD](../services/codimd.md) at: [md.redbrick.dcu.ie](https://md.redbrick.dcu.ie) +- [CodiMD](../services/md.md) at: [md.redbrick.dcu.ie](https://md.redbrick.dcu.ie) - all of this is routed through [traefik](../services/traefik.md) as a reverse proxy diff --git a/docs/services/api.md b/docs/services/api.md index 406ee4bf..8772af2d 100644 --- a/docs/services/api.md +++ b/docs/services/api.md @@ -1,3 +1,10 @@ +--- +title: API +tags: + - services + - api +--- + # API ## Redbrick Administrator Web API diff --git a/docs/services/bastion-vm.md b/docs/services/bastion-vm.md index 93813f76..8b7b4914 100644 --- a/docs/services/bastion-vm.md +++ b/docs/services/bastion-vm.md @@ -1,3 +1,13 @@ +--- +title: Bastion VM +tags: + - aperture + - services + - nomad + - vm + - ingress +--- + # Bastion VM This VM is an ephemeral machine that can be placed on any nomad client that has the qemu driver enabled. diff --git a/docs/services/bind.md b/docs/services/bind.md index 87f1679a..191f50fb 100644 --- a/docs/services/bind.md +++ b/docs/services/bind.md @@ -1,3 +1,13 @@ +--- +title: Bind9 +tags: + - services + - dns +author: + - distro + - ylmcc +--- + # Bind9 - `distro`, `ylmcc` Bind9 is our DNS provider. Currently it runs on [`paphos`](../hardware/paphos.md), but this may change in the near future. diff --git a/docs/services/exposed.md b/docs/services/exposed.md index 6a23cdef..d5284e25 100644 --- a/docs/services/exposed.md +++ b/docs/services/exposed.md @@ -1,3 +1,12 @@ +--- +title: Services Exposed to the Internet +author: + - wizzdom +tags: + - services + - exposed +--- + # Services Exposed to the Internet - `wizzdom` Firstly, it's important to mention that Redbrick is currently split in 2 parts: @@ -40,7 +49,7 @@ Firstly, it's important to mention that Redbrick is currently split in 2 parts: - [Wetty](servers.md#Logging%20in%20to%20Wetty) at: [wetty.redbrick.dcu.ie](https://wetty.redbrick.dcu.ie) - [Admin API](api.md) at: [api.redbrick.dcu.ie](https://api.redbrick.dcu.ie) - Secretary's email generator at: [generator.redbrick.dcu.ie](https://generator.redbrick.dcu.ie) - - [CodiMD](codimd.md) at: [md.redbrick.dcu.ie](https://md.redbrick.dcu.ie) + - [CodiMD](md.md) at: [md.redbrick.dcu.ie](https://md.redbrick.dcu.ie) - all of this is routed through [traefik](traefik.md) as a reverse proxy - [paphos](../hardware/paphos.md) - `136.206.15.53` - **OS**: Ubuntu 14.04 LTS diff --git a/docs/services/index.md b/docs/services/index.md index de224841..6cf4cdbc 100644 --- a/docs/services/index.md +++ b/docs/services/index.md @@ -5,7 +5,7 @@ Here you will find a list of all the services Redbrick runs, along with some con - [api](api.md) - [bastion-vm](bastion-vm.md) - [bind](bind.md) -- [codimd](codimd.md) +- [md](md.md) - [consul](consul.md) - [gitea](gitea.md) - [irc](irc.md) diff --git a/docs/services/irc.md b/docs/services/irc.md index c82c66d6..758235bd 100644 --- a/docs/services/irc.md +++ b/docs/services/irc.md @@ -2,54 +2,37 @@ ## Redbrick InspIRCd -In 2016/2017 we began work to move to InspIRCd. This was due to the complications in ircd-hybrid and how old it was. -These complications stopped new netsocs joining us so we all agreed to move irc. $ 4 years later after multiple attempts -we had not migrated. Until TCD decided to shutdown their server breaking the network. +In 2016/2017 we began work to move to InspIRCd. This was due to the complications in ircd-hybrid and how old it was. These complications stopped new netsocs joining us so we all agreed to move irc. $ 4 years later after multiple attempts we had not migrated. Until TCD decided to shutdown their server breaking the network. We run Inspircd v3 on Metharme. InspIRCd's docs can be found [here](https://docs.inspircd.org/) for configuration specifics. -IRC is available at `irc.redbrick.dcu.ie` on port `6697`. SSL is required for connection, we do not support non-SSL. +IRC is available at `irc.redbrick.dcu.ie` on port `6697`. SSL is required for connection, we do not support non-SSL. When connecting from a redbrick server a user will be automatically logged in. If connecting from an external server a user must pass their password on login. -When connecting from a redbrick server a user will be automatically logged in. If connecting from an external server a -user must pass their password on login. - -For the purpose of external peering of other servers the port `7001` is expose as well. Similarly to clients we only -support SSL on this port. +For the purpose of external peering of other servers the port `7001` is exposed as well. Similarly to clients we only support SSL on this port. For docs on connecting and using an IRC client please refer to the [wiki](https://wiki.redbrick.dcu.ie/index.php/IRC). ## Installation -InspIRCd is installed with Nix. There is no Nix package for InspIRCd so we compile a specific git tag from source. See -[Nix package](https://github.com/redbrick/nix-configs/tree/master/packages/inspircd) for details on how it is compiled. - -Given we only support SSL and require LDAP, we need to enable both at compile time. +InspIRCd is installed with Nix. There is no Nix package for InspIRCd so we compile a specific git tag from source. See [Nix package](https://github.com/redbrick/nix-configs/tree/master/packages/inspircd) for details on how it is compiled. Given we only support SSL and require LDAP, we need to enable both at compile time. ## Configuration -InspIRCd's configuration is in Nix [here](https://github.com/redbrick/nix-configs/blob/master/services/ircd/inspircd/conf.nix). -This config will be converted to xml on disc. +InspIRCd's configuration is in Nix [here](https://github.com/redbrick/nix-configs/blob/master/services/ircd/inspircd/conf.nix). This config will be converted to xml on disc. ### Important Configuration -_oper_ is a list of admin users on the irc server. Their `OPER` password will need to be manually hashed with -`hmac-sha256`, and placed in a secret on the server to be read in by inspircd. - -_ldapwhitelist_ is a list of cidr addresses that do no require authentication. The list consists of Redbrick public and -private addresses as well as `oldsoc`. - -_link_ is a list of all servers we peer with including the anope services server that runs on the same box. +- _oper_ is a list of admin users on the irc server. Their `OPER` password will need to be manually hashed with `hmac-sha256`, and placed in a secret on the server to be read in by inspircd. +- _ldapwhitelist_ is a list of cidr addresses that do no require authentication. The list consists of Redbrick public and private addresses as well as `oldsoc`. +- _link_ is a list of all servers we peer with including the anope services server that runs on the same box. ### oldsoc.net -`oldsoc.net` is a server run by old TCD netsocers. All the users on it are the remaining TCD associates following the -shutdown of TCD IRCd. This server is maintained by its own users and has explicit permission to join IRC without LDAP auth. +`oldsoc.net` is a server run by old TCD netsocers. All the users on it are the remaining TCD associates following the shutdown of TCD IRCd. This server is maintained by its own users and has explicit permission to join IRC without LDAP auth. ## Anope -Redbrick runs Anope services for the entire network. As with -[inspircd we compile](https://github.com/redbrick/nix-configs/tree/master/packages/inspircd) from source. Refer to anopes -[github docs](https://github.com/anope/anope/tree/2.0/docs) for configuration specifics. +Redbrick runs Anope services for the entire network. As with [inspircd we compile](https://github.com/redbrick/nix-configs/tree/master/packages/inspircd) from source. Refer to anopes [github docs](https://github.com/anope/anope/tree/2.0/docs) for configuration specifics. Our current Anope is configured with standard mods of chanserv, nickserv and operserv. All config is in [here](https://github.com/redbrick/nix-configs/tree/master/services/ircd/anope/confs). @@ -57,9 +40,6 @@ Anope stores all info in a custom db file on disk. ## Discord Bridge - `butlerx` -We run a [bridge](https://github.com/qaisjp/go-discord-irc) between the Redbrick Discord and irc. The configuration for -this is [here](https://github.com/redbrick/nix-configs/tree/master/services/ircd/discord/conf.nix). +We run a [bridge](https://github.com/qaisjp/go-discord-irc) between the Redbrick Discord and irc. The configuration for this is [here](https://github.com/redbrick/nix-configs/tree/master/services/ircd/discord/conf.nix). -The bridge adds all users from discord with the suffix `_d2` and all irc users appear as them self but tagged as a bot -in discord. Not all discord channels are on IRC, the config above contains a mapping of irc channels to discord channels -id's. This needs to be manually updated to add more channels. +The bridge adds all users from discord with the suffix `_d2` and all irc users appear as them self but tagged as a bot in discord. Not all discord channels are on IRC, the config above contains a mapping of irc channels to discord channels id's. This needs to be manually updated to add more channels. diff --git a/docs/services/socs.md b/docs/services/socs.md index ae6af893..f275a2a5 100644 --- a/docs/services/socs.md +++ b/docs/services/socs.md @@ -1,7 +1,6 @@ # Socs Using Redbrick Infrastructure - MPS/DCUfm - [`icecast`](icecast.md) -- MPS/TheCollegeView - https://thecollegeview.ie - `wordpress` -- DCU Style - https://thelookonline.dcu.ie - `wordpress` -- DCU Solar Racing - https://solarracing.ie -- +- MPS/TheCollegeView - [TheCollegeView](https://thecollegeview.ie) - `wordpress` +- DCU Style - [The Look](https://thelookonline.dcu.ie) - `wordpress` +- DCU Solar Racing - [Solarracing.ie](https://solarracing.ie) diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index 47a055f4..1780dab2 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -9,3 +9,15 @@ [data-md-color-scheme="slate"] * { --md-typeset-a-color: #d62e2e; } + +@keyframes logo { + 0%, 40%, 80%, 100% { + transform: scale(1); + } + 20%, 60% { + transform: scale(1.5); + } +} +.md-logo { + animation: logo 1000ms 1; +} diff --git a/docs/tags.md b/docs/tags.md new file mode 100644 index 00000000..f8c2d7ef --- /dev/null +++ b/docs/tags.md @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index eef1deee..45a54b4e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,5 +1,6 @@ site_name: Redbrick Docs site_url: https://docs.redbrick.dcu.ie/ +site_description: The home for all Redbrick technical documentation repo_url: https://github.com/redbrick/docs repo_name: redbrick/docs use_directory_urls: true @@ -17,6 +18,12 @@ theme: - navigation.indexes - content.code.copy - content.code.annotate + - search.highlight + - search.share + - search.suggest + - toc.follow + - toc.integrate + palette: - media: "(prefers-color-scheme)" toggle: @@ -42,7 +49,10 @@ plugins: - callouts - glightbox - search + - social - material-plausible + - tags: + tags_file: tags.md - git-revision-date-localized: type: timeago - redirects: @@ -77,6 +87,8 @@ markdown_extensions: anchor_linenums: true line_spans: __span pygments_lang_class: true + - toc: + permalink: true copyright: Redbrick Docs diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..4eb5d771 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,8 @@ +mkdocs-material +mkdocs-git-revision-date-localized-plugin +mkdocs-awesome-pages-plugin +mkdocs-callouts +material-plausible-plugin +mkdocs-glightbox +mkdocs-redirects +mkdocs-material[imaging]