Self-hosting a tangled knot git forge

Tangled is a new social-enabled git collaboration platform.

The social-enabled part makes it an alternative to GitHub.

The part where you can run tangled yourself makes it more like Gitea.

You can read more about it on tangled blog: introducing tangled.

What to install

The tangled ecosystem splits the concept of a git forge in two:

• Knots: lightweight, headless server that hosts git repositories
• App views: a way to access the network

We seek to install both what’s called a knotserver and an appview.

Explore the tangled core flake

The tangled core monorepo lives in https://tangled.sh/@tangled.sh/core/

It has a flake, which makes it easier to install it on NixOS.

Exploring what the flake has to offer (and omitting all but x86_64-linux for brevity):

$ nix flake show git+https://tangled.sh/@tangled.sh/core/
git+https://tangled.sh/@tangled.sh/core/?ref=refs/heads/master&rev=4793720c20f7e47078526f2ae7dd7979df12b73e
├───apps ...
│   └───x86_64-linux
│       ├───watch-appview: app: no description
│       └───watch-knotserver: app: no description
├───defaultPackage ...
│   └───x86_64-linux: package 'appview-static-x86_64-unknown-linux-musl-0.1.0'
├───devShells ...
│   └───x86_64-linux
│       └───default: development environment 'nix-shell-x86_64-unknown-linux-musl'
├───formatter ...
│   └───x86_64-linux: package 'alejandra-3.1.0'
├───nixosConfigurations
│   └───knotVM: NixOS configuration
├───nixosModules
│   ├───appview: NixOS module
│   └───knotserver: NixOS module
├───overlays
│   └───default: Nixpkgs overlay
└───packages ...
    └───x86_64-linux
        ├───appview: package 'appview-static-x86_64-unknown-linux-musl-0.1.0'
        ├───indigo-lexgen: package 'indigo-lexgen-0.1.0'
        ├───keyfetch: package 'keyfetch-0.1.0'
        ├───knotserver: package 'knotserver-static-x86_64-unknown-linux-musl-0.1.0'
        ├───knotserver-unwrapped: package 'knotserver-static-x86_64-unknown-linux-musl-0.1.0'
        └───repoguard: package 'repoguard-0.1.0'

With this information we can create a flake.nix that references the two packages:

{
  description = "A tangled flake";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    tangled.url = "git+https://tangled.sh/@tangled.sh/core";
    tangled.inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs = { self, nixpkgs, tangled, ... }: {
    packages.x86_64-linux = {
      appview = tangled.packages.x86_64-linux.appview;
      knotserver = tangled.packages.x86_64-linux.knotserver;
      # or: inherit (tangled.packages.x86_64-linux) appview knotserver;
    };
  };
}

Building and running the knotserver from this flake leads to the next step:

$ nix build .#knotserver
$ ./result/bin/knotserver
time=2025-04-16T23:35:10.728+02:00 level=ERROR msg="failed to load config" error="Server: Secret: missing required value: KNOT_SERVER_SECRET"

Configurating a tangled knoserver and appview

We produce a nixosModule that can be included in our system