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