diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/docs/CHANGELOG.md | 3 | ||||
| -rw-r--r-- | docs/docs/admin/configuration/open-graph.mdx | 47 | ||||
| -rw-r--r-- | docs/docs/admin/installation.mdx | 12 |
3 files changed, 60 insertions, 2 deletions
diff --git a/docs/docs/CHANGELOG.md b/docs/docs/CHANGELOG.md index 0937cc3..d7c6acb 100644 --- a/docs/docs/CHANGELOG.md +++ b/docs/docs/CHANGELOG.md @@ -14,7 +14,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Added support for native Debian, Red Hat, and tarball packaging strategies including installation and use directions. - A prebaked tarball has been added, allowing distros to build Anubis like they could in v1.15.x. - The placeholder Anubis mascot has been replaced with a design by [CELPHASE](https://bsky.app/profile/celphase.bsky.social). -- Allow iMessage's link preview fetcher through Anubis by default. - Added a periodic cleanup routine for the decaymap that removes expired entries, ensuring stale data is properly pruned. - Added a no-store Cache-Control header to the challenge page - Hide the directory listings for Anubis' internal static content @@ -38,6 +37,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Added `zizmor` for GitHub Actions static analysis - Fixed most `zizmor` findings - Enabled Dependabot +- Added an air config for autoreload support in development ([#195](https://github.com/TecharoHQ/anubis/pull/195)) +- Added support for [OpenGraph tags](https://ogp.me/) when rendering the challenge page. This allows for social previews to be generated when sharing the challenge page on social media platforms ([#195](https://github.com/TecharoHQ/anubis/pull/195)) - Added an `--extract-resources` flag to extract static resources to a local folder. - Add noindex flag to all Anubis pages ([#227](https://github.com/TecharoHQ/anubis/issues/227)). diff --git a/docs/docs/admin/configuration/open-graph.mdx b/docs/docs/admin/configuration/open-graph.mdx new file mode 100644 index 0000000..87dd404 --- /dev/null +++ b/docs/docs/admin/configuration/open-graph.mdx @@ -0,0 +1,47 @@ +--- +id: open-graph +title: Open Graph Configuration +--- + +# Open Graph Configuration + +This page provides detailed information on how to configure [OpenGraph tag](https://ogp.me/) passthrough in Anubis. This enables social previews of resources protected by Anubis without having to exempt each scraper individually. + +## Configuration Options + +| Name | Description | Type | Default | Example | +|------------------|-----------------------------------------------------------|----------|---------|-------------------------| +| `OG_PASSTHROUGH` | Enables or disables the Open Graph tag passthrough system | Boolean | `false` | `OG_PASSTHROUGH=true` | +| `OG_EXPIRY_TIME` | Configurable cache expiration time for Open Graph tags | Duration | `24h` | `OG_EXPIRY_TIME=1h` | + +## Usage + +To configure Open Graph tags, you can set the following environment variables, environment file or as flags in your Anubis configuration: + +```sh +export OG_PASSTHROUGH=true +export OG_EXPIRY_TIME=1h +``` + +## Implementation Details + +When `OG_PASSTHROUGH` is enabled, Anubis will: + +1. Check a local cache for the requested URL's Open Graph tags. +2. If a cached entry exists and is still valid, return the cached tags. +3. If the cached entry is stale or not found, fetch the URL, parse the Open Graph tags, update the cache, and return the new tags. + +The cache expiration time is controlled by `OG_EXPIRY_TIME`. + +## Example + +Here is an example of how to configure Open Graph tags in your Anubis setup: + +```sh +export OG_PASSTHROUGH=true +export OG_EXPIRY_TIME=1h +``` + +With these settings, Anubis will cache Open Graph tags for 1 hour and pass them through to the challenge page. + +For more information, refer to the [installation guide](../installation). diff --git a/docs/docs/admin/installation.mdx b/docs/docs/admin/installation.mdx index adf5cc9..c819e09 100644 --- a/docs/docs/admin/installation.mdx +++ b/docs/docs/admin/installation.mdx @@ -53,12 +53,16 @@ Anubis uses these environment variables for configuration: | `ED25519_PRIVATE_KEY_HEX_FILE` | unset | Path to a file containing the hex-encoded ed25519 private key. Only one of this or its sister option may be set. | | `METRICS_BIND` | `:9090` | The network address that Anubis serves Prometheus metrics on. See `BIND` for more information. | | `METRICS_BIND_NETWORK` | `tcp` | The address family that the Anubis metrics server listens on. See `BIND_NETWORK` for more information. | -| `SOCKET_MODE` | `0770` | _Only used when at least one of the `*_BIND_NETWORK` variables are set to `unix`._ The socket mode (permissions) for Unix domain sockets. | +| `OG_EXPIRY_TIME` | `24h` | The expiration time for the Open Graph tag cache. | +| `OG_PASSTHROUGH` | `false` | If set to `true`, Anubis will enable Open Graph tag passthrough. | | `POLICY_FNAME` | unset | The file containing [bot policy configuration](./policies.md). See the bot policy documentation for more details. If unset, the default bot policy configuration is used. | | `SERVE_ROBOTS_TXT` | `false` | If set `true`, Anubis will serve a default `robots.txt` file that disallows all known AI scrapers by name and then additionally disallows every scraper. This is useful if facts and circumstances make it difficult to change the underlying service to serve such a `robots.txt` file. | +| `SOCKET_MODE` | `0770` | _Only used when at least one of the `*_BIND_NETWORK` variables are set to `unix`._ The socket mode (permissions) for Unix domain sockets. | | `TARGET` | `http://localhost:3923` | The URL of the service that Anubis should forward valid requests to. Supports Unix domain sockets, set this to a URI like so: `unix:///path/to/socket.sock`. | | `USE_REMOTE_ADDRESS` | unset | If set to `true`, Anubis will take the client's IP from the network socket. For production deployments, it is expected that a reverse proxy is used in front of Anubis, which pass the IP using headers, instead. | +For more detailed information on configuring Open Graph tags, please refer to the [Open Graph Configuration](./configuration/open-graph.mdx) page. + ### Key generation To generate an ed25519 private key, you can use this command: @@ -86,6 +90,8 @@ services: SERVE_ROBOTS_TXT: "true" TARGET: "http://nginx" POLICY_FNAME: "/data/cfg/botPolicy.json" + OG_PASSTHROUGH: "true" + OG_EXPIRY_TIME: "24h" ports: - 8080:8080 volumes: @@ -122,6 +128,10 @@ containers: value: "true" - name: "TARGET" value: "http://localhost:5000" + - name: "OG_PASSTHROUGH" + value: "true" + - name: "OG_EXPIRY_TIME" + value: "24h" resources: limits: cpu: 500m |