add README.md

README.md

@@ -0,0 +1,86 @@
+# NixOS configs for toot.cat
+
+This repo contains all the configs to deploy toot.cat and its customized
+version of Mastodon. It is meant to be used with a flakes-aware version of `nix`
+(you may have to enable the `flakes` and `nix-command` experimental options in
+your configuration).
+
+We use [`git-crypt`](https://www.agwa.name/projects/git-crypt/) to encrypt our
+deployment secrets (found in the `secrets` subdirectory of this repository).
+
+[`colmena`](https://github.com/zhaofengli/colmena) is used for deployment.
+
+## Shell configuration
+
+`shell.nix` provides an environment with the tools required for deployment.
+You can enter the shell environment by running `nix develop` in the project
+directory.
+
+If you use [`direnv`](https://direnv.net/), there is a `.envrc` file that will
+automatically load the shell environment with nix.
+
+## Setting up secrets
+
+Some files in this repository are transparently encrypted with `git-crypt` and
+require extra steps to work with for deployment or otherwise. **There are not
+currently any checks in place to ensure you don't deploy encrypted secrets. If
+you deploy secrets without decrypting them, things WILL break.**
+
+Unfortunately, there is no `git-crypt` subcommand to check if the secrets are
+currently decrypted or not (https://github.com/AGWA/git-crypt/issues/69). One
+suggested way is to run `git config --local --get filter.git-crypt.smudge`. If
+the command outputs the text `git-crypt smudge` (verbatim) then it is unlocked.
+If the command outputs nothing, it is locked.
+
+If you have a gpg key that is registered with git-crypt in this repository, you
+can decrypt secrets with `git-crypt unlock`. You will be prompted to enter your
+gpg passphrase or touch your hardware token.  If you have a symmetric secret key
+file, use `git-crypt unlock /path/to/keyfile`.
+
+## Backups
+
+The `services.postgresqlBackup` NixOS module (enabled in `mastodon.nix`)
+provides a systemd service and timer that will automatically back up the
+Mastodon database to `/var/backup/postgresql/mastodon.sql.gz` at 01:15 every
+day (defaulting to UTC unless `time.timeZone` is set).
+
+To create a backup immediately, you can connect to the server via ssh and run
+`systemctl start postgresqlBackup-mastodon.service`. This command will exit when
+the backup is complete.
+
+## Deployment
+
+To deploy, simply run `colmena apply`. This will automatically build the system
+and its dependencies including Mastodon, push everything to the server, and
+restart appropriate services.
+
+If any service fails to restart properly, the deployment will be rolled back and
+logs for the failed service will be printed to the terminal.
+
+The Mastodon service automatically runs database migrations when deploying.
+This might take a significant amount of time. **Before deploying, you should
+take care to back up the database. There is no automatic rollback for database
+migrations, so Mastodon may fail to start if migrations took place before the
+rollback.** If this happens, restoring the database backup should fix the issue.
+
+## Updating
+
+Nix files for our customized version of Mastodon are in the `mastodon`
+subdirectory. These are automatically generated by the `update.sh` script in the
+root of the repository.
+
+To update, simply run `./update.sh` **from the root of the repository**. This
+will update `flake.lock`, fetch the latest version from the repository url
+specified at the top of the script and regenerate the files in the `mastodon`
+subdirectory.
+
+Sometimes the last step of the update script will time out and fail while
+fetching something from the yarn registry. If this happens, you can try running
+the update script again.
+
+## Other notes
+
+Currently, the nixpkgs url is fixed to a personal fork of nixpkgs which contains
+[these improvements](https://github.com/NixOS/nixpkgs/pull/174202). Once these
+are merged and make it into the nixos-unstable channel, the url at the top of
+`flake.nix` should be changed back.