initial repo docs

diff --git a/README.md b/README.md
new file mode 100644 (file)
index 0000000..768cead
--- /dev/null
+++ b/README.md
@@ -0,0 +1,65 @@
+# awful.systems infrastructure flake
+
+This is the Nix flake that deploys the awful.systems server infrastructure. It
+provides a set of files and commands that allow you to deploy the full set of
+awful.systems software and configuration for each host to anything running NixOS
+(though the provided commands default to the static IPs of the current
+awful.systems machines).
+
+## Requirements
+
+To use this flake, you'll want a [Nix evaluator](https://nixos.org/download) --
+that is, you'll want the Nix package manager (either on NixOS or in an
+environment where it's installed). This is a
+[dependency-free](https://www.haskellforall.com/2023/01/announcing-nixos-rebuild-new-deployment.html)
+stateless deployment mechanism, so this git repo and an authorized ssh key are
+all you need to deploy the whole stack.
+
+This flake builds everything locally for speed and then uploads it, so you'll
+want a fair bit of available disk space (20GB is safe) and the ability to upload
+a lot of data.
+
+*If you're not on x86_64-linux or you're limited on disk or upload*: you should
+use the deployment hosts to build. First, use `df -h` to make sure they've got
+enough disk space, then use the deployment command with the argument
+`--build-host root@<hostname>`, where `<hostname>` is the full domain name of
+the host you want to deploy to.
+
+## Optional Dependencies
+
+[nix-direnv](https://github.com/nix-community/nix-direnv) is convenient, since
+it'll make all of the awful.systems commands available in your shell with no
+other setup, and I use that to cache some larger dependencies as well.
+
+## Hosts
+### `more.awful.systems`
+- Hosts the production Lemmy server at https://awful.systems (`lemmy-prod`).
+- Proxies https://awful.systems/git and https://awful.systems/archives to
+  `these.awful.systems`.
+- Assumes it's running being a load balancer that terminates SSL, so it doesn't
+  handle anything related to HTTPS itself.
+
+### `these.awful.systems`
+- Hosts the development Lemmy server at https://making.awful.systems (`lemmy-dev`).
+- Hosts the r/SneerClub archive (`sneer-archive`).
+- Stores git repos in `/home/git/repos`.
+- Hosts `gitweb`.
+- Runs a git daemon for pull-only access to the git repos.
+
+## Commands
+
+If you have `nix-direnv`, these commands will be available in your shell after
+it finishes a build. Otherwise, run `nix develop` to kick off a build, and the
+resulting shell will have all of these commands available.
+
+- `deploy-these`: Kick off a deployment to the host `these`. Any arguments are
+  passed to `nixos-rebuild`.
+- `deploy-more`: Same as above for `more`.
+- `go-these`: Use your SSH key to log into `these` as `root`. Any arguments are
+  treated as commands for SSH to run; IE `go-these df -h` will run `df -h` on
+  `these`, display its output, and exit.
+- `go-more`: Same as above for `more`.
+- `rekey-secrets`: With a file argument, tells `sops` to re-encrypt the secrets
+  in that file with the currently configured encryption keys. Will definitely
+  need to be run by someone who previously has access to the secrets in order to
+  succeed.