Monorepo for Tangled
tangled.org
docs: self-hosting an appview
Signed-off-by: Anirudh Oppiliappan <anirudh@tangled.org>
author
Anirudh Oppiliappan
date
(Jun 24, 2026, 5:17 PM +0530)
commit
e938be3b
e938be3bc9137824e49c8bbb340d7f64818fb45f
parent
2028259b
2028259b6971884e4832abe5dff644529a808dda
change-id
ytnwlwpz
ytnwlwpznomsomonustoynrlpspnqxvw
+156
+156
docs/DOCS.md
+156
docs/DOCS.md
···
751
751
- `/home/git/log`
752
752
- `/home/git/guard.log`
753
753
754
+
# Self-hosting an appview
755
+
756
+
The appview is the web frontend and indexer for a Tangled
757
+
instance. It ingests events from the AT Protocol firehose,
758
+
indexes repositories and social data, and serves the web UI.
759
+
Running your own appview lets you host a fully independent
760
+
Tangled instance scoped to your own users, knots, and
761
+
content.
762
+
763
+
## NixOS
764
+
765
+
Refer to the [appview
766
+
module](https://tangled.org/tangled.org/core/blob/master/nix/modules/appview.nix)
767
+
for the full list of options. A minimal NixOS configuration:
768
+
769
+
```nix
770
+
services.tangled.appview = {
771
+
enable = true;
772
+
package = pkgs.appview;
773
+
774
+
appviewHost = "git.example.com";
775
+
appviewName = "My Forge";
776
+
dbPath = "/var/lib/appview/appview.db";
777
+
778
+
environmentFile = "/etc/appview.env";
779
+
# secrets in the environment file:
780
+
# TANGLED_COOKIE_SECRET
781
+
# TANGLED_OAUTH_CLIENT_SECRET
782
+
# TANGLED_OAUTH_CLIENT_KID
783
+
};
784
+
```
785
+
786
+
## Project mode
787
+
788
+
Project mode collapses the URL namespace so the appview
789
+
behaves like a single-project forge rather than a
790
+
multi-user platform. When enabled:
791
+
792
+
- `/{repo}` is served as `/{user}/{repo}`, where `{user}`
793
+
is a configured project user (a handle or DID).
794
+
- The home page and global timeline are disabled; `/`
795
+
serves the project user's profile page instead.
796
+
- The `/signup` route and all signup CTAs are hidden.
797
+
- The sites (static site hosting) settings are hidden.
798
+
799
+
Enable it in the NixOS module:
800
+
801
+
```nix
802
+
services.tangled.appview = {
803
+
enable = true;
804
+
package = pkgs.appview;
805
+
806
+
project = {
807
+
enable = true;
808
+
user = "anirudh.fi"; # handle or DID of the project owner
809
+
};
810
+
};
811
+
```
812
+
813
+
Or via environment variables:
814
+
815
+
```bash
816
+
TANGLED_PROJECT_MODE=true
817
+
TANGLED_PROJECT_USER=anirudh.fi
818
+
```
819
+
820
+
All other routes (settings, notifications, login, search,
821
+
issues, pull requests, pipelines) continue to work as
822
+
normal. Existing `/{user}/{repo}` URLs remain valid and
823
+
need not be updated.
824
+
825
+
## Caveats
826
+
827
+
The appview builds its index by consuming the AT Protocol
828
+
Jetstream firehose from the point it starts. It does **not**
829
+
backfill historical data on first run, so repositories,
830
+
users, and social data that existed before your instance
831
+
started will not appear until they produce new events on the
832
+
network (a push, a new issue, a profile edit, etc.).
833
+
834
+
There is currently no first-party tool to perform a full
835
+
network backfill.
836
+
837
+
## Custom templates
838
+
839
+
The appview UI is built from HTML templates embedded in the
840
+
binary at build time. You can override individual templates
841
+
by providing a custom templates directory whose structure
842
+
mirrors `appview/pages/templates/`. Files present in the
843
+
custom directory replace the defaults; everything else
844
+
falls back to the originals.
845
+
846
+
Point to your custom directory in the NixOS module:
847
+
848
+
```nix
849
+
services.tangled.appview = {
850
+
enable = true;
851
+
package = pkgs.appview;
852
+
853
+
project = {
854
+
enable = true;
855
+
user = "anirudh.fi";
856
+
templatesDir = ./custom-templates;
857
+
};
858
+
};
859
+
```
860
+
861
+
Your `custom-templates/` directory only needs to contain
862
+
the files you want to override. For example, to replace the
863
+
footer:
864
+
865
+
```
866
+
custom-templates/
867
+
layouts/
868
+
fragments/
869
+
footerMinimal.html
870
+
```
871
+
872
+
For local development, copy your custom templates on top of
873
+
the defaults and run with `TANGLED_DEV=true` for live
874
+
reload:
875
+
876
+
```bash
877
+
cp -rfv custom-templates/* appview/pages/templates/
878
+
TANGLED_DEV=true nix run .#watch-appview
879
+
```
880
+
881
+
## Custom CSS
882
+
883
+
For small CSS additions, override `layouts/base.html` in
884
+
your custom templates directory and add a `<style>` block
885
+
after the stylesheet link:
886
+
887
+
```html
888
+
<link rel="stylesheet" href="/static/tw.css?{{ cssContentHash }}" type="text/css" />
889
+
<style>
890
+
/* your overrides */
891
+
:root { --brand: #6366f1; }
892
+
</style>
893
+
```
894
+
895
+
For full Tailwind customisation, override the static files
896
+
Nix package to run Tailwind with your own `input.css`:
897
+
898
+
```nix
899
+
services.tangled.appview = {
900
+
package = pkgs.appview.override {
901
+
appview-static-files = pkgs.appview-static-files.overrideAttrs (old: {
902
+
buildCommand = old.buildCommand + ''
903
+
cat ${./extra.css} >> $out/tw.css
904
+
'';
905
+
});
906
+
};
907
+
};
908
+
```
909
+
754
910
# Spindles
755
911
756
912
## Pipelines