veryroundbird.house
1# knot self-hosting guide
2
3So you want to run your own knot server? Great! Here are a few prerequisites:
4
51. A server of some kind (a VPS, a Raspberry Pi, etc.). Preferably running a Linux of some kind.
62. A (sub)domain name. People generally use `knot.example.com`.
73. A valid SSL certificate for your domain.
8
9There's a couple of ways to get started:
10* NixOS: refer to
11[flake.nix](https://tangled.sh/@tangled.sh/core/blob/master/flake.nix)
12* Docker: Documented at
13[@tangled.sh/knot-docker](https://tangled.sh/@tangled.sh/knot-docker)
14(community maintained: support is not guaranteed!)
15* Manual: Documented below.
16
17## manual setup
18
19First, clone this repository:
20
21```
22git clone https://tangled.sh/@tangled.sh/core
23```
24
25Then, build the `knot` CLI. This is the knot administration and operation tool.
26For the purpose of this guide, we're only concerned with these subcommands:
27
28* `knot server`: the main knot server process, typically run as a
29supervised service
30* `knot guard`: handles role-based access control for git over SSH
31(you'll never have to run this yourself)
32* `knot keys`: fetches SSH keys associated with your knot; we'll use
33this to generate the SSH `AuthorizedKeysCommand`
34
35```
36cd core
37export CGO_ENABLED=1
38go build -o knot ./cmd/knot
39```
40
41Next, move the `knot` binary to a location owned by `root` --
42`/usr/local/bin/knot` is a good choice:
43
44```
45sudo mv knot /usr/local/bin/knot
46```
47
48This is necessary because SSH `AuthorizedKeysCommand` requires [really
49specific permissions](https://stackoverflow.com/a/27638306). The
50`AuthorizedKeysCommand` specifies a command that is run by `sshd` to
51retrieve a user's public SSH keys dynamically for authentication. Let's
52set that up.
53
54```
55sudo tee /etc/ssh/sshd_config.d/authorized_keys_command.conf <<EOF
56Match User git
57 AuthorizedKeysCommand /usr/local/bin/knot keys -o authorized-keys
58 AuthorizedKeysCommandUser nobody
59EOF
60```
61
62Next, create the `git` user. We'll use the `git` user's home directory
63to store repositories:
64
65```
66sudo adduser git
67```
68
69Create `/home/git/.knot.env` with the following, updating the values as
70necessary. The `KNOT_SERVER_SECRET` can be obtaind from the
71[/knots](/knots) page on Tangled.
72
73```
74KNOT_REPO_SCAN_PATH=/home/git
75KNOT_SERVER_HOSTNAME=knot.example.com
76APPVIEW_ENDPOINT=https://tangled.sh
77KNOT_SERVER_SECRET=secret
78KNOT_SERVER_INTERNAL_LISTEN_ADDR=127.0.0.1:5444
79KNOT_SERVER_LISTEN_ADDR=127.0.0.1:5555
80```
81
82If you run a Linux distribution that uses systemd, you can use the provided
83service file to run the server. Copy
84[`knotserver.service`](/systemd/knotserver.service)
85to `/etc/systemd/system/`. Then, run:
86
87```
88systemctl enable knotserver
89systemctl start knotserver
90```
91
92You should now have a running knot server! You can finalize your registration by hitting the
93`initialize` button on the [/knots](/knots) page.
94
95### custom paths
96
97(This section applies to manual setup only. Docker users should edit the mounts
98in `docker-compose.yml` instead.)
99
100Right now, the database and repositories of your knot lives in `/home/git`. You
101can move these paths if you'd like to store them in another folder. Be careful
102when adjusting these paths:
103
104* Stop your knot when moving data (e.g. `systemctl stop knotserver`) to prevent
105any possible side effects. Remember to restart it once you're done.
106* Make backups before moving in case something goes wrong.
107* Make sure the `git` user can read and write from the new paths.
108
109#### database
110
111As an example, let's say the current database is at `/home/git/knotserver.db`,
112and we want to move it to `/home/git/database/knotserver.db`.
113
114Copy the current database to the new location. Make sure to copy the `.db-shm`
115and `.db-wal` files if they exist.
116
117```
118mkdir /home/git/database
119cp /home/git/knotserver.db* /home/git/database
120```
121
122In the environment (e.g. `/home/git/.knot.env`), set `KNOT_SERVER_DB_PATH` to
123the new file path (_not_ the directory):
124
125```
126KNOT_SERVER_DB_PATH=/home/git/database/knotserver.db
127```
128
129#### repositories
130
131As an example, let's say the repositories are currently in `/home/git`, and we
132want to move them into `/home/git/repositories`.
133
134Create the new folder, then move the existing repositories (if there are any):
135
136```
137mkdir /home/git/repositories
138# move all DIDs into the new folder; these will vary for you!
139mv /home/git/did:plc:wshs7t2adsemcrrd4snkeqli /home/git/repositories
140```
141
142In the environment (e.g. `/home/git/.knot.env`), update `KNOT_REPO_SCAN_PATH`
143to the new directory:
144
145```
146KNOT_REPO_SCAN_PATH=/home/git/repositories
147```
148
149Similarly, update your `sshd` `AuthorizedKeysCommand` to use the updated
150repository path:
151
152```
153sudo tee /etc/ssh/sshd_config.d/authorized_keys_command.conf <<EOF
154Match User git
155 AuthorizedKeysCommand /usr/local/bin/knot keys -o authorized-keys -git-dir /home/git/repositories
156 AuthorizedKeysCommandUser nobody
157EOF
158```
159
160Make sure to restart your SSH server!