nasso.dev
forked from
tangled.org/core
this repo has no description
wip: details tag for docs
Signed-off-by: oppiliappan <me@oppi.li>
oppi.li
+46
-45
docs/hacking.md
+46
-45
docs/hacking.md
···
48
redis-server
49
```
50
51
-
## running knots and spindles in a VM
52
53
An end-to-end knot setup requires setting up a machine with
54
`sshd`, `AuthorizedKeysCommand`, and git user, which is
55
quite cumbersome. So the nix flake provides a
56
`nixosConfiguration` to do so.
57
58
-
### Mac-specific: setting up a Nix builder
59
60
-
In order to build Tangled's dev VM on macOS, you will first need to set up a
61
-
Linux Nix builder. The recommended way to do so is to run a
62
-
[`darwin.linux-builder` VM][darwin builder vm] and to register it in `nix.conf`
63
-
as a builder for Linux with the same architecture as your Mac (`linux-aarch64`
64
-
if you are using Apple Silicon).
65
66
-
> IMPORTANT: You must build `darwin.linux-builder` somewhere other than inside
67
-
> the tangled repo so that it doesn't conflict with the other VM. For example,
68
-
> you can do
69
-
>
70
-
> ```shell
71
-
> cd $(mktemp -d buildervm.XXXXX) && nix run nixpkgs#darwin.linux-builder
72
-
> ```
73
-
>
74
-
> to store the builder VM in a temporary dir.
75
-
>
76
-
> You should read and follow [all the other intructions][darwin builder vm] to
77
-
> avoid subtle problems.
78
79
-
Alternatively, you can use any other method to set up a Linux machine with `nix`
80
-
installed that you can `sudo ssh` into (in other words, root user on your Mac
81
-
has to be able to ssh into the Linux machine without entering a password) and
82
-
that has the same architecture as your Mac. See [remote builder instructions]
83
-
for how to register such a builder in `nix.conf`.
84
85
-
> WARNING: If you'd like to use
86
-
> [`nixos-lima`](https://github.com/nixos-lima/nixos-lima) or
87
-
> [Orbstack](https://orbstack.dev/), note that setting them up so that `sudo
88
-
> ssh` works can be tricky. It seems to be [possible with
89
-
> Orbstack](https://github.com/orgs/orbstack/discussions/1669).
90
91
-
[darwin builder vm]:
92
-
https://nixos.org/manual/nixpkgs/unstable/#sec-darwin-builder
93
-
[remote builder instructions]:
94
-
https://nix.dev/manual/nix/2.28/advanced-topics/distributed-builds.html#requirements
95
-
96
-
### Running a knot on a dev VM
97
98
To begin, grab your DID from http://localhost:3000/settings.
99
Then, set `TANGLED_VM_KNOT_OWNER` and
100
-
`TANGLED_VM_SPINDLE_OWNER` to your DID.
101
-
102
-
If you don't want to [set up a spindle](#running-a-spindle),
103
-
you can use any placeholder value.
104
-
105
-
You can now start a lightweight NixOS VM like so:
106
107
```bash
108
nix run --impure .#vm
···
114
with `ssh` exposed on port 2222.
115
116
Once the services are running, head to
117
-
http://localhost:3000/knots and hit verify (and similarly,
118
-
http://localhost:3000/spindles to verify your spindle). It
119
-
should verify the ownership of the services instantly if
120
-
everything went smoothly.
121
122
You can push repositories to this VM with this ssh config
123
block on your main machine:
···
159
# litecli has a nicer REPL interface:
160
litecli /var/lib/spindle/spindle.db
161
```
···
48
redis-server
49
```
50
51
+
## running knots and spindles
52
53
An end-to-end knot setup requires setting up a machine with
54
`sshd`, `AuthorizedKeysCommand`, and git user, which is
55
quite cumbersome. So the nix flake provides a
56
`nixosConfiguration` to do so.
57
58
+
<details>
59
+
<summary><strong>MacOS users will have to setup a Nix Builder first</strong></summary>
60
61
+
In order to build Tangled's dev VM on macOS, you will
62
+
first need to set up a Linux Nix builder. The recommended
63
+
way to do so is to run a [`darwin.linux-builder`
64
+
VM](https://nixos.org/manual/nixpkgs/unstable/#sec-darwin-builder)
65
+
and to register it in `nix.conf` as a builder for Linux
66
+
with the same architecture as your Mac (`linux-aarch64` if
67
+
you are using Apple Silicon).
68
69
+
> IMPORTANT: You must build `darwin.linux-builder` somewhere other than inside
70
+
> the tangled repo so that it doesn't conflict with the other VM. For example,
71
+
> you can do
72
+
>
73
+
> ```shell
74
+
> cd $(mktemp -d buildervm.XXXXX) && nix run nixpkgs#darwin.linux-builder
75
+
> ```
76
+
>
77
+
> to store the builder VM in a temporary dir.
78
+
>
79
+
> You should read and follow [all the other intructions][darwin builder vm] to
80
+
> avoid subtle problems.
81
82
+
Alternatively, you can use any other method to set up a
83
+
Linux machine with `nix` installed that you can `sudo ssh`
84
+
into (in other words, root user on your Mac has to be able
85
+
to ssh into the Linux machine without entering a password)
86
+
and that has the same architecture as your Mac. See
87
+
[remote builder
88
+
instructions](https://nix.dev/manual/nix/2.28/advanced-topics/distributed-builds.html#requirements)
89
+
for how to register such a builder in `nix.conf`.
90
91
+
> WARNING: If you'd like to use
92
+
> [`nixos-lima`](https://github.com/nixos-lima/nixos-lima) or
93
+
> [Orbstack](https://orbstack.dev/), note that setting them up so that `sudo
94
+
> ssh` works can be tricky. It seems to be [possible with
95
+
> Orbstack](https://github.com/orgs/orbstack/discussions/1669).
96
97
+
</details>
98
99
To begin, grab your DID from http://localhost:3000/settings.
100
Then, set `TANGLED_VM_KNOT_OWNER` and
101
+
`TANGLED_VM_SPINDLE_OWNER` to your DID. You can now start a
102
+
lightweight NixOS VM like so:
103
104
```bash
105
nix run --impure .#vm
···
111
with `ssh` exposed on port 2222.
112
113
Once the services are running, head to
114
+
http://localhost:3000/knots and hit verify. It should
115
+
verify the ownership of the services instantly if everything
116
+
went smoothly.
117
118
You can push repositories to this VM with this ssh config
119
block on your main machine:
···
155
# litecli has a nicer REPL interface:
156
litecli /var/lib/spindle/spindle.db
157
```
158
+
159
+
If for any reason you wish to disable either one of the
160
+
services in the VM, modify [nix/vm.nix](/nix/vm.nix) and set
161
+
`services.tangled-spindle.enable` (or
162
+
`services.tangled-knot.enable`) to `false`.