1 files changed, 326 insertions, 0 deletions

diff --git a/doc/snac.8 b/doc/snac.8
new file mode 100644
index 0000000..94afe71
--- /dev/null
+++ b/doc/snac.8
@@ -0,0 +1,326 @@
+.Dd $Mdocdate$
+.Dt SNAC 8
+.Os
+.Sh NAME
+.Nm snac
+.Nd snac administration
+.Sh DESCRIPTION
+The
+.Nm
+daemon processes messages from other servers in the Fediverse
+using the ActivityPub protocol.
+.Pp
+This is the admin manual. For user operation, see
+.Xr snac 1 .
+For file and data formats, see
+.Xr snac 5 .
+.Ss Installation
+Install the OpenSSL and urllib3 Python3 external packages, and run as root
+.Bd -literal -offset indent
+make install
+.Ed
+.Ss Database Initialization
+Once
+.Nm
+is properly installed on the system, designate a directory where
+the server and user data are to be stored. This directory
+must not exist yet.
+.Nm
+must always be run as a regular user; you can create one for
+it or use your own. To initialize the database, execute
+.Bd -literal -offset indent
+snac init $HOME/snac-data
+.Ed
+.Pp
+A small set of questions will be asked regarding the installation,
+specially the host name it will run under, the local network address
+and port
+.Nm
+will listen to, the optional path prefix and possibly other things.
+.Pp
+You can launch the
+.Nm
+process by running
+.Bd -literal -offset indent
+snac httpd $HOME/snac-data
+.Ed
+.Pp
+Use a web browser to connect to the specified address and port. You
+should see a greeting page.
+.Pp
+Log messages are sent to the standard error stream. By default, only
+relevant information is written there. You can increase the debugging
+level by editing the 'dbglevel' field in the
+.Pa server.json
+file or by setting a numeric value between 0 and 3 to the DEBUG
+environment variable, see below.
+.Pp
+If you run
+.Nm
+in an OS controlled by
+.Xr systemd 1 ,
+you can prepare a user service to start/stop the daemon. Following the
+previous example, create the file
+.Pa ~/.config/systemd/user/snac.service
+with the following content:
+.Bd -literal -offset indent
+[Unit]
+Description=snac daemon
+
+[Service]
+Type=simple
+Restart=always
+RestartSec=5
+ExecStart=/usr/local/bin/snac httpd /path/to/snac-data
+
+[Install]
+WantedBy=default.target
+.Ed
+.Pp
+And activate it by running
+.Bd -literal -offset indent
+systemctl --user enable snac.service
+systemctl --user start snac.service
+.Ed
+.Pp
+For other operating systems, please read the appropriate documentation
+on how to install a daemon as a non-root service.
+.Ss Server Setup
+.Pp
+An http server with TLS and proxying support must already be
+installed and configured.
+.Nm
+runs as a daemon and listens on a TCP/IP socket, preferrably
+on a local interface. It can serve the full domain or only
+a directory. The http server must be configured to route to the
+.Nm
+socket all related traffic and also the webfinger standard
+address. The Host header must be propagated.
+See the examples below.
+.Ss Adding Users
+.Pp
+Users must be created from the command line.
+You can do it by running
+.Bd -literal -offset indent
+snac adduser $HOME/snac-data
+.Ed
+.Pp
+All needed data will be prompted for. There is no artificial limit
+on the number of users that can be created.
+.Ss Customization
+The
+.Pa server.json
+configuration file allows some behaviour tuning:
+.Bl -tag -width tenletters
+.It Ic host
+The host name.
+.It Ic prefix
+The URL path prefix.
+.It Ic address
+The listen network address.
+.It Ic port
+The list network port.
+.It Ic dbglevel
+The debug level. An integer value, being 0 the less verbose (the default).
+.It Ic layout
+The disk storage layout version. Never touch this.
+.It Ic queue_retry_max
+Messages sent out are stored in a queue. If the posting of a messages fails,
+it's re-enqueued for later. This integer configures the maximum count of
+times the sending will be retried.
+.It Ic queue_retry_minutes
+The number of minutes to wait before the failed posting of a message is
+retried. This is not linear, but multipled by the number of retries
+already done.
+.It Ic max_timeline_entries
+This is the maximum timeline entries shown in the web interface.
+.It Ic timeline_purge_days
+Entries in the timeline older that this number of days are purged.
+.It Ic css_urls
+This is a list of URLs to CSS files that will be inserted, in this order,
+in the HTML before the user CSS. Use these files to configure the global
+site layout.
+.El
+.Pp
+You must restart the server to make effective these changes.
+.Pp
+If a file named
+.Pa greeting.html
+is present in the server base directory, it will be returned whenever
+the base URL of the server is requested. Fill it with whatever
+information about the instance you want to supply to people
+visiting the server, like sign up requirements, site policies
+and such. The special %userlist% mark in the file will cause
+the list of users in this instance to be inserted.
+.Pp
+Users can change a bit of information about themselves from the
+web interface. See
+.Xr snac 1
+for details. Further, every user has a private CSS file in their
+.Pa static/style.css
+that can be modified to suit their needs. This file contains
+a copy of the
+.Pa style.css
+file in the server root and it's inserted into the HTML output.
+It's not easily accesible from the web interface to avoid users
+shooting themselves in the foot by destroying everything.
+.Ss Old Data Purging
+The Fediverse generates big loads of data that get old and
+stale very quickly. By default, 
+.Nm
+does not delete anything; you must do it explicitly by issuing a
+.Ar purge
+command periodically. A cron entry will suffice. You can add the
+following to the
+.Nm
+user's crontab:
+.Bd -literal -offset indent
+# execute a data purge on Sundays at 4 am
+0 4 * * 0 /usr/local/bin/snac purge /path/to/snac-data
+.Ed
+.Pp
+Other directories, like
+.Pa archive/ ,
+can grow very quickly if the debug level is greater than 0. These
+files must be deleted manually.
+.Pp
+The user-generated data (the local timeline) is never deleted.
+.Ss ActivityPub Support
+These are the following activities and objects that
+.Nm
+supports:
+.Bl -tag -width tenletters
+.It Vt Follow
+Complete support, on input and output.
+.It Vt Undo
+For
+.Vt Follow ,
+.Vt Like
+and
+.Vt Announce
+objects, on input and output.
+.It Vt Create
+For
+.Vt Note
+objects, on input and output.
+.It Vt Accept
+For
+.Vt Follow
+objects, on input and output.
+.It Vt Like
+For
+.Vt Note
+objects, on input and output.
+.It Vt Announce
+For
+.Vt Note
+objects, on input and output.
+.It Vt Update
+For
+.Vt Person
+objects, on input and output. Support for updating
+.Vt Note
+objects will probably be added in the future.
+.It Vt Delete
+Supported for
+.Vt Note
+and
+.Vt Tomsbtone
+objects on input, and for
+.Vt Note
+objects on output.
+.El
+.Pp
+The rest of activities and objects are dropped on input.
+.Pp
+There is partial support for
+.Vt OrderedCollection
+objects in the
+.Pa /outbox 
+(with the last 20 entries of the local timeline shown). No pagination
+is supported. Intentionally, the
+.Pa /followers
+and
+.Pa /following
+paths return empty lists.
+.Ss Other Considerations
+.Nm
+stores all the messages it receives as JSON files, which are usually
+bloated and filled with redundant information. Using a filesystem with
+file compression enabled (like btrfs or zfs) will probably be a good
+choice to store the
+.Nm
+database into.
+.Sh ENVIRONMENT
+.Bl -tag -width Ds
+.It Ev DEBUG
+Overrides the debugging level from the server 'dbglevel' configuration
+variable. Set it to an integer value. The higher, the deeper in meaningless
+verbiage you'll find yourself into.
+.El
+.Sh EXAMPLES
+You want to install the
+.Nm
+Fediverse daemon in the host example.com, that is correctly configured
+with a valid TLS certificate and running the nginx httpd server.
+The service will be installed under the
+.Pa fedi
+location. Two users, walter and jessie, will be hosted in the system.
+Their Fediverse presence addresses will be https://example.com/fedi/walter
+and https://example.com/fedi/jesse, respectively. They will be known
+in the Fediverse as @walter@example.com and @jesse@example.com. The
+.Nm
+daemon will run as the user snacusr in the system and listen to the
+localhost:8001 network socket. All data will be stored in the
+.Pa /home/snacusr/fedidata
+directory.
+.Pp
+Log into the system as snacusr and execute:
+.Bd -literal -offset indent
+snac init /home/snacusr/fedidata
+.Ed
+.Pp
+Answer "example.com" to the host name question, "/fedi" to the path
+prefix question, "localhost" to the address and "8001" to the port.
+.Pp
+Create the users
+.Bd -literal -offset indent
+snac adduser /home/snacusr/fedidata walter
+snac adduser /home/snacusr/fedidata jesse
+.Ed
+.Pp
+Answer the questions with reasonable values.
+.Pp
+Execute the server:
+.Bd -literal -offset indent
+snac httpd /home/snacusr/fedidata
+.Ed
+.Pp
+Edit the nginx configuration and add the following snippet to the
+example.com server section:
+.Bd -literal -offset indent
+location /.well-known/webfinger {
+    proxy_pass http://localhost:8001;
+    proxy_set_header Host $http_host;
+}
+
+location /fedi {
+    proxy_pass http://localhost:8001;
+    proxy_set_header Host $http_host;
+}
+.Ed
+.Pp
+Restart the nginx daemon and connect to https://example.com/fedi/walter.
+The empty, default screen will be shown. Enter the admin section with the
+credentials defined for this user. Search people, start following
+them, engage in arid discussions and generally enjoy the frustrating
+experience of Social Media.
+.Sh SEE ALSO
+.Xr snac 1 ,
+.Xr snac 5
+.Sh AUTHORS
+.An grunfink
+.Sh LICENSE
+See the LICENSE file for details.
+.Sh CAVEATS
+JSON files are fragile when modified by hand. Take care.