| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138 |
- ---
- title: Setting up Anubis
- ---
- import RandomKey from "@site/src/components/RandomKey";
- import Tabs from "@theme/Tabs";
- import TabItem from "@theme/TabItem";
- 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>
- ## Docker image conventions
- 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 |
- | :------------------ | :--------------------------------------------------------------------------------------------------------------------------------- |
- | `latest` | The latest [tagged release](https://github.com/TecharoHQ/anubis/releases), if you are in doubt, start here. |
- | `v<version number>` | The Anubis image for [any given tagged release](https://github.com/TecharoHQ/anubis/tags) |
- | `main` | The current build on the `main` branch. Only use this if you need the latest and greatest features as they are merged into `main`. |
- The Docker image runs Anubis as user ID 1000 and group ID 1000. If you are mounting external volumes into Anubis' container, please be sure they are owned by or writable to this user/group.
- Anubis has very minimal system requirements. I suspect that 128Mi of ram may be sufficient for a large number of concurrent clients. Anubis may be a poor fit for apps that use WebSockets and maintain open connections, but I don't have enough real-world experience to know one way or another.
- ## Native packages
- For more detailed information on installing Anubis with native packages, please read [the native install directions](./native-install.mdx).
- ## Environment variables
- Anubis uses these environment variables for configuration:
- | Environment Variable | Default value | Explanation |
- | :----------------------------- | :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
- | `BASE_PREFIX` | unset | If set, adds a global prefix to all Anubis endpoints. For example, setting this to `/myapp` would make Anubis accessible at `/myapp/` instead of `/`. This is useful when running Anubis behind a reverse proxy that routes based on path prefixes. |
- | `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. |
- | `COOKIE_DOMAIN` | unset | The domain the Anubis challenge pass cookie should be set to. This should be set to the domain you bought from your registrar (EG: `techaro.lol` if your webapp is running on `anubis.techaro.lol`). See [here](https://stackoverflow.com/a/1063760) for more information. |
- | `COOKIE_PARTITIONED` | `false` | If set to `true`, enables the [partitioned (CHIPS) flag](https://developers.google.com/privacy-sandbox/cookies/chips), meaning that Anubis inside an iframe has a different set of cookies than the domain hosting the iframe. |
- | `DIFFICULTY` | `4` | The difficulty of the challenge, or the number of leading zeroes that must be in successful responses. |
- | `ED25519_PRIVATE_KEY_HEX` | unset | The hex-encoded ed25519 private key used to sign Anubis responses. If this is not set, Anubis will generate one for you. This should be exactly 64 characters long. See below for details. |
- | `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. |
- | `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.mdx). See the bot policy documentation for more details. If unset, the default bot policy configuration is used. |
- | `REDIRECT_DOMAINS` | unset | If set, restrict the domains that Anubis can redirect to when passing a challenge.<br/><br/>If this is unset, Anubis may redirect to any domain which could cause security issues in the unlikely case that an attacker passes a challenge for your browser and then tricks you into clicking a link to your domain. |
- | `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. |
- | `WEBMASTER_EMAIL` | unset | If set, shows a contact email address when rendering error pages. This email address will be how users can get in contact with administrators. |
- For more detailed information on configuring Open Graph tags, please refer to the [Open Graph Configuration](./configuration/open-graph.mdx) page.
- ### Using Base Prefix
- The `BASE_PREFIX` environment variable allows you to run Anubis behind a path prefix. This is useful when:
- - You want to host multiple services on the same domain
- - You're using a reverse proxy that routes based on path prefixes
- - You need to integrate Anubis with an existing application structure
- For example, if you set `BASE_PREFIX=/myapp`, Anubis will:
- - Serve its challenge page at `/myapp/` instead of `/`
- - Serve its API endpoints at `/myapp/.within.website/x/cmd/anubis/api/` instead of `/.within.website/x/cmd/anubis/api/`
- - Serve its static assets at `/myapp/.within.website/x/cmd/anubis/` instead of `/.within.website/x/cmd/anubis/`
- When using this feature with a reverse proxy:
- 1. Configure your reverse proxy to route requests for the specified path prefix to Anubis
- 2. Set the `BASE_PREFIX` environment variable to match the path prefix in your reverse proxy configuration
- 3. Ensure that your reverse proxy preserves the path when forwarding requests to Anubis
- Example with Nginx:
- ```nginx
- location /myapp/ {
- proxy_pass http://anubis:8923/myapp;
- proxy_set_header Host $host;
- proxy_set_header X-Real-IP $remote_addr;
- }
- ```
- With corresponding Anubis configuration:
- ```
- BASE_PREFIX=/myapp
- ```
- ### 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 />
- ## Next steps
- To get Anubis filtering your traffic, you need to make sure it's added to your HTTP load balancer or platform configuration. See the [environments category](/docs/category/environments) for detailed information on individual environments.
- - [Apache](./environments/apache.mdx)
- - [Docker compose](./environments/docker-compose.mdx)
- - [Kubernetes](./environments/kubernetes.mdx)
- - [Nginx](./environments/nginx.mdx)
- - [Traefik](./environments/traefik.mdx)
- :::note
- Anubis loads its assets from `/.within.website/x/xess/` and `/.within.website/x/cmd/anubis`. If you do not reverse proxy these in your server config, Anubis won't work.
- :::
|
