diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/docs/CHANGELOG.md | 1 | ||||
| -rw-r--r-- | docs/docs/admin/installation.mdx | 55 | ||||
| -rw-r--r-- | docs/manifest/deployment.yaml | 2 | ||||
| -rw-r--r-- | docs/src/components/RandomKey/index.tsx | 43 |
4 files changed, 89 insertions, 12 deletions
diff --git a/docs/docs/CHANGELOG.md b/docs/docs/CHANGELOG.md index 86e3c78..eac4599 100644 --- a/docs/docs/CHANGELOG.md +++ b/docs/docs/CHANGELOG.md @@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +- ed25519 signing keys for Anubis can be stored in the flag `--ed25519-private-key-hex` or envvar `ED25519_PRIVATE_KEY_HEX`; if one is not provided when Anubis starts, a new one is generated and logged - Fixed and clarified installation instructions - Introduced integration tests using Playwright - Refactor & Split up Anubis into cmd and lib.go diff --git a/docs/docs/admin/installation.mdx b/docs/docs/admin/installation.mdx index 248a885..8059319 100644 --- a/docs/docs/admin/installation.mdx +++ b/docs/docs/admin/installation.mdx @@ -2,8 +2,28 @@ title: Setting up Anubis --- +import RandomKey from "@site/src/components/RandomKey"; + Anubis is meant to sit between your reverse proxy (such as Nginx or Caddy) and your target service. One instance of Anubis must be used per service you are protecting. +<center> + +```mermaid +--- +title: With Anubis installed +--- + +flowchart LR + LB(Load balancer / +TLS terminator) + Anubis(Anubis) + App(App) + + LB --> Anubis --> App +``` + +</center> + Anubis is shipped in the Docker repo [`ghcr.io/techarohq/anubis`](https://github.com/TecharoHQ/anubis/pkgs/container/anubis). The following tags exist for your convenience: | Tag | Meaning | @@ -21,17 +41,30 @@ Anubis has very minimal system requirements. I suspect that 128Mi of ram may be Anubis uses these environment variables for configuration: -| Environment Variable | Default value | Explanation | -| :--------------------- | :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `BIND` | `:8923` | The network address that Anubis listens on. For `unix`, set this to a path: `/run/anubis/instance.sock` | -| `BIND_NETWORK` | `tcp` | The address family that Anubis listens on. Accepts `tcp`, `unix` and anything Go's [`net.Listen`](https://pkg.go.dev/net#Listen) supports. | -| `DIFFICULTY` | `5` | The difficulty of the challenge, or the number of leading zeroes that must be in successful responses. | -| `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. | -| `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. | -| `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`. | +| Environment Variable | Default value | Explanation | +| :------------------------ | :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `BIND` | `:8923` | The network address that Anubis listens on. For `unix`, set this to a path: `/run/anubis/instance.sock` | +| `BIND_NETWORK` | `tcp` | The address family that Anubis listens on. Accepts `tcp`, `unix` and anything Go's [`net.Listen`](https://pkg.go.dev/net#Listen) supports. | +| `DIFFICULTY` | `5` | The difficulty of the challenge, or the number of leading zeroes that must be in successful responses. | +| `ED25519_PRIVATE_KEY_HEX` | | The hex-encoded ed25519 private key used to sign Anubis responses. If this is not set, Anubis will generate one for you. | +| `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. | +| `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. | +| `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`. | + +### Key generation + +To generate an ed25519 private key, you can use this command: + +```text +openssl rand -hex 32 +``` + +Alternatively here is a key generated by your browser: + +<RandomKey /> ## Docker compose diff --git a/docs/manifest/deployment.yaml b/docs/manifest/deployment.yaml index fbf762c..4abb94b 100644 --- a/docs/manifest/deployment.yaml +++ b/docs/manifest/deployment.yaml @@ -22,7 +22,7 @@ spec: ports: - containerPort: 80 - name: anubis - image: ghcr.io/techarohq/anubis:latest + image: ghcr.io/techarohq/anubis:main imagePullPolicy: Always env: - name: "BIND" diff --git a/docs/src/components/RandomKey/index.tsx b/docs/src/components/RandomKey/index.tsx new file mode 100644 index 0000000..4f94a4d --- /dev/null +++ b/docs/src/components/RandomKey/index.tsx @@ -0,0 +1,43 @@ +import { useState, useEffect } from "react"; +import Code from "@theme/CodeInline"; +import BrowserOnly from "@docusaurus/BrowserOnly"; + +// https://www.xaymar.com/articles/2020/12/08/fastest-uint8array-to-hex-string-conversion-in-javascript/ +function toHex(buffer) { + return Array.prototype.map + .call(buffer, (x) => ("00" + x.toString(16)).slice(-2)) + .join(""); +} + +export const genRandomKey = (): String => { + const array = new Uint8Array(32); + self.crypto.getRandomValues(array); + return toHex(array); +}; + +export default function RandomKey() { + return ( + <BrowserOnly fallback={<div>Loading...</div>}> + {() => { + const [key, setKey] = useState<String>(genRandomKey()); + const [refresh, setRefresh] = useState<number>(0); + useEffect(() => { + setKey(genRandomKey); + }, [refresh]); + return ( + <span> + <Code>{key}</Code> + <span style={{ marginLeft: "0.25rem", marginRight: "0.25rem" }} /> + <button + onClick={() => { + setRefresh((n) => n + 1); + }} + > + ♻️ + </button> + </span> + ); + }} + </BrowserOnly> + ); +} |