mirror of
https://codeberg.org/grunfink/snac2.git
synced 2024-11-15 01:55:03 +00:00
301 lines
8.7 KiB
Groff
301 lines
8.7 KiB
Groff
.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 Building and Installation
|
|
A C compiler must be installed in the system, as well as the development
|
|
headers and libraries for OpenSSL and curl. To build
|
|
.Nm ,
|
|
run
|
|
.Bd -literal -offset indent
|
|
make
|
|
.Ed
|
|
.Pp
|
|
And, after that, 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 operate a Linux systemd-enabled system or OpenBSD, there are
|
|
startup scripts and configuration data in the
|
|
.Pa examples
|
|
directory.
|
|
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.
|
|
If you don't want any timeline purging and enjoy your data drives
|
|
fill up with old crap and finally burst in flames, you can disable
|
|
purging by setting this to 0 (this only applies to the private timeline,
|
|
the local timeline is never touched).
|
|
.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.
|
|
.It Ic disable_cache
|
|
If set to true, timeline caching is not done. This is only useful for
|
|
debugging purposes; don't enable it unless you know what do you want, as
|
|
it makes everything slower.
|
|
.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
|
|
From version 2.06, there is no longer a need to add a special
|
|
cron job for purging old data, as this is managed internally.
|
|
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.
|