Merge pull request #1 from Huskydog9988/misc-changes

Improve OIDC docs plus add guide

docs/astro.config.mjs

@@ -16,12 +16,23 @@ export default defineConfig({
       ],
       title: "Drop OSS",
       logo: { src: "./src/assets/wordmark.png", replacesTitle: true },
+      tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 4 },
       social: [
         {
           icon: "github",
           label: "GitHub",
           href: "https://github.com/Drop-OSS/",
         },
+        {
+          icon: "discord",
+          label: "Discord",
+          href: "https://discord.gg/NHx46XKJWA",
+        },
+        {
+          icon: "matrix",
+          label: "Matrix",
+          href: "https://matrix.to/#/%23drop-oss:matrix.org",
+        },
       ],
       sidebar: [
         {
@@ -54,10 +65,7 @@ export default defineConfig({
             },
             {
               label: "Going further",
-              items: [
+              autogenerate: { directory: "admin/going-further" },
-                { slug: "admin/going-further/importing-update" },
-                { slug: "admin/going-further/emulators" },
-              ],
             },
             {
               label: "Metadata",

docs/public/robots.txt

@@ -0,0 +1,4 @@
+User-agent: *
+Allow: /
+
+Sitemap: https://docs-next.droposs.org/sitemap-index.xml

docs/src/content/docs/admin/authentication/oidc.md

@@ -8,7 +8,7 @@ OpenID Connect is a OAuth2 extension support by most identity providers.
 
 To configure OIDC, you must set the following environment variables:
 
-| Variable                             | Usage                                                                                                                                  |
+| Variable                             | Description                                                                                                                            |
 | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
 | `OIDC_CLIENT_ID`                     | Client ID from your identity provider.                                                                                                 |
 | `OIDC_CLIENT_SECRET`                 | Client secret from your identity provider.                                                                                             |
@@ -25,13 +25,19 @@ And then, you must configure **either**:
 
 #### Use `OIDC_WELLKNOWN`
 
-A unprotected endpoint that returns a OIDC well-known JSON. Fetched on startup
+A unprotected endpoint that returns a OIDC well-known JSON. Fetched on startup.
+
+For example if you used authentik, your OIDC well-known endpoint would be: `https://authentik.tld/application/o/<slug>/.well-known/openid-configuration`.
 
 ---
 
 #### Provide options individually
 
-| Variable             | Usage                                                                     |
+:::caution
+Drop recommends using the OIDC well-known option **instead** of manually specifying each endpoint. This should only be used if your OIDC provider does not support the well-known format.
+:::
+
+| Variable             | Description                                                               |
 | -------------------- | ------------------------------------------------------------------------- |
 | `OIDC_AUTHORIZATION` | Authorization endpoint. Usually ends with `authorize`.                    |
 | `OIDC_TOKEN`         | Token endpoint. Usually ends with `token`.                                |
@@ -42,4 +48,10 @@ A unprotected endpoint that returns a OIDC well-known JSON. Fetched on startup
 
 ## Redirect URL
 
-Drop uses the `EXTERNAL_URL` environment variable to create the callback URL: `$EXTERNAL_URL/auth/callback/oidc`.
+Drop uses the `EXTERNAL_URL` environment variable to create the callback URL: `$EXTERNAL_URL/api/v1/auth/odic/callback`.
+
+For example: if `EXTERNAL_URL` was set to `http://localhost:3000/`, then the redirect URL would be `http://localhost:3000/api/v1/auth/odic/callback`.
+
+## Logout URL
+
+Drop supports OIDC back-channel logout, enabling the OIDC provider to logout users. Using the example above, the back-channel logout URL would be `http://localhost:3000/api/v1/auth/odic/logout`.

docs/src/content/docs/admin/going-further/setting-up-oidc.mdx

@@ -0,0 +1,42 @@
+---
+title: Setting up OIDC
+---
+
+:::note
+You can find reference information in the [OIDC authentication docs](/admin/authentication/oidc/).
+:::
+
+## Authentik
+
+For this guide, `drop.tld` is used as a placeholder for your Drop instance's domain. Make sure to replace it with your actual domain.
+
+### In Authentik
+
+1. Go to the admin dashboard
+1. In the applications section, click Create with Provider
+   Set any name and slug you want
+1. Select OpenID Connect as the provider type
+1. Configure the provider
+   - Copy the client ID, and secret, you'll need them for Drop
+   - Set the redirect as `Strict` and the URL to `https://drop.tld/api/v1/auth/odic/callback`
+   - Set the logout URL to `https://drop.tld/api/v1/auth/odic/logout`
+     - Make sure to set the logout URL as a `back-channel` logout in the dropdown
+1. Configure everything else as you see fit
+
+### For Drop
+
+:::note
+Make sure to replace the client ID, secret, and well-known url with your actual values. You can find the well-known URL in the provider's configuration page in Authentik.
+:::
+
+For drop, the docker compose configuration would look like this:
+
+```yaml
+services:
+  drop:
+    environment:
+      - OIDC_CLIENT_ID=authentik-client-id
+      - OIDC_CLIENT_SECRET=authentik-client-secret
+      - OIDC_ADMIN_GROUP=admin-group-name
+      - OIDC_WELLKNOWN=https://authentik.tld/application/o/<slug>/.well-known/openid-configuration
+```

docs/src/content/docs/reference/build-server.mdx

@@ -6,10 +6,10 @@ import { Steps } from "@astrojs/starlight/components";
 
 The Drop server is compromised of the following components, and are built with the associated tools:
 
-| Project        | Tools                           |
+| Project        | Tools           |
-| -------------- | ------------------------------- |
+| -------------- | --------------- |
-| Frontend & API | Node.js, `pnpm`                 |
+| Frontend & API | Node.js, `pnpm` |
-| `torrential`   | Rust (nightly)                  |
+| `torrential`   | Rust (nightly)  |
 
 Then, to be run outside the Docker container, Drop needs the following:
 
@@ -64,6 +64,10 @@ You will need to install:
 - Your copy of `torrential`, to somewhere in the [search path](#torrential-search-algorithm)
 - PostgreSQL
 
+:::tip
+Drop's [dockerfile](https://github.com/Drop-OSS/drop/blob/develop/Dockerfile) provides a great example on how to properly setup Drop's runtime environment.
+:::
+
 <Steps>
 1. ### Prepare your run directory
    You will need to copy the following files to your run directory:
@@ -78,10 +82,14 @@ You will need to install:
 
 3. ### Install `prisma` and run migrations
 
-   Use your Node.js package manager to install prisma, either to the local directory or globally:
+   Use your Node.js package manager to install drop's runtime dependencies:
+
+   :::caution
+   Make sure the prisma version installed is the same version as defined in drop's `package.json`.
+   :::
 
    ```bash
-   npm install prisma@6.11.1 dotenv # dotenv is a requirement
+   npm install prisma@7.3.0 dotenv # dotenv is required
    ```
 
    Then, with your database running: