diff --git a/astro.config.mjs b/astro.config.mjs index 45c24df..bbe0e2c 100644 --- a/astro.config.mjs +++ b/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: [ { @@ -53,7 +64,7 @@ export default defineConfig({ }, { label: "Going further", - items: [{ slug: "admin/going-further/importing-update" }], + autogenerate: { directory: "admin/going-further" }, }, { label: "Metadata", diff --git a/public/robots.txt b/public/robots.txt new file mode 100644 index 0000000..2de1a22 --- /dev/null +++ b/public/robots.txt @@ -0,0 +1,4 @@ +User-agent: * +Allow: / + +Sitemap: https://docs-next.droposs.org/sitemap-index.xml \ No newline at end of file diff --git a/src/content/docs/admin/authentication/oidc.md b/src/content/docs/admin/authentication/oidc.md index 0864771..c7c9684 100644 --- a/src/content/docs/admin/authentication/oidc.md +++ b/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//.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`. diff --git a/src/content/docs/admin/going-further/setting-up-oidc.mdx b/src/content/docs/admin/going-further/setting-up-oidc.mdx new file mode 100644 index 0000000..d663a56 --- /dev/null +++ b/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//.well-known/openid-configuration +``` diff --git a/src/content/docs/reference/build-server.mdx b/src/content/docs/reference/build-server.mdx index 1fdd805..418aec6 100644 --- a/src/content/docs/reference/build-server.mdx +++ b/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 | -| -------------- | ------------------------------- | -| Frontend & API | Node.js, `pnpm` | -| `torrential` | Rust (nightly) | +| Project | Tools | +| -------------- | --------------- | +| Frontend & API | Node.js, `pnpm` | +| `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. +::: + 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: