Copy-edits and comments

README.md

@@ -6,15 +6,16 @@ control the data. (Microsoft's recent approach to AI has me feeling real
 anxious about continuing to develop on there!)
 
 We like to use Ansible playbooks to keep track of how we set up our servers,
-here's how we've structured them! (We don't use very fancy Ansible features:
-these are all very basic commands, captured in script form for convenience!)
+here's how we've structured them! (We don't use very fancy Ansible features, we
+just use them as idempotent command-line scripts!)
 
 - `setup-users.yml`: Sets up the user accounts for the system, with their SSH
   keys for login.
 - `setup-security.yml`: Sets up firewall rules and automatic system updates.
   (This is a standard playbook I use for all my servers!)
 - `setup-forgejo.yml`: Sets up the Forgejo server itself, as a `systemd`
-  service running Forgejo's official Linux binary.
+  service running Forgejo's official Linux binary. This is mostly a 1:1 port
+  of [Forgejo's "Installation from binary" guide][fj-install]!
 
 You can run them individually, or all at once, with `run.sh`:
 
@@ -41,3 +42,4 @@ to note:
 Hope this helps!
 
 [fj]: https://forgejo.org/
+[fj-install]: https://forgejo.org/docs/latest/admin/installation-binary/

setup-forgejo.yml

@@ -46,6 +46,11 @@
         owner: root
         group: git
 
+    # NOTE: Instead of copying a pre-built app.ini, you could also skip this,
+    # use SSH tunneling to access the server over port 3000, and use their
+    # built-in setup process. You'd need to temporarily change /etc/forgejo to
+    # have mode "770", to allow Forgejo to write its own config file. (This is
+    # what we did for our first-time setup, then we copied app.ini to here!)
     - name: Copy app.ini to Forgejo's config directory
       copy:
         src: files/app.ini
@@ -54,6 +59,12 @@
       notify:
         - Restart Forgejo
 
+    # NOTE: Instead of having a separate secrets directory, you could hardcode
+    # the secrets into app.ini. This extra indirection just lets us share our
+    # app.ini publicly, while keeping the secret tokens in gitignored files.
+    # Also, the directory name "secrets" and the file names we chose aren't
+    # reserved by Forgejo! Forgejo simply ignores any unrecognized files in
+    # /etc/forgejo, then we reference our secret files by path in app.ini.
     - name: Copy secrets directory to Forgejo's config directory
       copy:
         src: files/secrets