From 1337fae991c2e38a0ce414dac4e94b5dd87f2fd7 Mon Sep 17 00:00:00 2001 From: Djeex Date: Fri, 4 Sep 2026 16:33:37 +0200 Subject: [PATCH] Rework the Serveex intro page and fix icon colors --- content/en/3.serveex/1.introduction.md | 170 +++++++++++++++--- .../1.wireguard.md => 2.core/3.wireguard.md} | 2 +- .../3.serveex/2.core/{3.swag.md => 4.swag.md} | 0 .../{4.tinyauth.md => 3.tinyauth.md} | 93 ++++------ .../{3.pocket-id.md => 4.pocket-id.md} | 54 +++++- .../.navigation.yml | 0 .../1.authentik.md | 0 7 files changed, 237 insertions(+), 82 deletions(-) rename content/en/3.serveex/{3.security/1.wireguard.md => 2.core/3.wireguard.md} (99%) rename content/en/3.serveex/2.core/{3.swag.md => 4.swag.md} (100%) rename content/en/3.serveex/3.security/{4.tinyauth.md => 3.tinyauth.md} (81%) rename content/en/3.serveex/3.security/{3.pocket-id.md => 4.pocket-id.md} (75%) rename content/en/3.serveex/{10.advanced => 91.advanced}/.navigation.yml (100%) rename content/en/3.serveex/{10.advanced => 91.advanced}/1.authentik.md (100%) diff --git a/content/en/3.serveex/1.introduction.md b/content/en/3.serveex/1.introduction.md index 59a55b0..7213ef5 100644 --- a/content/en/3.serveex/1.introduction.md +++ b/content/en/3.serveex/1.introduction.md @@ -15,9 +15,8 @@ navigation: A big thanks to **Nipah** for sharing his infinite knowledge and, above all, for his patience. -::note -**Prerequisites:** - +::note{icon=""} +📋 **Prerequisites:** - Have [an online VPS](https://www.it-connect.fr/les-serveurs-prives-virtuels-vps-pour-les-debutants/) or a local machine: ideally a mini PC (you can find N100 models for around €100), but it also works on a laptop or [a virtual machine](https://openclassrooms.com/fr/courses/2035806-virtualisez-votre-architecture-et-vos-environnements-de-travail/6313946-installez-virtualbox). The [Freebox Delta/Ultra offer virtual machines](https://next.ink/3493/machines-virtuelles-et-freebox-delta-comment-heberger-votre-premiere-page-web/). - Know how to configure [NAT rules on a router and assign DHCP leases](/general/networking/nat) - Know how to configure the [DNS zone of a domain name](/general/networking/dns) @@ -44,11 +43,25 @@ Install and configure Debian 13 Install Docker :: -::card{icon="i-carbon-container-registry" title="Container manager" to="/serveex/core/docker#installer-dockge-pour-gérer-et-déployer-les-conteneurs"} +::card +--- +icon: i-carbon-container-registry +title: Container manager +to: "/serveex/core/docker#installer-dockge-pour-gérer-et-déployer-les-conteneurs" +ui: + icon: text-[#74C2FF] +--- Install and deploy Dockge :: -::card{icon="i-simple-icons-wireguard" title="VPN" to="/serveex/security/wireguard"} +::card +--- +icon: i-simple-icons-wireguard +title: VPN +to: /serveex/security/wireguard +ui: + icon: text-[#88171A] +--- Install and deploy Wireguard :: @@ -66,8 +79,12 @@ Expose your services with SWAG ::card-group -::card{icon="i-noto-key" title="SSO & MFA" to="/serveex/advanced/authentik"} -Install and deploy Authentik +::card{icon="i-noto-locked-with-key" title="Forward Auth" to="/serveex/security/tinyauth"} +Install and deploy TinyAuth +:: + +::card{icon="i-noto-identification-card" title="Passwordless SSO" to="/serveex/security/pocket-id"} +Install and deploy Pocket ID :: ::card{icon="i-logos-cloudflare-icon" title="Zero Trust" to="/serveex/security/cloudflare"} @@ -82,11 +99,25 @@ Install and deploy Cloudflared ::: ::card-group -::card{icon="i-solar-pulse-linear" title="Service Status" to="/serveex/monitoring/uptime-kuma"} +::card +--- +icon: i-solar-pulse-linear +title: Service Status +to: /serveex/monitoring/uptime-kuma +ui: + icon: text-[#5CDD8B] +--- Install and deploy Uptime-Kuma :: -::card{icon="i-lucide-logs" title="Log Management" to="/serveex/monitoring/dozzle"} +::card +--- +icon: i-lucide-logs +title: Log Management +to: /serveex/monitoring/dozzle +ui: + icon: text-[#FFA600] +--- Install and deploy Dozzle :: @@ -94,11 +125,25 @@ Install and deploy Dozzle Install and deploy Speedtest Tracker :: -::card{icon="i-lucide-chart-column-decreasing" title="Resource Status" to="/serveex/monitoring/beszel"} +::card +--- +icon: i-lucide-chart-column-decreasing +title: Resource Status +to: /serveex/monitoring/beszel +ui: + icon: text-[#747bff] +--- Install and deploy Beszel :: -::card{icon="i-lucide-circle-power" title="Wake on Lan" to="/serveex/monitoring/upsnap"} +::card +--- +icon: i-lucide-circle-power +title: Wake on Lan +to: /serveex/monitoring/upsnap +ui: + icon: text-[#5BDAFD] +--- Install and deploy UpSnap :: :: @@ -110,13 +155,38 @@ Install and deploy UpSnap ::: ::card-group -::card{icon="i-simple-icons-jellyfin" title="Media" to="/serveex/media/jellyfin"} +::card +--- +icon: i-simple-icons-jellyfin +title: Media +to: /serveex/media/jellyfin +ui: + icon: text-[#00A4DC] +--- Install and deploy Jellyfin :: -::card{icon="i-cbi-qbittorrent" title="Seedbox" to="/serveex/media/qbittorrent"} +::card +--- +icon: i-cbi-qbittorrent +title: Seedbox +to: /serveex/media/qbittorrent +ui: + icon: text-[#2F67BA] +--- Install and deploy Qbittorrent :: + +::card +--- +icon: i-cbi-radarr +title: Automation +to: /serveex/media/servarr +ui: + icon: text-[#FFCB3D] +--- +Install and deploy the Servarr stack +:: :: ### Cloud Drive & Photos @@ -126,11 +196,25 @@ Install and deploy Qbittorrent ::: ::card-group -::card{icon="i-cib-nextcloud" title="Drive" to="/serveex/cloud/nextcloud"} +::card +--- +icon: i-cib-nextcloud +title: Drive +to: /serveex/cloud/nextcloud +ui: + icon: text-[#0082C9] +--- Install and deploy Nextcloud :: -::card{icon="i-simple-icons-immich" title="Photos" to="/serveex/cloud/immich"} +::card +--- +icon: i-simple-icons-immich +title: Photos +to: /serveex/cloud/immich +ui: + icon: text-[#4250AF] +--- Install and deploy Immich :: :: @@ -142,11 +226,18 @@ Install and deploy Immich ::: ::card-group -::card{icon="i-noto-open-file-folder" title="File Explorer" to="/serveex/files/file-browser"} -Install and deploy file-browser +::card{icon="i-noto-open-file-folder" title="File Explorer" to="/serveex/files/file-browser-quantum"} +Install and deploy File Browser Quantum :: -::card{icon="i-carbon-share" title="Sharing" to="/serveex/files/pingvin"} +::card +--- +icon: i-carbon-share +title: Sharing +to: /serveex/files/pingvin +ui: + icon: text-[#46509E] +--- Install and deploy Pingvin :: :: @@ -162,7 +253,14 @@ Install and deploy Pingvin Install and deploy code-server :: -::card{icon="i-simple-icons-forgejo" title="Git Repository" to="/serveex/development/forgejo"} +::card +--- +icon: i-simple-icons-forgejo +title: Git Repository +to: /serveex/development/forgejo +ui: + icon: text-[#FB923C] +--- Install and deploy Forgejo :: @@ -178,18 +276,42 @@ Install and deploy IT Tools ::: ::card-group -::card{icon="i-cbi-adguard" title="Ad-blocking DNS and Filters" to="/serveex/apps/adguard"} +::card +--- +icon: i-cbi-adguard +title: Ad-blocking DNS and Filters +to: /serveex/apps/adguard +ui: + icon: text-[#68BC71] +--- Install and deploy Adguard Home :: -::card{icon="i-cbi-bitwarden" title="Password Manager" to="/serveex/apps/vaultwarden"} +::card +--- +icon: i-cbi-bitwarden +title: Password Manager +to: /serveex/apps/vaultwarden +ui: + icon: text-[#175DDC] +--- Install and deploy Vaultwarden :: :: +### Advanced + +:::div{class="relative"} +:ellipsis{left=0px width=40rem top=10rem blur=140px} +::: + +::card-group +::card{icon="i-noto-key" title="SSO & MFA" to="/serveex/advanced/authentik"} +Install and deploy Authentik +:: +:: + ## Coming Soon - Homepage, to have all your services at a glance and access them easily -- Mkdocs for your documentation -- Docus, an alternative to Mkdocs -- UpSnap to remotely wake your machines +- Zensical, how to write and organize your own documentation diff --git a/content/en/3.serveex/3.security/1.wireguard.md b/content/en/3.serveex/2.core/3.wireguard.md similarity index 99% rename from content/en/3.serveex/3.security/1.wireguard.md rename to content/en/3.serveex/2.core/3.wireguard.md index 7674120..4081a8d 100644 --- a/content/en/3.serveex/3.security/1.wireguard.md +++ b/content/en/3.serveex/2.core/3.wireguard.md @@ -39,7 +39,7 @@ You *can* allow VPN clients to share access to their local networks, but we won So only VPN-connected devices can communicate with each other on the VPN, not with other local devices outside the VPN. ## Server Setup -::note +::note{icon=""} 📋 **Pre-flight Checklist:** - Ensure port `51820 UDP` is free on your server and correctly forwarded from your router (`51820 UDP -> Server`). diff --git a/content/en/3.serveex/2.core/3.swag.md b/content/en/3.serveex/2.core/4.swag.md similarity index 100% rename from content/en/3.serveex/2.core/3.swag.md rename to content/en/3.serveex/2.core/4.swag.md diff --git a/content/en/3.serveex/3.security/4.tinyauth.md b/content/en/3.serveex/3.security/3.tinyauth.md similarity index 81% rename from content/en/3.serveex/3.security/4.tinyauth.md rename to content/en/3.serveex/3.security/3.tinyauth.md index 02d1d70..cf1f4d0 100644 --- a/content/en/3.serveex/3.security/4.tinyauth.md +++ b/content/en/3.serveex/3.security/3.tinyauth.md @@ -10,16 +10,11 @@ description: Install TinyAuth, a lightweight forward-auth proxy, and pair it wit ![tinyauth](/img/serveex/tinyauth.png) -It supports a simple local username/password login out of the box, and can also delegate login to an external OIDC provider. Here we'll use [Pocket ID](/serveex/security/pocket-id), so anyone visiting a protected app first authenticates with a passkey via Pocket ID, then gets forwarded through. +It supports a simple local username/password login out of the box, which is what we'll set up here. It can also delegate login to an external OIDC provider like [Pocket ID](/serveex/security/pocket-id) instead, so anyone visiting a protected app authenticates with a passkey via Pocket ID and then gets forwarded through: install Pocket ID afterwards and follow [its guide](/serveex/security/pocket-id#connecting-pocket-id-to-tinyauth) to connect the two. - [TinyAuth documentation](https://tinyauth.app/docs) - [TinyAuth on GitHub](https://github.com/tinyauthapp/tinyauth) -::note - -This guide assumes you've already installed [Pocket ID](/serveex/security/pocket-id). You can skip the Pocket ID sections below and use TinyAuth with just a local username/password instead. -:: - ## Installation ::file-tree @@ -103,6 +98,42 @@ Deploy the stack. The local interface is available at `http://yourserverip:3000` ### Done ! :: +## Enabling Two-Factor Authentication +TinyAuth can require a TOTP code from an authenticator app (Google Authenticator, Aegis...) alongside the local password, per user. This is a property of the user entry itself, not a toggle in the web UI. + +::steps{level="3"} +### Generate a TOTP secret + +```bash [Terminal] +sudo docker run -i -t --rm ghcr.io/tinyauthapp/tinyauth:v5 totp generate --interactive +``` + +Enter the `username:hash` pair you generated during installation. TinyAuth prints a QR code to scan with your authenticator app, then outputs the updated login string as `username:hash:secret`. + +::note + +Both `docker run` and `docker exec` need the `-it` flags here: the command is interactive and renders the QR code in the terminal, which needs a TTY (and a wide enough window) to display correctly. +:: + +### Update your environment variable + +Replace that user's entry in `TINYAUTH_AUTH_USERS` with the new `username:hash:secret` string, then redeploy the stack. + +::tip{icon=""} +✨ __Tip:__ Verify the flow works before relying on it: + +```bash [Terminal] +sudo docker run -i -t --rm ghcr.io/tinyauthapp/tinyauth:v5 user verify --interactive +``` + +It re-prompts for the username, password, and current 6-digit code. +:: + +### Done ! +:: + +From now on, that user needs both their password and a valid code from their authenticator app to log in. + ## Exposing TinyAuth with Swag TinyAuth needs its own subdomain: it's the page users land on before being forwarded to the app they actually want. @@ -192,56 +223,6 @@ __If it fails:__ check your firewall rules. ### Done ! :: -## Connecting TinyAuth to Pocket ID -::steps{level="3"} -### Register TinyAuth as an OIDC client - -First, [register TinyAuth as an OIDC client in Pocket ID](/serveex/security/pocket-id#registering-an-oidc-client), using this callback URL: - -```text -https://tinyauth.mydomain.com/api/oauth/callback/pocketid -``` - -### Add the Pocket ID provider - -Copy the __Client ID__ and __Client Secret__ Pocket ID gives you, then edit TinyAuth's `.env` file: - -```bash [Terminal] -sudo nano /docker/tinyauth/.env -``` - -Add the following: - -```properties [.env] -TINYAUTH_OAUTH_PROVIDERS_POCKETID_NAME=Pocket ID -TINYAUTH_OAUTH_PROVIDERS_POCKETID_CLIENTID= -TINYAUTH_OAUTH_PROVIDERS_POCKETID_CLIENTSECRET= -TINYAUTH_OAUTH_PROVIDERS_POCKETID_AUTHURL=https://id.mydomain.com/authorize -TINYAUTH_OAUTH_PROVIDERS_POCKETID_TOKENURL=https://id.mydomain.com/api/oidc/token -TINYAUTH_OAUTH_PROVIDERS_POCKETID_USERINFOURL=https://id.mydomain.com/api/oidc/userinfo -TINYAUTH_OAUTH_PROVIDERS_POCKETID_REDIRECTURL=https://tinyauth.mydomain.com/api/oauth/callback/pocketid -TINYAUTH_OAUTH_PROVIDERS_POCKETID_SCOPES=openid email profile -``` - -| Variable | Value | -|----------|-------| -| `CLIENTID`{lang=properties} | The client ID copied from Pocket ID | -| `CLIENTSECRET`{lang=properties} | The client secret copied from Pocket ID | -| `AUTHURL` / `TOKENURL` / `USERINFOURL`{lang=properties} | Pocket ID's public URL, with the paths shown above | - -Press :kbd{value="Ctrl+O"}, then :kbd{value="Enter"} to save, and :kbd{value="Ctrl+X"} to exit. - -### Redeploy the stack - -Redeploy the TinyAuth stack. On your next visit to `https://tinyauth.mydomain.com`, you'll see a "Login with Pocket ID" option alongside the local login form. - -::tip{icon=""} -✨ To skip straight to Pocket ID and hide the local login form, add `TINYAUTH_OAUTH_AUTOREDIRECT=pocketid` to the same `.env` file. -:: - -### Done ! -:: - ## Protecting an app via reverse proxy Swag doesn't ship a ready-made include file for TinyAuth, so we'll add the forward-auth check directly to the app's own `*.subdomain.conf`. We'll use Dockge as an example. diff --git a/content/en/3.serveex/3.security/3.pocket-id.md b/content/en/3.serveex/3.security/4.pocket-id.md similarity index 75% rename from content/en/3.serveex/3.security/3.pocket-id.md rename to content/en/3.serveex/3.security/4.pocket-id.md index 8cf01bf..027e21a 100644 --- a/content/en/3.serveex/3.security/3.pocket-id.md +++ b/content/en/3.serveex/3.security/4.pocket-id.md @@ -226,4 +226,56 @@ Save, then copy the generated __Client ID__ and __Client Secret__. You'll need t ### Done ! :: -Pocket ID is ready to act as your OIDC provider. Head to the [TinyAuth guide](/serveex/security/tinyauth) to use it as a forward-auth login page for the rest of your apps. +## Connecting Pocket ID to TinyAuth +[TinyAuth](/serveex/security/tinyauth) can delegate its login to Pocket ID instead of (or alongside) its local username/password, so anyone visiting a protected app authenticates with a passkey and gets forwarded through. + +::steps{level="3"} +### Register TinyAuth as an OIDC client + +[Register an OIDC client](#registering-an-oidc-client) named `TinyAuth`, using this callback URL: + +```text +https://tinyauth.mydomain.com/api/oauth/callback/pocketid +``` + +### Add the Pocket ID provider in TinyAuth + +Copy the __Client ID__ and __Client Secret__ Pocket ID gives you, then edit TinyAuth's `.env` file: + +```bash [Terminal] +sudo nano /docker/tinyauth/.env +``` + +Add the following: + +```properties [.env] +TINYAUTH_OAUTH_PROVIDERS_POCKETID_NAME=Pocket ID +TINYAUTH_OAUTH_PROVIDERS_POCKETID_CLIENTID= +TINYAUTH_OAUTH_PROVIDERS_POCKETID_CLIENTSECRET= +TINYAUTH_OAUTH_PROVIDERS_POCKETID_AUTHURL=https://id.mydomain.com/authorize +TINYAUTH_OAUTH_PROVIDERS_POCKETID_TOKENURL=https://id.mydomain.com/api/oidc/token +TINYAUTH_OAUTH_PROVIDERS_POCKETID_USERINFOURL=https://id.mydomain.com/api/oidc/userinfo +TINYAUTH_OAUTH_PROVIDERS_POCKETID_REDIRECTURL=https://tinyauth.mydomain.com/api/oauth/callback/pocketid +TINYAUTH_OAUTH_PROVIDERS_POCKETID_SCOPES=openid email profile +``` + +| Variable | Value | +|----------|-------| +| `CLIENTID`{lang=properties} | The client ID copied from Pocket ID | +| `CLIENTSECRET`{lang=properties} | The client secret copied from Pocket ID | +| `AUTHURL` / `TOKENURL` / `USERINFOURL`{lang=properties} | Pocket ID's public URL, with the paths shown above | + +Press :kbd{value="Ctrl+O"}, then :kbd{value="Enter"} to save, and :kbd{value="Ctrl+X"} to exit. + +### Redeploy the stack + +Redeploy the TinyAuth stack. On your next visit to `https://tinyauth.mydomain.com`, you'll see a "Login with Pocket ID" option alongside the local login form. + +::tip{icon=""} +✨ To skip straight to Pocket ID and hide the local login form, add `TINYAUTH_OAUTH_AUTOREDIRECT=pocketid` to the same `.env` file. +:: + +### Done ! +:: + +That's it! TinyAuth now offers passwordless login via Pocket ID for every app it protects. diff --git a/content/en/3.serveex/10.advanced/.navigation.yml b/content/en/3.serveex/91.advanced/.navigation.yml similarity index 100% rename from content/en/3.serveex/10.advanced/.navigation.yml rename to content/en/3.serveex/91.advanced/.navigation.yml diff --git a/content/en/3.serveex/10.advanced/1.authentik.md b/content/en/3.serveex/91.advanced/1.authentik.md similarity index 100% rename from content/en/3.serveex/10.advanced/1.authentik.md rename to content/en/3.serveex/91.advanced/1.authentik.md