Imported documentation from snac 1.x.

7 files changed, 668 insertions, 0 deletions

diff --git a/doc/snac.1 b/doc/snac.1
new file mode 100644
index 0000000..f2ed24d
--- /dev/null
+++ b/doc/snac.1
@@ -0,0 +1,208 @@
+.Dd $Mdocdate$
+.Dt SNAC 1
+.Os
+.Sh NAME
+.Nm snac
+.Nd A simple, minimalistic ActivityPub instance
+.Sh SYNOPSIS
+.Nm
+.Cm command
+.Ar basedir
+.Op Ar option ...
+.Sh DESCRIPTION
+The
+.Nm
+daemon processes messages from other servers in the Fediverse
+using the ActivityPub protocol.
+.Pp
+This is the user manual and expects an already running
+.Nm
+installation. For the administration manual, see
+.Xr snac 8 .
+For file and data formats, see
+.Xr snac 5 .
+.Ss Web Interface
+The web interface provided by
+.Nm
+is split in two data streams: the public timeline and the
+private timeline. There are no other feeds like the server-scoped
+or the federated firehoses provided by other similar ActivityPub
+implementations like Mastodon or Pleroma.
+.Pp
+The public timeline, also called the local timeline, is what an
+external visitor sees about the activity of a
+.Nm
+user: that is, only the list of public notes, boosts and likes
+the user generates or participates into. This is, obviously,
+read-only, and not very remarkable, unless the user publishes
+messages of staggering genious. A set of history links, grouped
+by month, will also be available at the bottom of the page.
+.Pp
+The private timeline, or simply the timeline, is the private,
+password-protected area of a
+.Nm
+server where the user really interacts with the rest of the
+Fediverse.
+.Pp
+The top area of the timeline provides a big text area to write
+notes for the public (i.e. for the user followers). As this is
+the second most important activity on the Fediverse, this is
+located in the most prominent area of the user page. You can
+enter plain text, @user@host mentions and other things. See the
+.Xr snac 5
+manual for more information on the allowed markup.
+.Pp
+More options are hidden under a toggle control. They are the
+following:
+.Bl -tag -offset indent
+.It Follow (by URL or user@host)
+Fill the input area with a user 'actor' URL or a user@host
+Fediverse identifier to follow.
+.It Boost (by URL)
+Fill the input area with the URL of a Fediverse note to be
+boosted.
+.It User setup...
+This option opens the user setup dialog.
+.El
+.Pp
+The user setup dialog allows some user information to be
+changed, specifically:
+.Bl -tag -offset indent
+.It User name
+Your user name, or not really that. People like to include
+emojis, flags and strange symbols for some reason.
+.It Avatar URL
+The URL of a picture to be used as your avatar in timelines
+around the world.
+.It Bio
+Enter here a bunch of self-indulgent blurb about yourself.
+The same markup options available for text notes apply here.
+.It Password
+Write the same string in these two fields to change your
+password. Don't write anything if you don't want to do this.
+.El
+.Pp
+The rest of the page contains your timeline in reverse
+chronological order (i.e., newest interactions first).
+.Nm
+shows the conversations as nested trees, unlike other Fediverse
+software; everytime something new is added to a conversation,
+the full thread is bumped up, so new interactions are shown
+always at the top of the page while the forgotten ones languish
+at the bottom.
+.Pp
+Private notes (a.k.a. direct messages) are also shown in
+the timeline as normal messages, but marked with a cute lock
+to mark them as non-public. Replies to direct messages are
+also private and cannot be liked nor boosted.
+.Pp
+For each entry in the timeline, a set of reasonable actions
+in the form of buttons will be shown. These can be:
+.Bl -tag -offset indent
+.It Reply
+Unveils a text area to write your intelligent and acute comment
+to an uninformed fellow. This note is sent to the original
+author as well as to your followers. The note can include
+mentions in the @user@format; these people will also become
+recipients of the message. If you reply to a boost or like,
+you are really replying to the note, not to the admirer of it.
+.It Like
+Click this if you admire this post. The poster and your
+followers will be informed.
+.It Boost
+Click this if you want to propagate this post to all your
+followers. The original author will also be informed.
+.It Follow
+Click here if you want to start receiving all the shenanigans
+the original author of the post will write in the future.
+.It Unfollow
+Click here if you are fed up of this fellow's activities.
+.It Delete
+Click here to send this post to the bin. If it's an activity
+written by you, the appropriate message is sent to the rest
+of involved parts telling them that you no longer want your
+thing in their servers (not all implementations really obey
+this kind of requirements, though).
+.It MUTE
+This is the most important button in
+.Nm
+and the Fediverse in general. Click it if you don't want
+to read crap from this user again in the forseeable future.
+.El
+.Ss Command-line options
+The command-line tool provide the following commands:
+.Bl -tag -offset indent
+.It Cm init Op basedir
+Initializes the database. This is an interactive command; necessary
+information will be prompted for. The
+.Ar basedir
+directory must not exist.
+.It Cm check Ar basedir Op uid
+Does a minimal health check to the database and its users. If a
+user id is provided, only this user will be checked.
+.It Cm purge Ar basedir Op uid
+Purges old data from the timeline of all users. If a user id is
+provided, only this user's timeline will be purged.
+.It Cm adduser Ar basedir Op uid
+Adds a new user to the server. This is an interactive command;
+necessary information will be prompted for. Also, a copy of
+the server
+.Pa style.css
+is installed in the user's
+.Pa static/
+directory.
+.It Cm httpd Ar basedir
+Starts the daemon.
+.It Cm queue Ar basedir Ar uid
+Processes the output queue of the specied user, sending all
+enqueued messages and re-enqueing the failing ones. This command
+must not be executed if the server is running.
+.It Cm update Ar basedir Ar uid
+Enqueues a user information Update message to all followers.
+.It Cm passwd Ar basedir Ar uid
+Changes the password for a user (interactive).
+.It Cm follow Ar basedir Ar uid Ar actor
+Sends a Follow message for the specified actor URL.
+.It Cm unfollow Ar basedir Ar uid Ar actor
+Sends an Unfollow message for the specified actor URL.
+.It Cm mute Ar basedir Ar uid Ar actor
+Mutes an actor for the specified user. This is the most important
+command for the Fediverse. The user will no longer receive nor
+read another activity from the specified moron.
+.It Cm unmute Ar basedir Ar uid Ar actor
+In case a muted moron is no longer a moron, it can be unmuted
+this way. This is the least used command ever.
+.It Cm like Ar basedir Ar uid Ar url
+Enqueues a Like message for a post given its url.
+.It Cm announce Ar basedir Ar uid Ar url
+Enqueues an Announce (boost) message for a message post its url.
+.It Cm request Ar basedir Ar uid Ar url
+Requests an object and dumps it to stdout. This is a very low
+level command that is not very useful to you.
+.It Cm note Ar basedir Ar uid Ar text
+Enqueues a Create + Note message to all followers. If the
+.Ar text
+argument is - (a lonely hyphen), the external editor defined
+by the EDITOR environment variable will be invoked to prepare
+a message.
+.El
+.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.
+.It Ev EDITOR
+The user-preferred interactive text editor to prepare messages.
+.El
+.Sh SEE ALSO
+.Xr snac 5 ,
+.Xr snac 8
+.Sh AUTHORS
+.An grunfink
+.Sh LICENSE
+See the LICENSE file for details.
+.Sh CAVEATS
+Use the Fediverse sparingly. Don't fear the mute button.
+.Sh BUGS
+Plenty. Some issues may be documented in the TODO.md file.
diff --git a/doc/snac.5 b/doc/snac.5
new file mode 100644
index 0000000..a5311e4
--- /dev/null
+++ b/doc/snac.5
@@ -0,0 +1,131 @@
+.Dd $Mdocdate$
+.Dt SNAC 5
+.Os
+.Sh NAME
+.Nm snac
+.Nd message formatting and file format documentation
+.Sh DESCRIPTION
+The
+.Nm
+daemon processes messages from other servers in the Fediverse
+using the ActivityPub protocol.
+.Pp
+This manual describes the allowed formatting of note messages
+and the disk storage layout of
+.Nm
+server and user data. For the operation manual, see
+.Xr snac 1 .
+For the administration manual, see
+.Xr snac 8 .
+.Ss Message Formatting
+Message notes respect the entered new line breaks rigurously.
+A special subset of Markdown is allowed, including:
+.Bl -tag -width tenletters
+.It bold
+**text between two pairs of asterisks**
+.It italic
+*text between a pair of asterisks*
+.It code
+Text `between backticks` is formatted as code.
+.Bd -literal
+```
+/* text between lines with only three backticks is preformatted */
+int main(int argc, char *argv[])
+{
+    return 0;
+}
+
+```
+.Ed
+.It links
+Standalone URLs.
+.It quoted text
+Lines starting with >.
+.It User Mentions
+Strings in the format @user@host are requested using the Webfinger
+protocol and converted to links and mentions if something reasonable
+is found.
+.El
+.Pp
+HTML tags are left untouched. This is probably a bad idea that may
+change in future versions.
+.Pp
+.Ss Disk Layout
+This section documents version 1 of the disk storage layout. It's still
+subject to change.
+.Pp
+The base directory contains the following files and folders:
+.Bl -tag -width tenletters
+.It Pa server.json
+Server configuration.
+.It Pa user/
+Directory holding user subdirectories.
+.El
+.Pp
+Each user directory is a subdirectory of 
+.Pa BASEDIR/user/ ,
+has the user id as name and contains the following subdirectories and files:
+.Bl -tag -width tenletters
+.It Pa user.json
+User configuration file.
+.It Pa key.json
+SHA-1 secret/public key PEM data.
+.It Pa actors/
+This subdirectory stores cached 'Person' ActivityPub messages as JSON files. Each
+file name is an MD5 hash of the actor URL.
+.It Pa timeline/
+This subdirectory stores the user's timeline. Everytime a valid message arrives,
+it's stored in this directory as a JSON object. The file name spec is: a Unix
+timestamp followed by a hyphen followed by an MD5 of the message Id. Additionally,
+metadata for each message parent and children is stored under the '_snac' field;
+parent messages with new children are renamed with an updated timestamp so that
+the more recently updated thread is shown at the top. This directory is presented
+in the web interface in reverse file name order up to a maximum, hardcoded limit.
+These files are purged when they are considered old (this time can be changed by
+tweaking the server configuration).
+.It Pa local/
+This subdirectory stores all activities generated by this user as hardlinks to
+their analogue entries in the
+.Pa timeline/
+subdirectory. These files are never deleted.
+.It Pa followers/
+This subdirectory stores the 'Follow' ActivityPub message from each
+Fediverse user that is following this user as a JSON file. Each file name is
+an MD5 hash of the actor that is a follower of this user.
+.It Pa following/
+This subdirectory stores the 'Follow' (not yet confirmed) or the 'Accept'
+(confirmed) ActivityPub message for each actor that is being followed. Each file
+name is an MD5 hash of the actor.
+.It Pa muted/
+This directory contains files which names are MD5 hashes of muted actors. The
+content is a line containing the actor URL.
+Messages from these actors will be ignored on input and not shown in any timeline.
+.It Pa queue/
+This directory contains the output queue of messages generated by the user as
+JSON files. File names contain timestamps that indicate when the message will
+be sent. Messages not accepted by their respective servers will be re-enqueued
+for later retransmission until a maximum number of retries is reached,
+then discarded.
+.It Pa static/
+Files in this directory are served as-is when requested from the
+.Pa https://HOST/s/...
+URL path. A special file named
+.Pa style.css
+can contain user-specific CSS code to be inserted into the HTML of the
+web interface.
+.It Pa history/
+This directory contains generated HTML files. They may be snapshots of the
+local timeline in previous months or other cached data.
+.It Pa archive/
+This directory stores all input/output traffic of ActivityPub messages. There
+is a different file for each day. This information is only stored if
+.Nm
+is run with a debug level >= 1.
+.El
+.Sh SEE ALSO
+.Xr snac 1 ,
+.Xr snac 8
+.Sh AUTHORS
+.An grunfink
+.Sh LICENSE
+See the LICENSE file for details.
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.
diff --git a/doc/susie.png b/doc/susie.png
new file mode 100644
index 0000000..99f19bc
--- /dev/null
+++ b/doc/susie.png
diff --git a/doc/susie.txt b/doc/susie.txt
new file mode 100644
index 0000000..e361642
--- /dev/null
+++ b/doc/susie.txt
@@ -0,0 +1,3 @@
+data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAABAAAAAQAQAAAA
+A3iMLMAAAAO0lEQVQI1wEwAM//AAZgAAcwAA/4AAPkAB3cAAPgAKXIAKfIAH/
+8AD/8ADw8AB56AA/2AEPtAMwfAO+/UlQP2C3B0yEAAAAASUVORK5CYII=
diff --git a/doc/susie32.png b/doc/susie32.png
new file mode 100644
index 0000000..0269607
--- /dev/null
+++ b/doc/susie32.png
diff --git a/doc/susie64.png b/doc/susie64.png
new file mode 100644
index 0000000..739d154
--- /dev/null
+++ b/doc/susie64.png