Directory structure

bin -- small scripts for managing the stuff below
src -- codebase for generating website or conducting process. Anything bigger than a (small) script.
assets -- IP, including incoming articles, images, currently edited work, final products.
web -- the contents of our (static, public) website.
secrets -- passwords, PII, etc. Assume everything else could be made public. If it would be existentially bad for it to leak, encrypt it, and put it here.
doc -- documentation of processes, ideas, memos, etc.
llc -- corporate documents, financial ledger, business running.
.venv -- python environment for this whole kiboodle.

Quick Start

From a fresh clone:

make bootstrap        # Create venv, install deps, run migrations
source bin/a-activate # Activate the environment
make serve            # Start Django dev server on port 1969

Requires uv for dependency management.

Working Environment

To reactivate an existing environment:

. bin/a-activate

Editor-Only Content

Some content in editorial/inbox/ is encrypted so only editors can read it. This is for unpublished drafts and works-in-progress—not for secrets or confidential information (those belong in secrets/).

Why encrypt drafts?

• Upcoming articles shouldn't be publicly visible before publication
• Contributors may share work that isn't ready for the world yet
• The rest of the repo can remain public without leaking unfinished writing

How it works

We use md-age for transparent encryption. Files with this frontmatter are automatically encrypted in git:

---
age-encrypt: yes
age-recipients:
  - git:assets/keys/editors
---
Your markdown content here...

The git:assets/keys/editors reference points to a file listing editor public keys. When you check out the file, it's automatically decrypted (if you have a matching private key). When you commit, it's re-encrypted.

Setup

Run bin/a-setup-key to configure everything automatically:

bin/a-setup-key

This script:

• Creates an Ed25519 keypair (~/.ssh/almanack-age) compatible with both SSH and age
• Configures git to use md-age filters for transparent decrypt/encrypt
• Adds SSH config for the almnck git server alias
• Adds your public key to assets/keys/editors and commits it

After running, add the printed public key to your Forgejo account at https://code.almnck.com/user/settings/keys to complete git server access.

Adding a new editor

When a new editor runs a-setup-key, their key is added to assets/keys/editors. Then run md-age git rekey to re-encrypt all protected files with the new recipient.

Current editors

See assets/keys/editors for the list of public keys with access.