willdot.net
docs: knot hosting and contributing guide
anirudh.fi
+74
docs/contributing.md
+74
docs/contributing.md
···
···
1
+
# tangled contributing guide
2
+
3
+
## commit guidelines
4
+
5
+
We follow a commit style similar to the Go project. Please keep commits:
6
+
7
+
* **atomic**: each commit should represent one logical change
8
+
* **descriptive**: the commit message should clearly describe what the
9
+
change does and why it's needed
10
+
11
+
### message format
12
+
13
+
```
14
+
<service/top-level directory>: <package/path>: <short summary of change>
15
+
16
+
17
+
Optional longer description, if needed. Explain what the change does and
18
+
why, especially if not obvious. Reference relevant issues or PRs when
19
+
applicable. These can be links for now since we don't auto-link
20
+
issues/PRs yet.
21
+
```
22
+
23
+
Here are some examples:
24
+
25
+
```
26
+
appview: state: fix token expiry check in middleware
27
+
28
+
The previous check did not account for clock drift, leading to premature
29
+
token invalidation.
30
+
```
31
+
32
+
```
33
+
knotserver: git/service: improve error checking in upload-pack
34
+
```
35
+
36
+
### general notes
37
+
38
+
- PRs get merged as a single commit, so keep PRs small and focused. Use
39
+
the above guidelines for the PR title and description.
40
+
- Use the imperative mood in the summary line (e.g., "fix bug" not
41
+
"fixed bug" or "fixes bug").
42
+
- Try to keep the summary line under 72 characters, but we aren't too
43
+
fussed about this.
44
+
- Don't include unrelated changes in the same commit.
45
+
- Avoid noisy commit messages like "wip" or "final fix"—rewrite history
46
+
before submitting if necessary.
47
+
48
+
## proposals for bigger changes
49
+
50
+
Small fixes like typos, minor bugs, or trivial refactors can be
51
+
submitted directly as PRs.
52
+
53
+
For larger changes—especially those introducing new features,
54
+
significant refactoring, or altering system behavior—please open a
55
+
proposal first. This helps us evaluate the scope, design, and potential
56
+
impact before implementation.
57
+
58
+
### proposal format
59
+
60
+
Create a new issue titled:
61
+
62
+
```
63
+
proposal: <affected scope>: <summary of change>
64
+
```
65
+
66
+
In the description, explain:
67
+
68
+
- What the change is
69
+
- Why it's needed
70
+
- How you plan to implement it (roughly)
71
+
- Any open questions or tradeoffs
72
+
73
+
We'll use the issue thread to discuss and refine the idea before moving
74
+
forward.
+108
docs/knot-hosting.md
+108
docs/knot-hosting.md
···
···
1
+
# knot self-hosting guide
2
+
3
+
So you want to run your own knot server? Great! Here are a few prerequisites:
4
+
5
+
1. A server of some kind (a VPS, a Raspberry Pi, etc.). Preferably running a Linux of some kind.
6
+
2. A (sub)domain name. People generally use `knot.example.com`.
7
+
3. A valid SSL certificate for your domain.
8
+
9
+
There'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
+
16
+
Clone this repository:
17
+
18
+
```
19
+
git clone https://tangled.sh/@tangled.sh/core
20
+
```
21
+
22
+
Modify the `docker/docker-compose.yml`, specifically the
23
+
`KNOT_SERVER_SECRET` and `KNOT_SERVER_HOSTNAME` env vars. Then run:
24
+
25
+
```
26
+
docker compose -f docker/docker-compose.yml up
27
+
```
28
+
29
+
### manual setup
30
+
31
+
First, clone this repository:
32
+
33
+
```
34
+
git clone https://tangled.sh/@tangled.sh/core
35
+
```
36
+
37
+
Then, 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
+
```
43
+
cd core
44
+
export CGO_ENABLED=1
45
+
go build -o knot ./cmd/knotserver
46
+
go build -o keyfetch ./cmd/keyfetch
47
+
go build -o repoguard ./cmd/repoguard
48
+
```
49
+
50
+
Next, move the `keyfetch` binary to a location owned by `root` --
51
+
`/usr/local/libexec/tangled-keyfetch` is a good choice:
52
+
53
+
```
54
+
sudo mv keyfetch /usr/local/libexec/tangled-keyfetch
55
+
sudo chown root:root /usr/local/libexec/tangled-keyfetch
56
+
sudo chmod 755 /usr/local/libexec/tangled-keyfetch
57
+
```
58
+
59
+
This is necessary because SSH `AuthorizedKeysCommand` requires [really specific
60
+
permissions](https://stackoverflow.com/a/27638306). Let's set that up:
61
+
62
+
```
63
+
sudo tee /etc/ssh/sshd_config.d/authorized_keys_command.conf <<EOF
64
+
Match User git
65
+
AuthorizedKeysCommand /usr/local/libexec/tangled-keyfetch
66
+
AuthorizedKeysCommandUser nobody
67
+
EOF
68
+
```
69
+
70
+
Next, create the `git` user:
71
+
72
+
```
73
+
sudo adduser git
74
+
```
75
+
76
+
Copy the `repoguard` binary to the `git` user's home directory:
77
+
78
+
```
79
+
sudo cp repoguard /home/git
80
+
sudo chown git:git /home/git/repoguard
81
+
```
82
+
83
+
Now, let's set up the server. Copy the `knot` binary to
84
+
`/usr/local/bin/knotserver`. Then, create `/home/git/.knot.env` with the
85
+
following, updating the values as necessary. The `KNOT_SERVER_SECRET` can be
86
+
obtaind from the [/knots](/knots) page on Tangled.
87
+
88
+
```
89
+
KNOT_REPO_SCAN_PATH=/home/git
90
+
KNOT_SERVER_HOSTNAME=knot.example.com
91
+
APPVIEW_ENDPOINT=https://tangled.sh
92
+
KNOT_SERVER_SECRET=secret
93
+
KNOT_SERVER_INTERNAL_LISTEN_ADDR=127.0.0.1:5444
94
+
KNOT_SERVER_LISTEN_ADDR=127.0.0.1:5555
95
+
```
96
+
97
+
If you run a Linux distribution that uses systemd, you can use the provided
98
+
service file to run the server. Copy
99
+
[`knotserver.service`](https://tangled.sh/did:plc:wshs7t2adsemcrrd4snkeqli/core/blob/master/systemd/knotserver.service)
100
+
to `/etc/systemd/system/`. Then, run:
101
+
102
+
```
103
+
systemctl enable knotserver
104
+
systemctl start knotserver
105
+
```
106
+
107
+
You should now have a running knot server! You can finalize your registration by hitting the
108
+
`initialize` button on the [/knots](/knots) page.