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 [flake.nix](https://tangled.sh/@tangled.sh/core/blob/master/flake.nix)
11* Docker: Documented below.
12* Manual: Documented below.
13
14## docker setup
15
16Clone this repository:
17
18```
19git clone https://tangled.sh/@tangled.sh/core
20```
21
22Modify the `docker/docker-compose.yml`, specifically the
23`KNOT_SERVER_SECRET` and `KNOT_SERVER_HOSTNAME` env vars. Then run:
24
25```
26docker compose -f docker/docker-compose.yml up
27```
28
29## manual setup
30
31First, clone this repository:
32
33```
34git clone https://tangled.sh/@tangled.sh/core
35```
36
37Then, build our binaries (you need to have Go installed):
38* `knotserver`: the main server program
39* `keyfetch`: utility to fetch ssh pubkeys
40* `repoguard`: enforces repository access control
41
42```
43cd core
44export CGO_ENABLED=1
45go build -o knot ./cmd/knotserver
46go build -o keyfetch ./cmd/keyfetch
47go build -o repoguard ./cmd/repoguard
48```
49
50Next, move the `keyfetch` binary to a location owned by `root` --
51`/usr/local/libexec/tangled-keyfetch` is a good choice:
52
53```
54sudo mv keyfetch /usr/local/libexec/tangled-keyfetch
55sudo chown root:root /usr/local/libexec/tangled-keyfetch
56sudo chmod 755 /usr/local/libexec/tangled-keyfetch
57```
58
59This is necessary because SSH `AuthorizedKeysCommand` requires [really specific
60permissions](https://stackoverflow.com/a/27638306). Let's set that up:
61
62```
63sudo tee /etc/ssh/sshd_config.d/authorized_keys_command.conf <<EOF
64Match User git
65 AuthorizedKeysCommand /usr/local/libexec/tangled-keyfetch
66 AuthorizedKeysCommandUser nobody
67EOF
68```
69
70Next, create the `git` user:
71
72```
73sudo adduser git
74```
75
76Copy the `repoguard` binary to the `git` user's home directory:
77
78```
79sudo cp repoguard /home/git
80sudo chown git:git /home/git/repoguard
81```
82
83Now, let's set up the server. Copy the `knot` binary to
84`/usr/local/bin/knotserver`. Then, create `/home/git/.knot.env` with the
85following, updating the values as necessary. The `KNOT_SERVER_SECRET` can be
86obtaind from the [/knots](/knots) page on Tangled.
87
88```
89KNOT_REPO_SCAN_PATH=/home/git
90KNOT_SERVER_HOSTNAME=knot.example.com
91APPVIEW_ENDPOINT=https://tangled.sh
92KNOT_SERVER_SECRET=secret
93KNOT_SERVER_INTERNAL_LISTEN_ADDR=127.0.0.1:5444
94KNOT_SERVER_LISTEN_ADDR=127.0.0.1:5555
95```
96
97If you run a Linux distribution that uses systemd, you can use the provided
98service file to run the server. Copy
99[`knotserver.service`](https://tangled.sh/did:plc:wshs7t2adsemcrrd4snkeqli/core/blob/master/systemd/knotserver.service)
100to `/etc/systemd/system/`. Then, run:
101
102```
103systemctl enable knotserver
104systemctl start knotserver
105```
106
107You should now have a running knot server! You can finalize your registration by hitting the
108`initialize` button on the [/knots](/knots) page.
109
110### custom paths
111
112(This section applies to manual setup only. Docker users should edit the mounts
113in `docker-compose.yml` instead.)
114
115Right now, the database and repositories of your knot lives in `/home/git`. You
116can move these paths if you'd like to store them in another folder. Be careful
117when adjusting these paths:
118
119* Stop your knot when moving data (e.g. `systemctl stop knotserver`) to prevent
120any possible side effects. Remember to restart it once you're done.
121* Make backups before moving in case something goes wrong.
122* Make sure the `git` user can read and write from the new paths.
123
124#### database
125
126As an example, let's say the current database is at `/home/git/knotserver.db`,
127and we want to move it to `/home/git/database/knotserver.db`.
128
129Copy the current database to the new location. Make sure to copy the `.db-shm`
130and `.db-wal` files if they exist.
131
132```
133mkdir /home/git/database
134cp /home/git/knotserver.db* /home/git/database
135```
136
137In the environment (e.g. `/home/git/.knot.env`), set `KNOT_SERVER_DB_PATH` to
138the new file path (_not_ the directory):
139
140```
141KNOT_SERVER_DB_PATH=/home/git/database/knotserver.db
142```
143
144#### repositories
145
146As an example, let's say the repositories are currently in `/home/git`, and we
147want to move them into `/home/git/repositories`.
148
149Create the new folder, then move the existing repositories (if there are any):
150
151```
152mkdir /home/git/repositories
153# move all DIDs into the new folder; these will vary for you!
154mv /home/git/did:plc:wshs7t2adsemcrrd4snkeqli /home/git/repositories
155```
156
157In the environment (e.g. `/home/git/.knot.env`), update `KNOT_REPO_SCAN_PATH`
158to the new directory:
159
160```
161KNOT_REPO_SCAN_PATH=/home/git/repositories
162```
163
164In your SSH config (e.g. `/etc/ssh/sshd_config.d/authorized_keys_command.conf`),
165update the `AuthorizedKeysCommand` line to use the new folder. For example:
166
167```
168Match User git
169 AuthorizedKeysCommand /usr/local/libexec/tangled-keyfetch -git-dir /home/git/repositories
170 AuthorizedKeysCommandUser nobody
171```
172
173Make sure to restart your SSH server!
174
175#### git
176
177The keyfetch executable takes multiple arguments to change certain paths. You
178can view a full list by running `/usr/local/libexec/tangled-keyfetch -h`.
179
180As an example, if you wanted to change the path to the repoguard executable,
181you would edit your SSH config (e.g. `/etc/ssh/sshd_config.d/authorized_keys_command.conf`)
182and update the `AuthorizedKeysCommand` line:
183
184```
185Match User git
186 AuthorizedKeysCommand /usr/local/libexec/tangled-keyfetch -repoguard-path /path/to/repoguard
187 AuthorizedKeysCommandUser nobody
188```
189
190Make sure to restart your SSH server!