diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 00000000..d96f3f7c --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,74 @@ +# tangled contributing guide + +## commit guidelines + +We follow a commit style similar to the Go project. Please keep commits: + +* **atomic**: each commit should represent one logical change +* **descriptive**: the commit message should clearly describe what the +change does and why it's needed + +### message format + +``` +: : + + +Optional longer description, if needed. Explain what the change does and +why, especially if not obvious. Reference relevant issues or PRs when +applicable. These can be links for now since we don't auto-link +issues/PRs yet. +``` + +Here are some examples: + +``` +appview: state: fix token expiry check in middleware + +The previous check did not account for clock drift, leading to premature +token invalidation. +``` + +``` +knotserver: git/service: improve error checking in upload-pack +``` + +### general notes + +- PRs get merged as a single commit, so keep PRs small and focused. Use +the above guidelines for the PR title and description. +- Use the imperative mood in the summary line (e.g., "fix bug" not +"fixed bug" or "fixes bug"). +- Try to keep the summary line under 72 characters, but we aren't too +fussed about this. +- Don't include unrelated changes in the same commit. +- Avoid noisy commit messages like "wip" or "final fix"—rewrite history +before submitting if necessary. + +## proposals for bigger changes + +Small fixes like typos, minor bugs, or trivial refactors can be +submitted directly as PRs. + +For larger changes—especially those introducing new features, +significant refactoring, or altering system behavior—please open a +proposal first. This helps us evaluate the scope, design, and potential +impact before implementation. + +### proposal format + +Create a new issue titled: + +``` +proposal: : +``` + +In the description, explain: + +- What the change is +- Why it's needed +- How you plan to implement it (roughly) +- Any open questions or tradeoffs + +We'll use the issue thread to discuss and refine the idea before moving +forward. diff --git a/docs/knot-hosting.md b/docs/knot-hosting.md new file mode 100644 index 00000000..d9dcf39e --- /dev/null +++ b/docs/knot-hosting.md @@ -0,0 +1,108 @@ +# knot self-hosting guide + +So you want to run your own knot server? Great! Here are a few prerequisites: + +1. A server of some kind (a VPS, a Raspberry Pi, etc.). Preferably running a Linux of some kind. +2. A (sub)domain name. People generally use `knot.example.com`. +3. A valid SSL certificate for your domain. + +There's a couple of ways to get started: +* NixOS: refer to [flake.nix](https://tangled.sh/@tangled.sh/core/blob/master/flake.nix) +* Docker: Documented below. +* Manual: Documented below. + +## docker setup + +Clone this repository: + +``` +git clone https://tangled.sh/@tangled.sh/core +``` + +Modify the `docker/docker-compose.yml`, specifically the +`KNOT_SERVER_SECRET` and `KNOT_SERVER_HOSTNAME` env vars. Then run: + +``` +docker compose -f docker/docker-compose.yml up +``` + +### manual setup + +First, clone this repository: + +``` +git clone https://tangled.sh/@tangled.sh/core +``` + +Then, build our binaries (you need to have Go installed): +* `knotserver`: the main server program +* `keyfetch`: utility to fetch ssh pubkeys +* `repoguard`: enforces repository access control + +``` +cd core +export CGO_ENABLED=1 +go build -o knot ./cmd/knotserver +go build -o keyfetch ./cmd/keyfetch +go build -o repoguard ./cmd/repoguard +``` + +Next, move the `keyfetch` binary to a location owned by `root` -- +`/usr/local/libexec/tangled-keyfetch` is a good choice: + +``` +sudo mv keyfetch /usr/local/libexec/tangled-keyfetch +sudo chown root:root /usr/local/libexec/tangled-keyfetch +sudo chmod 755 /usr/local/libexec/tangled-keyfetch +``` + +This is necessary because SSH `AuthorizedKeysCommand` requires [really specific +permissions](https://stackoverflow.com/a/27638306). Let's set that up: + +``` +sudo tee /etc/ssh/sshd_config.d/authorized_keys_command.conf <