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_SECRET` can be obtained from the
77[/knots](https://tangled.sh/knots) page on Tangled.
78
79```
80KNOT_REPO_SCAN_PATH=/home/git
81KNOT_SERVER_HOSTNAME=knot.example.com
82APPVIEW_ENDPOINT=https://tangled.sh
83KNOT_SERVER_SECRET=secret
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 your registration by hitting the
132`initialize` button on the [/knots](https://tangled.sh/knots) page.
133
134### custom paths
135
136(This section applies to manual setup only. Docker users should edit the mounts
137in `docker-compose.yml` instead.)
138
139Right now, the database and repositories of your knot lives in `/home/git`. You
140can move these paths if you'd like to store them in another folder. Be careful
141when adjusting these paths:
142
143* Stop your knot when moving data (e.g. `systemctl stop knotserver`) to prevent
144any possible side effects. Remember to restart it once you're done.
145* Make backups before moving in case something goes wrong.
146* Make sure the `git` user can read and write from the new paths.
147
148#### database
149
150As an example, let's say the current database is at `/home/git/knotserver.db`,
151and we want to move it to `/home/git/database/knotserver.db`.
152
153Copy the current database to the new location. Make sure to copy the `.db-shm`
154and `.db-wal` files if they exist.
155
156```
157mkdir /home/git/database
158cp /home/git/knotserver.db* /home/git/database
159```
160
161In the environment (e.g. `/home/git/.knot.env`), set `KNOT_SERVER_DB_PATH` to
162the new file path (_not_ the directory):
163
164```
165KNOT_SERVER_DB_PATH=/home/git/database/knotserver.db
166```
167
168#### repositories
169
170As an example, let's say the repositories are currently in `/home/git`, and we
171want to move them into `/home/git/repositories`.
172
173Create the new folder, then move the existing repositories (if there are any):
174
175```
176mkdir /home/git/repositories
177# move all DIDs into the new folder; these will vary for you!
178mv /home/git/did:plc:wshs7t2adsemcrrd4snkeqli /home/git/repositories
179```
180
181In the environment (e.g. `/home/git/.knot.env`), update `KNOT_REPO_SCAN_PATH`
182to the new directory:
183
184```
185KNOT_REPO_SCAN_PATH=/home/git/repositories
186```
187
188Similarly, update your `sshd` `AuthorizedKeysCommand` to use the updated
189repository path:
190
191```
192sudo tee /etc/ssh/sshd_config.d/authorized_keys_command.conf <<EOF
193Match User git
194 AuthorizedKeysCommand /usr/local/bin/knot keys -o authorized-keys -git-dir /home/git/repositories
195 AuthorizedKeysCommandUser nobody
196EOF
197```
198
199Make sure to restart your SSH server!
200
201#### MOTD (message of the day)
202
203To configure the MOTD used ("Welcome to this knot!" by default), edit the
204`/home/git/motd` file:
205
206```
207printf "Hi from this knot!\n" > /home/git/motd
208```
209
210Note that you should add a newline at the end if setting a non-empty message
211since the knot won't do this for you.