haccfiles/README.md

82 lines
2.7 KiB
Markdown
Raw Normal View History

2021-01-11 00:22:37 +00:00
# hacc nixfiles
Welcome to the hacc nixfiles (haccfiles). This is how we configure (most of)
our infrastructure.
2021-01-11 00:22:37 +00:00
## General layout
2021-01-11 00:22:37 +00:00
2022-11-14 17:38:43 +00:00
- `flake.nix`: Entrypoint & dependencies
2021-01-11 00:22:37 +00:00
- `modules/`: home-grown modules for hacc-specific services
- `pkgs/`: packages we need which aren't in nixpkgs
- `websites/`: static websites hosted by us
- `common/`: meta-level config, reusable across machines
- `parsons/`: our sole server, its config & the services it runs
2021-01-11 00:22:37 +00:00
Right now, we only have a single host. We might add more again in the future.
## Working with this repo
2021-01-11 00:22:37 +00:00
2022-11-14 17:38:43 +00:00
You will need a flake-enabled nix installation, and have your ssh config set up
so that `ssh parsons` will connect to `parsons.hacc.space`.
### Deploying remotely
2022-11-14 17:38:43 +00:00
It's recommended to use [deploy_rs](https://github.com/serokell/deploy-rs):
~~~shell
deploy .#parsons -k [--dry-activate]
~~~
Alternatively, using just `nixos-rebuild`:
~~~shell
nixos-rebuild --flake .#parsons --target-host parsons \
--use-remote-sudo --use-substitutes [test|switch|dry-activate]
~~~
2021-01-11 00:22:37 +00:00
### Re-deploying on parsons itself
Simply do:
2022-11-14 17:38:43 +00:00
~~~shell
nixos-rebuild --flake .#parsons [test|switch|dry-activate]
2022-11-14 17:38:43 +00:00
~~~
## Working on websites
Websites are exposed as flake outputs: if you're working on a website & want to
check it in a browser, do e.g.
~~~shell
nix run .#\"muc.hacc.earth\"
~~~
to start a local http server (note that some of our websites need a directory
to be built in; these use `/tmp/hacc-website`).
To add a new website, add a new subdirectory to `websites`; nix will generate a
vhost config based on that directory's name. Add a `default.nix` in your directory
describing how to build the website, and give its derivation a `watch` attribute
to make the `nix run` setup work.
## I don't want to build this long dependency / want a cached version!
If it's still available on parsons from a previous deploy, do:
```shell
nix copy --from ssh://parsons /nix/store/...
```
Note: don't just copy the .drv file (which Nix complains about if it can't
build something), that's just the description of how to build it! If you
don't know the actual outpath, look in the .drv file (should start with
`Derive([("out","[the path you want]"...`)
## committing to haccfiles
2022-11-14 17:38:43 +00:00
- Things on `main` should always reflect the config that's actually deployed on
parsons, except during testing / debugging sessions
- split up commits, every commit is one atomic change
2022-11-14 17:38:43 +00:00
- follow the commit format: "place: $change"
- place: e.g. `modules/$module`, `services/$service` ...
- change: describe your change. Please wrap your lines sensibly (or configure
your editor to do this for you)
- Exception: autogenerated messages (merge commits, reverts, etc)
2022-11-14 17:38:43 +00:00
- don't overuse merge commits, try to rebase things if possible with reasonable
effort