From 76a3f73a42c2f9bbeb4c56afa4b30a98a283b79f Mon Sep 17 00:00:00 2001 From: Max Date: Mon, 15 Jul 2024 19:51:14 +0200 Subject: [PATCH] Build and installation docs (#47) * README: document basic build/setup steps * document dev setup and how the config schema works * set up for use with direnv * mention direnv in the dev setup docs * README: mention developer docs * provide some contributor infos --- .envrc | 1 + .gitignore | 1 + README.md | 39 ++++++++++++++++++-- docs/content/Development.md | 31 ++++++++++++++++ docs/content/Development/config-schema.md | 8 ++++ docs/content/Development/for-contributors.md | 22 +++++++++++ 6 files changed, 99 insertions(+), 3 deletions(-) create mode 100644 .envrc create mode 100644 docs/content/Development.md create mode 100644 docs/content/Development/config-schema.md create mode 100644 docs/content/Development/for-contributors.md diff --git a/.envrc b/.envrc new file mode 100644 index 0000000..3550a30 --- /dev/null +++ b/.envrc @@ -0,0 +1 @@ +use flake diff --git a/.gitignore b/.gitignore index b9e8de4..cb9ad76 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ result result-* .data/ *_generated.go +.direnv/ diff --git a/README.md b/README.md index 6d6e70f..d222c2b 100644 --- a/README.md +++ b/README.md @@ -15,10 +15,11 @@ https://user-images.githubusercontent.com/19558067/152407636-a5f4ae1f-9493-4346- - [Use Cases](#use-cases) - [A Digital Nomad](#a-digital-nomad) - [A Privacy Advocate](#a-privacy-advocate) -- [Prerequisites](#prerequisites) +- [Installation](#installation) - [Usage](#usage) - [Commands](#commands) - [Tutorial](#tutorial) +- [Hacking](#hacking) ## About the Fork @@ -50,9 +51,37 @@ If anyone else has some use cases please add them! Pull requests welcome! ## Getting Started -### Prerequisites +### Installation -If you're running Hyprspace on Windows you'll need to install [tap-windows](http://build.openvpn.net/downloads/releases/). +Hyprspace requires [Nix](https://nixos.org/) to build. + +```shell-session +$ nix build github:hyprspace/hyprspace +``` + +Hyprspace also offers a NixOS module. To use it, simply import `nixosModules.default` in your NixOS configuration and use the options under `services.hyprspace`. +This will create a systemd service that runs `hyprspace up` with a generated config file. + +```nix +{ + services.hyprspace = { + enable = true; + + # To get a private key and peer ID, use `hyprspace init` + privateKeyFile = "/example/secrets/hyprspace-private-key"; + + # Same as the config file + settings = { + peers = [ + { id = "12D3KooWKgq4aJpZM8Peer1"; } + { id = "12D3KooWKgq4aJpZM8Peer2"; } + ]; + }; + }; +} +``` + +Also take a look at the [configuration docs](https://docs.hyprspace.privatevoid.net/configuration.html). ## Usage @@ -214,6 +243,10 @@ Addresses: ### Stopping the Interface and Cleaning Up Now to stop the interface and clean up the system, simply kill the proceses (for example, by pressing Ctrl+C where you started it). +## Hacking + +If you want to hack on Hyprspace, check out the [development docs](https://docs.hyprspace.privatevoid.net/Development.html) for a quick introduction. + ## Disclaimer & Copyright WireGuard is a registered trademark of Jason A. Donenfeld. diff --git a/docs/content/Development.md b/docs/content/Development.md new file mode 100644 index 0000000..b07475b --- /dev/null +++ b/docs/content/Development.md @@ -0,0 +1,31 @@ +# Development + +## Developer Environment + +Hyprspace is built with [Nix](https://nixos.org). The Hyprspace flake includes a devShell with all the tools needed for development. + +To use it, simply run: + +```shell-session +$ nix develop +``` + +You can also use [direnv](https://direnv.net). + +```shell-session +$ direnv allow +``` + +## Building + +To build Hyprspace for testing during development, you first need to generate the [[config-schema]] code. This is always done automatically upon entering the devShell. If you made changes to the config schema, you can regenerate the Go code (requires Nix): + +```shell-session +$ go generate ./schema +``` + +Then you can build the binary as usual: + +```shell-session +$ go build +``` diff --git a/docs/content/Development/config-schema.md b/docs/content/Development/config-schema.md new file mode 100644 index 0000000..c3614e9 --- /dev/null +++ b/docs/content/Development/config-schema.md @@ -0,0 +1,8 @@ +# Configuration Schema + +The schema for the configuration file is defined in `nixos/settings.nix`. This schema is used for +- generating Go code so Hyprspace can parse the configuration +- typed configuration in the NixOS module +- generating the [[configuration|config documentation]] + +The conversion to Go code happens by first converting the module options to a JSON schema using [clan.lol's NixOS to JSON schema converter](https://docs.clan.lol/blog/2024/05/25/jsonschema-converter/). The JSON schema is then used to generate Go code using [go-jsonschema](https://github.com/omissis/go-jsonschema). diff --git a/docs/content/Development/for-contributors.md b/docs/content/Development/for-contributors.md new file mode 100644 index 0000000..f8db3a5 --- /dev/null +++ b/docs/content/Development/for-contributors.md @@ -0,0 +1,22 @@ +# For Contributors + +This page contains some information you might find useful when contributing to Hyprspace. + +## Canonical Repository Location + +Development canonically takes place at https://github.com/hyprspace/hyprspace. Feel free to open issues and PRs there. + +## Continuous Integration + +Hyprspace uses [Hercules CI](https://hercules-ci.com/github/hyprspace/hyprspace) to verify code functionality and quality. You can also run all the builds and checks locally by running: + +```shell-session +$ nix flake check +``` + +## Code Formatting + +Hyprspace's codebase consists mainly of Go and Nix code. `go fmt` and nixfmt (RFC Style) are used respectively to format the code for those languages. Formatting is enforced via CI. + +Formatters are available in the [[Development|devShell]]. +