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 distribution 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
62Then, reload `sshd`:
63
64```
65sudo systemctl reload ssh
66```
67
68Next, create the `git` user. We'll use the `git` user's home directory
69to store repositories:
70
71```
72sudo adduser git
73```
74
75Create `/home/git/.knot.env` with the following, updating the values as
76necessary. The `KNOT_SERVER_OWNER` should be set to your
77DID, you can find your DID in the [Settings](https://tangled.sh/settings) page.
78
79```
80KNOT_REPO_SCAN_PATH=/home/git
81KNOT_SERVER_HOSTNAME=knot.example.com
82APPVIEW_ENDPOINT=https://tangled.sh
83KNOT_SERVER_OWNER=did:plc:foobar
84KNOT_SERVER_INTERNAL_LISTEN_ADDR=127.0.0.1:5444
85KNOT_SERVER_LISTEN_ADDR=127.0.0.1:5555
86```
87
88If you run a Linux distribution that uses systemd, you can use the provided
89service file to run the server. Copy
90[`knotserver.service`](/systemd/knotserver.service)
91to `/etc/systemd/system/`. Then, run:
92
93```
94systemctl enable knotserver
95systemctl start knotserver
96```
97
98The last step is to configure a reverse proxy like Nginx or Caddy to front your
99knot. Here's an example configuration for Nginx:
100
101```
102server {
103 listen 80;
104 listen [::]:80;
105 server_name knot.example.com;
106
107 location / {
108 proxy_pass http://localhost:5555;
109 proxy_set_header Host $host;
110 proxy_set_header X-Real-IP $remote_addr;
111 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
112 proxy_set_header X-Forwarded-Proto $scheme;
113 }
114
115 # wss endpoint for git events
116 location /events {
117 proxy_set_header X-Forwarded-For $remote_addr;
118 proxy_set_header Host $http_host;
119 proxy_set_header Upgrade websocket;
120 proxy_set_header Connection Upgrade;
121 proxy_pass http://localhost:5555;
122 }
123 # additional config for SSL/TLS go here.
124}
125
126```
127
128Remember to use Let's Encrypt or similar to procure a certificate for your
129knot domain.
130
131You should now have a running knot server! You can finalize
132your registration by hitting the `verify` button on the
133[/knots](https://tangled.sh/knots) page. This simply creates
134a record on your PDS to announce the existence of the knot.
135
136### custom paths
137
138(This section applies to manual setup only. Docker users should edit the mounts
139in `docker-compose.yml` instead.)
140
141Right now, the database and repositories of your knot lives in `/home/git`. You
142can move these paths if you'd like to store them in another folder. Be careful
143when adjusting these paths:
144
145* Stop your knot when moving data (e.g. `systemctl stop knotserver`) to prevent
146any possible side effects. Remember to restart it once you're done.
147* Make backups before moving in case something goes wrong.
148* Make sure the `git` user can read and write from the new paths.
149
150#### database
151
152As an example, let's say the current database is at `/home/git/knotserver.db`,
153and we want to move it to `/home/git/database/knotserver.db`.
154
155Copy the current database to the new location. Make sure to copy the `.db-shm`
156and `.db-wal` files if they exist.
157
158```
159mkdir /home/git/database
160cp /home/git/knotserver.db* /home/git/database
161```
162
163In the environment (e.g. `/home/git/.knot.env`), set `KNOT_SERVER_DB_PATH` to
164the new file path (_not_ the directory):
165
166```
167KNOT_SERVER_DB_PATH=/home/git/database/knotserver.db
168```
169
170#### repositories
171
172As an example, let's say the repositories are currently in `/home/git`, and we
173want to move them into `/home/git/repositories`.
174
175Create the new folder, then move the existing repositories (if there are any):
176
177```
178mkdir /home/git/repositories
179# move all DIDs into the new folder; these will vary for you!
180mv /home/git/did:plc:wshs7t2adsemcrrd4snkeqli /home/git/repositories
181```
182
183In the environment (e.g. `/home/git/.knot.env`), update `KNOT_REPO_SCAN_PATH`
184to the new directory:
185
186```
187KNOT_REPO_SCAN_PATH=/home/git/repositories
188```
189
190Similarly, update your `sshd` `AuthorizedKeysCommand` to use the updated
191repository path:
192
193```
194sudo tee /etc/ssh/sshd_config.d/authorized_keys_command.conf <<EOF
195Match User git
196 AuthorizedKeysCommand /usr/local/bin/knot keys -o authorized-keys -git-dir /home/git/repositories
197 AuthorizedKeysCommandUser nobody
198EOF
199```
200
201Make sure to restart your SSH server!
202
203#### MOTD (message of the day)
204
205To configure the MOTD used ("Welcome to this knot!" by default), edit the
206`/home/git/motd` file:
207
208```
209printf "Hi from this knot!\n" > /home/git/motd
210```
211
212Note that you should add a newline at the end if setting a non-empty message
213since the knot won't do this for you.