veryroundbird.house / core
forked from tangled.org/core
this repo has no description
fork atom
core / docs / knot-hosting.md
at push-qnstkrpltlqu 5.6 kB view raw view code

knot self-hosting guide#

So you want to run your own knot server? Great! Here are a few prerequisites:

  1. A server of some kind (a VPS, a Raspberry Pi, etc.). Preferably running a Linux of some kind.
  2. A (sub)domain name. People generally use knot.example.com.
  3. A valid SSL certificate for your domain.

There's a couple of ways to get started:

  • NixOS: refer to flake.nix
  • Docker: Documented below.
  • Manual: Documented below.

docker setup#

Clone this repository:

git clone https://tangled.sh/@tangled.sh/core

Modify the docker/docker-compose.yml, specifically the KNOT_SERVER_SECRET and KNOT_SERVER_HOSTNAME env vars. Then run:

docker compose -f docker/docker-compose.yml up

manual setup#

First, clone this repository:

git clone https://tangled.sh/@tangled.sh/core

Then, build our binaries (you need to have Go installed):

  • knotserver: the main server program
  • keyfetch: utility to fetch ssh pubkeys
  • repoguard: enforces repository access control
cd core
export CGO_ENABLED=1
go build -o knot ./cmd/knotserver
go build -o keyfetch ./cmd/keyfetch
go build -o repoguard ./cmd/repoguard

Next, move the keyfetch binary to a location owned by root -- /usr/local/libexec/tangled-keyfetch is a good choice:

sudo mv keyfetch /usr/local/libexec/tangled-keyfetch
sudo chown root:root /usr/local/libexec/tangled-keyfetch
sudo chmod 755 /usr/local/libexec/tangled-keyfetch

This is necessary because SSH AuthorizedKeysCommand requires really specific permissions. Let's set that up:

sudo tee /etc/ssh/sshd_config.d/authorized_keys_command.conf <<EOF
Match User git
  AuthorizedKeysCommand /usr/local/libexec/tangled-keyfetch
  AuthorizedKeysCommandUser nobody
EOF

Next, create the git user:

sudo adduser git

Copy the repoguard binary to the git user's home directory:

sudo cp repoguard /home/git
sudo chown git:git /home/git/repoguard

Now, let's set up the server. Copy the knot binary to /usr/local/bin/knotserver. Then, create /home/git/.knot.env with the following, updating the values as necessary. The KNOT_SERVER_SECRET can be obtaind from the /knots page on Tangled.

KNOT_REPO_SCAN_PATH=/home/git
KNOT_SERVER_HOSTNAME=knot.example.com
APPVIEW_ENDPOINT=https://tangled.sh
KNOT_SERVER_SECRET=secret
KNOT_SERVER_INTERNAL_LISTEN_ADDR=127.0.0.1:5444
KNOT_SERVER_LISTEN_ADDR=127.0.0.1:5555

If you run a Linux distribution that uses systemd, you can use the provided service file to run the server. Copy knotserver.service to /etc/systemd/system/. Then, run:

systemctl enable knotserver
systemctl start knotserver

You should now have a running knot server! You can finalize your registration by hitting the initialize button on the /knots page.

custom paths#

(This section applies to manual setup only. Docker users should edit the mounts in docker-compose.yml instead.)

Right now, the database and repositories of your knot lives in /home/git. You can move these paths if you'd like to store them in another folder. Be careful when adjusting these paths:

  • Stop your knot when moving data (e.g. systemctl stop knotserver) to prevent any possible side effects. Remember to restart it once you're done.
  • Make backups before moving in case something goes wrong.
  • Make sure the git user can read and write from the new paths.

database#

As an example, let's say the current database is at /home/git/knotserver.db, and we want to move it to /home/git/database/knotserver.db.

Copy the current database to the new location. Make sure to copy the .db-shm and .db-wal files if they exist.

mkdir /home/git/database
cp /home/git/knotserver.db* /home/git/database

In the environment (e.g. /home/git/.knot.env), set KNOT_SERVER_DB_PATH to the new file path (not the directory):

KNOT_SERVER_DB_PATH=/home/git/database/knotserver.db

repositories#

As an example, let's say the repositories are currently in /home/git, and we want to move them into /home/git/repositories.

Create the new folder, then move the existing repositories (if there are any):

mkdir /home/git/repositories
# move all DIDs into the new folder; these will vary for you!
mv /home/git/did:plc:wshs7t2adsemcrrd4snkeqli /home/git/repositories

In the environment (e.g. /home/git/.knot.env), update KNOT_REPO_SCAN_PATH to the new directory:

KNOT_REPO_SCAN_PATH=/home/git/repositories

In your SSH config (e.g. /etc/ssh/sshd_config.d/authorized_keys_command.conf), update the AuthorizedKeysCommand line to use the new folder. For example:

Match User git
  AuthorizedKeysCommand /usr/local/libexec/tangled-keyfetch -git-dir /home/git/repositories
  AuthorizedKeysCommandUser nobody

Make sure to restart your SSH server!

git#

The keyfetch executable takes multiple arguments to change certain paths. You can view a full list by running /usr/local/libexec/tangled-keyfetch -h.

As an example, if you wanted to change the path to the repoguard executable, you would edit your SSH config (e.g. /etc/ssh/sshd_config.d/authorized_keys_command.conf) and update the AuthorizedKeysCommand line:

Match User git
  AuthorizedKeysCommand /usr/local/libexec/tangled-keyfetch -repoguard-path /path/to/repoguard
  AuthorizedKeysCommandUser nobody

Make sure to restart your SSH server!