I've contributed a few times to the Tangled codebase, none of which have been major changes but a couple of those changes needed testing before I was happy with them. To do that I needed to have an instance of Tangled running locally.
There is a hacking.md file that runs through how to get this set up locally but something that scared me off was in the first sentence...
We highly recommend installing NixOS(the package manager) before working on the codebase.
I had never used NixOS before and while I enjoy trying out new bits of tech, it seemed to be one of those things that you had to really invest time into using to get used to and understand how it worked. Not only that, but it looked like it would install a ton of things on my laptop and I just didn't fancy it.
Then it occurred to me, I wonder if there's a Docker image that I could run that could run the NixOS package manager for me inside of a container. Turns out there was and so I set upon my quest to get Tangled running inside a Docker container.
After playing around with setting the container up, following the instructions in the Tangled hacking guide and configuring everything, I finally had a working environment where I was able to make changes to the codebase and see the changes in my locally running instance of Tangled. I even managed to get a Knot setup and push some code to a repo inside of it. I haven't tried a Spindle because I have yet to use them but I have a feeling it won't work because they can't currently run Docker in Docker (I may be wrong about this though).
Here is a guide on how to get things running.
First, you need to have a Redis instance running. So something like docker run -d --name redis -p 6379:6379 redis will do.
Now for Nix. It starts with a Docker Compose file.
services:
nix:
container_name: nix
image: nixos/nix
environment:
TANGLED_VM_KNOT_OWNER: "PUT YOUR DID HERE"
TANGLED_VM_SPINDLE_OWNER: "PUT YOUR DID HERE"
volumes:
- /Users/will/tangled-fork:/tangled
- /Users/will/tangled-nix/config/:/etc/nix
restart: always
network_mode: host
stdin_open: true # docker run -i
tty: true # docker run -tFew things going on here.
Those environment variables are required as part of getting a Knot and Spindle running as directed in the Tangled hacking guide.
There are 2 volumes set up. One for the code repo I have on my machine so that it's available inside the container and another one that allows some Nix config to be set. I don't understand Nix but I do know that run trying to run the commands found in the hacking guide, I got errors because experimental features needed to be enabled. I found out that you can enable them using a nix.conf file inside the container, so that volume maps that config file. It looks like this.
build-users-group = nixbld
sandbox = false
trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=
experimental-features = nix-command flakesThe first 3 lines I copied from an existing config file from when I first ran the container and then I added the last line to enable to experimental features.
So create a config directory with a file nix.conf that contains the above config, and ensure that the config directory is mapped in your docker compose file.
Back to the Docker Compose file. I enable network mode to be host to make things easier when I'm pushing code to the Knot inside the container so that I don't have to fiddle around to much with SSH config.
Finally the last 2 lines allow me to connect to the container via shell.
Once that has been done the container can be started with docker-compose run --rm nix and it'll take you straight into the container. You now have the ability to run Nix commands which will allow you to run the Tangled code. So head into the tangled directory and at this point you can follow the hacking guide. However I will go through it quickly.
Once inside the tangled directory (which is a volume mapped to the code on your machine) you can run nix develop which will set things up. Once that's done, run TANGLED_DEV=true nix run .#watch-appview and that will start up the Tangled app view service.
Next if you want a Knot, you'll need a new terminal window connected to the container. So grab the container ID and then docker exec {containerID} -it bash and head into the tangled directory again.
This time run nix run --impure .#vm and that will start up a Knot server and apparently a Spindle server, however I haven't tested the Spindle server out yet.
Running both of those commands may take a while but once it's done you should be able to open up a web browser and head to localhost:3000 and you'll see the Tangled site. Make sure you log in with the account that matches the DID you configured in the Docker Compose file.
Top tip!! Don't use Safari because the OAuth flow doesn't work nicely and it allow you to be logged in after being redirected back from your OAuth login.
I guess the best thing to do next is to create a Knot, create a repo and push some code. Head over to the Knot page, create a new Knot at address localhost:6000 and then create a new repo on that Knot.
Now to push some code. Create a new local git repo with some files or use an existing one. Next you'll need to configure a remote like this
git remote add local-dev git@nixos-shell:{your-handle-here}/{repo-name}
Next you need to configure your SSH config so vi ~/.ssh/config and add the following
Host nixos-shell
Hostname localhost
Port 2222
User git
IdentityFile ~/.ssh/my_tangled_keyCreate a new SSH key called my_tangled_key, copy the public key and add it to your account on the Tangled UI.
Now push git push --set-upstream local-dev main and it should push your code to the Knot and you'll see it in the Tangled UI.
That's how I run the Tangled code locally, by running NixOS in a container on my local machine. The hacking.md guide contains a lot more information if you get stuck and I've not done anything crazy here, other than configuring NixOS to run in a container instead of installing it on my machine.