TARDIS Project

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Working on NixOS hosts / Core services ======

Our 'core services' (the stuff we're more scared of changing), are mostly managed with Nix - a functional programming language, build system, configuration tool, and hard disk stress tester wrapped into one.

A lot of this is specific to Tardis core services nix, and is mostly geared towards people needing to make superficial changes, that probably haven't learnt Nix.

===== 'I-just-want-to-add-a-vhost-why-is-this-so-hard' =====

Our core services is setup to deploy whatever's on ''main'' to all of our machines. This means if you know exactly what you need to change, you can probably avoid doing any actual building or deploying locally.

With that said, you should still use a syntax checker / linter. You can download [[https://github.com/kamadorueda/alejandra|alejandra]], our linter. Make your changes, then run ''alejandra .'' to check syntax, and format it. Double check your changes to make sure you haven't completely changed the meaning of the file - if the indentation is the same everywhere else you're probably fine.

[[https://cheat.readthedocs.io/en/latest/nixos/nix_lang.html|Here]] is a small cheatsheet for the nix language - alternatively, just look at the parts around what you're editing. Here are some common files you might need to edit:

  * [[https://git.tardisproject.uk/tardis/nix/-/blob/main/profiles/services/email/postfix.nix|Email domains]] (see [[hosts:virtual_machines:web:mail|here]] for full steps)
  * [[https://git.tardisproject.uk/tardis/nix/-/blob/main/profiles/services/web/default.nix|Reverse Proxy Entries]]
  * [[https://git.tardisproject.uk/tardis/nix/-/blob/main/profiles/services/metrics/prometheus.nix|Prometheus Targets]]

**You won't be able to merge directly into main**, for hopefully obvious reasons. Make a branch and an MR, then ask someone else to approve it.

===== Prolonged work =====

If you're doing a lot of work and want to deploy and redeploy without pushing to CI, you'll need to do some local setup. Fortunately - you don't need a lot of disk space (all of our hosts take up about 11G). We can do all the actual building remotely, and only do some local config to make Nix forward things properly.

==== Installing Nix ====

You'll need something running *nix - either a VM or WSL. MacOS (Darwin) should work, but we haven't tested it.

We recommend the [[https://github.com/DeterminateSystems/nix-installer|determinate systems nix installer]], which can be run as simple as:

<code>
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
</code>

It gives you basically the same setup as [[https://nixos.org/download.html|the official Nix installer]] (which you can use if you have any problems), but it enables some extra commands, and especially flakes.

If you do use the official Nix installer, add ''extra-experimental-features = flakes nix-command'' so you can use these extra features. Don't worry - they're barely experimental anymore and are pretty widely deployed.

For this to work, we need to have passwordless ssh to whatever host you are deploying to. This involves proxying through our SSH bastion. You can find more details [[howto:ssh_proxy|here]], but you'll need to add something like this **to ''/etc/ssh/ssh_config''**:

<code>
Host tardis
    User USERNAME
    IdentityFile /path/to/your/ssh_key
    HostName tardisproject.uk

Host web.tardisproject.uk
    User root
    HostName web.internal.tardisproject.uk
    ProxyJump tardis
    IdentityFile /path/to/tardis/admin/key
</code>


Now that you're all setup, you can use the 3 scripts in our repo for most tasks:

  * ''scripts/eval_system <hostname>'' evaluates a given hostname and does some basic checks like that options exist, etc. Nothing gets built, and this doesnt even require remote building.
  * ''colmena apply switch --on=<hostname>'' builds and deploys the given hostname - all remotely. Skip the ''on'' flag if you want to deploy everything.
  * ''colmena apply build --on=<hostname>'' just builds the given hostname, but doesn't switch to it.

And some routine Nix tasks:

  - ''nix flake update'' - Update all inputs
  - ''nix flake lock --update-input <name>'' - Update a specific input, ie ''crane''

==== Secret Encryption & agenix ====

[[https://github.com/FiloSottile/age|age]] is an encryption tool & format to encrypt data using public keys.
[[https://github.com/ryantm/agenix|agenix]] integrates this into nix so that our secrets are both versioned & private.

=== Example usage (editing a secret file): ===



<code>
nix develop # Downloads & installs tools we use for our nix configs, including agenix
cd secrets
export EDITOR vi # Or your editor of choice
agenix -e [secret file].age -i [Path to the tardis root SSH key]
</code>