TecharoHQ · Xe · Apr 19, 2025 · Apr 19, 2025
diff --git a/docs/docs/CHANGELOG.md b/docs/docs/CHANGELOG.md
@@ -21,6 +21,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Allow requests from the Internet Archive
 - Added example nginx configuration to documentation
 - Added example Apache configuration to the documentation [#277](https://github.com/TecharoHQ/anubis/issues/277)
+- Move per-environment configuration details into their own pages
 
 ## v1.16.0
 

diff --git a/docs/docs/admin/environments/_category_.json b/docs/docs/admin/environments/_category_.json
@@ -0,0 +1,8 @@
+{
+  "label": "Environments",
+  "position": 20,
+  "link": {
+    "type": "generated-index",
+    "description": "Detailed information about individual environments (such as HTTP servers, platforms, etc.) Anubis is known to work with."
+  }
+}
diff --git a/docs/docs/admin/environments/apache.mdx b/docs/docs/admin/environments/apache.mdx
@@ -0,0 +1,151 @@
+# Apache
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+Anubis is intended to be a filter proxy. The way to integrate this is to break your configuration up into two parts: TLS termination and then HTTP routing. Consider this diagram:
+
+```mermaid
+---
+title: Apache as tls terminator and HTTP router
+---
+
+flowchart LR
+    T(User Traffic)
+    subgraph Apache 2
+        TCP(TCP 80/443)
+        US(TCP 3001)
+    end
+
+    An(Anubis)
+    B(Backend)
+
+    T --> |TLS termination| TCP
+    TCP --> |Traffic filtering| An
+    An --> |Happy traffic| US
+    US --> |whatever you're doing| B
+```
+
+Effectively you have one trip through Apache to do TLS termination, a detour through Anubis for traffic scrubbing, and then going to the backend directly. This final socket is what will do HTTP routing.
+
+:::note
+
+These examples assume that you are using a setup where your nginx configuration is made up of a bunch of files in `/etc/httpd/conf.d/*.conf`. This is not true for all deployments of Apache. If you are not in such an environment, append these snippets to your `/etc/httpd/conf/httpd.conf` file.
+
+:::
+
+## Dependencies
+
+Install the following dependencies for proxying HTTP:
+
+<Tabs>
+  <TabItem value="rpm" label="Red Hat / RPM" default>
+
+```text
+dnf -y install mod_proxy_html
+```
+
+  </TabItem>
+  <TabItem value="deb" label="Debian / Ubuntu / apt">
+
+```text
+apt-get install -y libapache2-mod-proxy-html libxml2-dev
+```
+
+  </TabItem>
+</Tabs>
+
+## Configuration
+
+Assuming you are protecting `anubistest.techaro.lol`, you need the following server configuration blocks:
+
+1. A block on port 80 that forwards HTTP to HTTPS
+2. A block on port 443 that terminates TLS and forwards to Anubis
+3. A block on port 3001 that actually serves your websites
+
+```text
+# Plain HTTP redirect to HTTPS
+<VirtualHost *:80>
+       ServerAdmin your@email.here
+       ServerName anubistest.techaro.lol
+       DocumentRoot /var/www/anubistest.techaro.lol
+       ErrorLog /var/log/httpd/anubistest.techaro.lol_error.log
+       CustomLog /var/log/httpd/anubistest.techaro.lol_access.log combined
+       RewriteEngine on
+       RewriteCond %{SERVER_NAME} =anubistest.techaro.lol
+       RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
+</VirtualHost>
+
+# HTTPS listener that forwards to Anubis
+<VirtualHost *:443>
+       ServerAdmin your@email.here
+       ServerName anubistest.techaro.lol
+       DocumentRoot /var/www/anubistest.techaro.lol
+       ErrorLog /var/log/httpd/anubistest.techaro.lol_error.log
+       CustomLog /var/log/httpd/anubistest.techaro.lol_access.log combined
+
+       SSLCertificateFile /etc/letsencrypt/live/anubistest.techaro.lol/fullchain.pem
+       SSLCertificateKeyFile /etc/letsencrypt/live/anubistest.techaro.lol/privkey.pem
+       Include /etc/letsencrypt/options-ssl-apache.conf
+
+       # These headers need to be set or else Anubis will
+       # throw an "admin misconfiguration" error.
+       RequestHeader set "X-Real-Ip" expr=%{REMOTE_ADDR}
+       RequestHeader set X-Forwarded-Proto "https"
+
+       ProxyPreserveHost On
+
+       ProxyRequests Off
+       ProxyVia Off
+
+       # Replace 9000 with the port Anubis listens on
+       ProxyPass / http://[::1]:9000/
+       ProxyPassReverse / http://[::1]:9000/
+</VirtualHost>
+</IfModule>
+
+# Actual website config
+<VirtualHost *:3001>
+       ServerAdmin your@email.here
+       ServerName anubistest.techaro.lol
+       DocumentRoot /var/www/anubistest.techaro.lol
+       ErrorLog /var/log/httpd/anubistest.techaro.lol_error.log
+       CustomLog /var/log/httpd/anubistest.techaro.lol_access.log combined
+</VirtualHost>
+```
+
+Make sure to add a separate configuration file for the listener on port 3001:
+
+```text
+# /etc/httpd/conf.d/listener-3001.conf
+
+Listen 3001
+```
+
+This can be repeated for multiple sites. Anubis does not care about the HTTP `Host` header and will happily cope with multiple websites via the same instance.
+
+Then reload your Apache config and load your website. You should see Anubis protecting your apps!
+
+```text
+sudo systemctl reload httpd.service
+```
+
+## Troubleshooting
+
+Here are some answers to questions that came in in testing:
+
+### I'm running on a Red Hat distribution and Apache is saying "service unavailable" for every page load
+
+If you see a "Service unavailable" error on every page load and run a Red Hat derived distribution, you are missing a `selinux` setting. The exact command will be in a journalctl log message like this:
+
+```text
+*****  Plugin catchall_boolean (89.3 confidence) suggests   ******************
+
+If you want to allow HTTPD scripts and modules to connect to the network using TCP.
+Then you must tell SELinux about this by enabling the 'httpd_can_network_connect' boolean.
+
+Do
+setsebool -P httpd_can_network_connect 1
+```
+
+This will fix the error immediately.
diff --git a/docs/docs/admin/environments/docker-compose.mdx b/docs/docs/admin/environments/docker-compose.mdx
@@ -0,0 +1,26 @@
+## Docker compose
+
+Docker compose is typically used in concert with other load balancers such as [Apache](./apache.mdx) or [Nginx](./nginx.mdx). Below is a minimal example showing you how to set up an instance of Anubis listening on host port 8080 that points to a static website containing data in `./www`:
+
+```yaml
+services:
+  anubis-nginx:
+    image: ghcr.io/techarohq/anubis:latest
+    environment:
+      BIND: ":8080"
+      DIFFICULTY: "5"
+      METRICS_BIND: ":9090"
+      SERVE_ROBOTS_TXT: "true"
+      TARGET: "http://nginx"
+      POLICY_FNAME: "/data/cfg/botPolicy.json"
+      OG_PASSTHROUGH: "true"
+      OG_EXPIRY_TIME: "24h"
+    ports:
+      - 8080:8080
+    volumes:
+      - "./botPolicy.json:/data/cfg/botPolicy.json:ro"
+  nginx:
+    image: nginx
+    volumes:
+      - "./www:/usr/share/nginx/html"
+```
diff --git a/docs/docs/admin/environments/kubernetes.mdx b/docs/docs/admin/environments/kubernetes.mdx
@@ -0,0 +1,128 @@
+# Kubernetes
+
+When setting up Anubis in Kubernetes, you want to make sure that you thread requests through Anubis kinda like this:
+
+```mermaid
+---
+title: Anubis embedded into workload pods
+---
+
+flowchart LR
+    T(User Traffic)
+
+    IngressController(IngressController)
+
+    subgraph Service
+        AnPort(Anubis Port)
+        BPort(Backend Port)
+    end
+
+    subgraph Pod
+        An(Anubis)
+        B(Backend)
+    end
+
+    T -->  IngressController
+    IngressController --> AnPort
+    AnPort --> An
+    An --> B
+```
+
+Anubis is lightweight enough that you should be able to have many instances of it running without many problems. If this is a concern for you, please check out [ingress-anubis](https://github.com/jaredallard/ingress-anubis?ref=anubis.techaro.lol).
+
+This example makes the following assumptions:
+
+- Your target service is listening on TCP port `5000`.
+- Anubis will be listening on port `8080`.
+
+Adjust these values as facts and circumstances demand.
+
+Create a secret with the signing key Anubis should use for its responses:
+
+```
+kubectl create secret generic anubis-key \
+  --namespace default \
+  --from-literal=ED25519_PRIVATE_KEY_HEX=$(openssl rand -hex 32)
+```
+
+Attach Anubis to your Deployment:
+
+```yaml
+containers:
+  # ...
+  - name: anubis
+    image: ghcr.io/techarohq/anubis:latest
+    imagePullPolicy: Always
+    env:
+      - name: "BIND"
+        value: ":8080"
+      - name: "DIFFICULTY"
+        value: "4"
+      - name: ED25519_PRIVATE_KEY_HEX
+        valueFrom:
+          secretKeyRef:
+            name: anubis-key
+            key: ED25519_PRIVATE_KEY_HEX
+      - name: "METRICS_BIND"
+        value: ":9090"
+      - name: "SERVE_ROBOTS_TXT"
+        value: "true"
+      - name: "TARGET"
+        value: "http://localhost:5000"
+      - name: "OG_PASSTHROUGH"
+        value: "true"
+      - name: "OG_EXPIRY_TIME"
+        value: "24h"
+    resources:
+      limits:
+        cpu: 750m
+        memory: 256Mi
+      requests:
+        cpu: 250m
+        memory: 256Mi
+    securityContext:
+      runAsUser: 1000
+      runAsGroup: 1000
+      runAsNonRoot: true
+      allowPrivilegeEscalation: false
+      capabilities:
+        drop:
+          - ALL
+      seccompProfile:
+        type: RuntimeDefault
+```
+
+Then add a Service entry for Anubis:
+
+```yaml
+# ...
+spec:
+  ports:
+    # diff-add
+    - protocol: TCP
+      # diff-add
+      port: 8080
+      # diff-add
+      targetPort: 8080
+      # diff-add
+      name: anubis
+```
+
+Then point your Ingress to the Anubis port:
+
+```yaml
+  rules:
+  - host: git.xeserv.us
+    http:
+      paths:
+      - pathType: Prefix
+        path: "/"
+        backend:
+          service:
+            name: git
+            port:
+              # diff-remove
+              name: http
+              # diff-add
+              name: anubis
+```