A docs/admin.txt

@@ -0,0 +1,54 @@
+
+Honk administration guide.
+
+This is the admin manual. Please refer to manual.txt for user documentation.
+
+-- css
+
+Custom CSS may be provided by creating a views/local.css file.
+
+-- message
+
+A custom server message may be set adding a ('servermsg', 'message') entry to
+the config table using sqlite3.
+
+-- emus and memes
+
+Custom emus may be provided by creating and populating the emus directory.
+emus may be referenced when composing a honk via colon wrapping. How pleasant.
+This :example: will be replaced by emus/example.png.
+
+To save disk space and avoid repeated uploads, the memes directory may be
+prepopulated with bandwidth wasting reactions and referenced by meme: filename.
+
+A list of available emus and memes appears in the funzone.
+
+-- cleanup
+
+One should occasionally run `honk cleanup` to free up internal space in the
+database. This deletes honks older than 30 days, but not those posted by a
+user.
+
+One may also run `honk reduce [honker]` to delete honks older than 3 days.
+This is useful to reduce the space requirements from following image bots.
+
+(Neither command runs vacuum, so the file size will not immediately shrink.)
+
+-- add user
+
+Running `honk adduser` can add additional users. This is discouraged.
+
+-- proxy
+
+honk requires a TLS terminating reverse proxy be configured. It communicates
+with other servers via https URLs.
+
+If the proxy is configured to support caching, be mindful of the fact that
+ActivityPub requests vary based on the Accept and Content-Type headers.
+
+ActivityPub in practice uses HTTP signatures to verify requests. In order for
+this to work, the backend server must receive certain header fields
+unmodified. In particular, the Host header and the message content cannot be
+altered.
+
+Specifically, for nginx: `proxy_set_header Host $http_host;`

M docs/manual.txt → docs/manual.txt

@@ -1,5 +1,7 @@
 
-Instructions for running of the honk.
+Instructions for using honk.
+
+This is the user manual. Please refer to admin.txt for administration.
 
 -- posting
 
@@ -67,26 +69,13 @@ As a special exception to the public honking rule, replies to limited messages
 will be restricted as much as possible. Note that ActivityPub leaks. Do
 not use honk for posting truly private information.
 
--- css
-
-Custom CSS may be provided by creating a views/local.css file.
-
--- message
-
-A custom server message may be set adding a ('servermsg', 'message') entry to
-the config table using sqlite3.
-
 -- emus and memes
 
-Custom emus may be provided by creating and populating the emus directory.
-emus may be referenced when composing a honk via colon wrapping. How pleasant.
-This :example: will be replaced by emus/example.png.
+A list of available emus and memes appears in the funzone.
 
-To save disk space and avoid repeated uploads, the memes directory may be
-prepopulated with bandwidth wasting reactions and referenced by meme: filename.
-Example: "Woah. meme: woahface.mp4"
+Emus such as :example: will be inlined into posts.
 
-A list of available emus and memes appears in the funzone.
+Memes such as `meme: example.mp4` will be appended to posts.
 
 -- hoots