From e938be3bc9137824e49c8bbb340d7f64818fb45f Mon Sep 17 00:00:00 2001
From: Anirudh Oppiliappan <anirudh@tangled.org>
Date: Thu, 14 May 2026 08:55:21 +0300
Subject: [PATCH] docs: self-hosting an appview

Signed-off-by: Anirudh Oppiliappan <anirudh@tangled.org>
---
 docs/DOCS.md | 156 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 156 insertions(+)

diff --git a/docs/DOCS.md b/docs/DOCS.md
index d46f884a..0b8bb0e0 100644
--- a/docs/DOCS.md
+++ b/docs/DOCS.md
@@ -751,6 +751,162 @@ If you are unable to push to your knot or repository:
    - `/home/git/log`
    - `/home/git/guard.log`
 
+# Self-hosting an appview
+
+The appview is the web frontend and indexer for a Tangled
+instance. It ingests events from the AT Protocol firehose,
+indexes repositories and social data, and serves the web UI.
+Running your own appview lets you host a fully independent
+Tangled instance scoped to your own users, knots, and
+content.
+
+## NixOS
+
+Refer to the [appview
+module](https://tangled.org/tangled.org/core/blob/master/nix/modules/appview.nix)
+for the full list of options. A minimal NixOS configuration:
+
+```nix
+services.tangled.appview = {
+  enable  = true;
+  package = pkgs.appview;
+
+  appviewHost = "git.example.com";
+  appviewName = "My Forge";
+  dbPath      = "/var/lib/appview/appview.db";
+
+  environmentFile = "/etc/appview.env";
+  # secrets in the environment file:
+  #   TANGLED_COOKIE_SECRET
+  #   TANGLED_OAUTH_CLIENT_SECRET
+  #   TANGLED_OAUTH_CLIENT_KID
+};
+```
+
+## Project mode
+
+Project mode collapses the URL namespace so the appview
+behaves like a single-project forge rather than a
+multi-user platform. When enabled:
+
+- `/{repo}` is served as `/{user}/{repo}`, where `{user}`
+  is a configured project user (a handle or DID).
+- The home page and global timeline are disabled; `/`
+  serves the project user's profile page instead.
+- The `/signup` route and all signup CTAs are hidden.
+- The sites (static site hosting) settings are hidden.
+
+Enable it in the NixOS module:
+
+```nix
+services.tangled.appview = {
+  enable  = true;
+  package = pkgs.appview;
+
+  project = {
+    enable = true;
+    user   = "anirudh.fi"; # handle or DID of the project owner
+  };
+};
+```
+
+Or via environment variables:
+
+```bash
+TANGLED_PROJECT_MODE=true
+TANGLED_PROJECT_USER=anirudh.fi
+```
+
+All other routes (settings, notifications, login, search,
+issues, pull requests, pipelines) continue to work as
+normal. Existing `/{user}/{repo}` URLs remain valid and
+need not be updated.
+
+## Caveats
+
+The appview builds its index by consuming the AT Protocol
+Jetstream firehose from the point it starts. It does **not**
+backfill historical data on first run, so repositories,
+users, and social data that existed before your instance
+started will not appear until they produce new events on the
+network (a push, a new issue, a profile edit, etc.).
+
+There is currently no first-party tool to perform a full
+network backfill. 
+
+## Custom templates
+
+The appview UI is built from HTML templates embedded in the
+binary at build time. You can override individual templates
+by providing a custom templates directory whose structure
+mirrors `appview/pages/templates/`. Files present in the
+custom directory replace the defaults; everything else
+falls back to the originals.
+
+Point to your custom directory in the NixOS module:
+
+```nix
+services.tangled.appview = {
+  enable  = true;
+  package = pkgs.appview;
+
+  project = {
+    enable       = true;
+    user         = "anirudh.fi";
+    templatesDir = ./custom-templates;
+  };
+};
+```
+
+Your `custom-templates/` directory only needs to contain
+the files you want to override. For example, to replace the
+footer:
+
+```
+custom-templates/
+  layouts/
+    fragments/
+      footerMinimal.html
+```
+
+For local development, copy your custom templates on top of
+the defaults and run with `TANGLED_DEV=true` for live
+reload:
+
+```bash
+cp -rfv custom-templates/* appview/pages/templates/
+TANGLED_DEV=true nix run .#watch-appview
+```
+
+## Custom CSS
+
+For small CSS additions, override `layouts/base.html` in
+your custom templates directory and add a `<style>` block
+after the stylesheet link:
+
+```html
+<link rel="stylesheet" href="/static/tw.css?{{ cssContentHash }}" type="text/css" />
+<style>
+  /* your overrides */
+  :root { --brand: #6366f1; }
+</style>
+```
+
+For full Tailwind customisation, override the static files
+Nix package to run Tailwind with your own `input.css`:
+
+```nix
+services.tangled.appview = {
+  package = pkgs.appview.override {
+    appview-static-files = pkgs.appview-static-files.overrideAttrs (old: {
+      buildCommand = old.buildCommand + ''
+        cat ${./extra.css} >> $out/tw.css
+      '';
+    });
+  };
+};
+```
+
 # Spindles
 
 ## Pipelines
-- 
2.51.2