FediRoster

FediRoster is a web application to host an opt-in public list of fediverse accounts. Its purpose is to assist communities to more easily find people with shared interests on Mastodon and other connected platforms. People are able to add themselves to the list via proof of account ownership.

It is a slightly more heavyweight alternative to David Adler’s Sociologists on Mastodon software. It is intended to function as a public list of Mastodon and other fediverse accounts, geared primarily towards academic communities, but suitable for others as well. It offers functions for following listed accounts individually or in bulk. The main novelty here is that you can add yourself to the list through an authentication process instead of all the work falling on a list maintainer. You can sign in through your Mastodon account or send a message to the list’s bot to verify your account ownership. This also means that the hosting process for new lists is a bit more involved (it’s a Python/WSGI application).

It was first developed for the HCI Directory, a list of human-computer interaction researchers on the fediverse. It has since been released as an open source project that can be self-hosted. Its current state is stable, but not quite ready for widespread use. Administrators willing to experiment and to keep up with version upgrades can now get a head start.

Project website: https://fietkau.software/fediroster

Requirements

A FediRoster installation requires a reasonably recent Python 3 environment. I have tested it on Python 3.11. Beyond the standard library, it requires the modules flask and requests. If a required module is missing, it will tell you when you try to run it.

You can run FediRoster through Flask’s local development server for testing and configuration, but a long-term installation will need a proper WSGI server. I personally use Apache 2.4 with the wsgi module, because I already use the same web server for all my other projects. If you prefer nginx or something else, check its WSGI capabilities. I can’t give any informed recommendations on this.

In addition to a WSGI-capable web server, FediRoster relies on background tasks getting handled behind the scenes. This can be done either through a persistent system service/daemon or through scheduled calls from something like cron. More on both possibilities in the “Server installation” section.

The web frontend requires a modern browser with JavaScript enabled.

A running, public list will also require a Mastodon bot account. You do not need administrative functions on the Mastodon server that you’ll run your bot on, but if the Mastodon server in question is not your own, make sure to get permission ahead of time. Many public servers have separate rules and restrictions on bot accounts.

Setup Overview

To get started, you can simply clone the repository (git clone https://fietkau.software/FediRoster.git) and then run main.py. If your Python environment lacks any required modules, that will be the first thing you’ll find out. The script will also perform a few environmental checks and let you know if the database directory needs to be made writable. When you get the Usage text after running the script, the basic preconditions are met.

Next you should run main.py --interactive to get a local Flask server. It’ll tell you the URL to connect to in your web browser, where you should see a new empty list. Now is a good time to check out config.py, where you can adjust the administrative configuration of your FediRoster installation. The configuration file contains detailed explanations for each setting, so please do not be intimidated by its length and make sure to read about what you are modifying. It is very heavily recommended to go through the entire config file before making an attempt to open your list to the public.

If you’d like to change your list’s icon, you need to replace the three files icon.ico, icon-small.png and icon-large.png in the static subdirectory. The icon creator on the FediRoster website will give you all three in the correct sizes.

For account confirmations and new list addition shoutouts (unless you have disabled the latter in your config file), you will need to set up a Mastodon bot account. More on that in the following section.

If you are satisfied with your first impression and would like to convert your testing environment into a permanent FediRoster instance, proceed to the “Server Installation” section.

Mastodon Bot Configuration

FediRoster uses one Mastodon bot account for account confirmations and for new list addition shoutouts. Because the former option can currently not be disabled, having a bot account is a mandatory part of the software setup. You can use your own Mastodon server to host the bot account if you wish, or you can use an external Mastodon server, assuming it allows you to set up a bot account for this purpose. You may want to confirm this with the server administration ahead of time.

Register your Mastodon bot account as normal, make sure it uses an existing email address with an inbox that will reach you in case of issues, and give it a strong password. You can configure the public profile as you wish, add a nice profile picture and header image, a bio that’ll help people understand the bot’s purpose, etc. Make sure the “This is an automated account” box is checked. After you have fully set up the bot’s information in your FediRoster config file, the list itself will contain a meta tag which works for Mastodon account verification if you enter the list as a link in the bot’s profile.

I also recommend setting up the bot account so old posts are automatically deleted after a relatively short time (I have mine set to two weeks). The list addition shoutouts are designed so people don’t have to keep checking the website for new additions, but this functionality has to be weighed against the interests of people who want to delete their own information. They can delete their account from the public list, but they cannot delete old bot posts. As a list operator, it is in your own interest too not to accidentally set up a long-term “shadow record” of your list contents.

After the bot’s profile is configured to your liking, visit the “Development” tab in the Mastodon preferences. There you will be required to set up a new application to let FediRoster act through the bot account. The application’s name can be whatever you want (though keep in mind people will be able to see it under the bot’s posts), the website should be the URL for your new list. You can leave the redirect URI as is. For scopes, uncheck the default read, write and follow scopes, and instead check read:accounts, read:notifications, read:statuses and write:statuses, which are all that’s needed for the bot to function. After you have submitted your application, it will show you various confidential digital keys. The access token is needed for your FediRoster configuration file – it is what lets the software act through the bot’s account.

And that’s all for the bot configuration. After you’ve set everything up, adjusted your FediRoster config file and reloaded the WSGI app, you should be able to see the bot make posts whenever an account is added to the list. You can also test the post-hoc verification process now.

Server Installation

FediRoster should be compatible with any WSGI-capable web server, although I have only tested it with Apache, where you will need the wsgi module (available in the libapache2-mod-wsgi-py3 package on a recent Ubuntu Linux). Create a virtual host for your FediRoster instance and configure it as necessary. My Apache configuration looks like this:

ServerName fediroster.example.com

WSGIDaemonProcess fediroster user=www-data group=www-data threads=5 home=/var/www/fediroster/
WSGIScriptAlias / /var/www/fediroster/app.wsgi

<Directory /var/www/fediroster>
    WSGIProcessGroup fediroster
    WSGIApplicationGroup %{GLOBAL}
    WSGIScriptReloading On
    Require all granted
</Directory>

# Plus the normal stuff for logging, certs, etc...

Make sure the provided app.wsgi file along with everything else can be found by the web server. Again, the user account running the web server needs to be able to write to the data subdirectory. On my Ubuntu server, I usually change the directory’s group to www-data and make it group-writable. Everything else can be read-only. If you want, you can copy over your local database from the previous section, but if you do, you will need to manually empty the mastodon_servers table (existing entries will fail if the base URL for the list has changed). Enable the virtual host, follow any instructions your web server gives you, and you should have an accessible FediRoster installation.

If you use certbot for your website certificate management, note that it is easiest to generate certificates for your virtual host before you do the WSGI configuration. Because certbot copies your virtual host configuration file, clashes arise if the virtual host configures a WSGI environment.

In addition to the WSGI component, you now need to decide how you want to handle the FediRoster background process. Of the two options available, I use the persistent service mode as a systemd daemon. The service configuration file looks like this:

[Unit]
Description=FediRoster daemon
After=network.target

[Service]
User=www-data
ExecStart=/usr/bin/python3 -u /var/www/fediroster/main.py --background

[Install]
WantedBy=multi-user.target

Note how the script is being started with the --background parameter, which makes it run persistently and handle background tasks as they arise. Running the background service under the same user account as the web server makes pragmatic sense to ensure they have the same access rights to the database.

If you want to avoid running it as a persistent service and would rather use cron or a similar service to call the script regularly, you can configure the script call in much the same way: use the same user account as the web server if possible, add a custom parameter. Though in this case, instead of --background it should be --background-and-terminate. This way, the script will perform any background tasks that are pending (with one second breaks in between) and then terminate itself when there is nothing more to do. I recommend setting it up so the background script gets called often, every few seconds ideally or every few minutes at most. If not, your users may spend a long time waiting.

And with that you should have a fully functional FediRoster installation!

List Administration

In the FediRoster config file, you can set a list of administrator accounts. These accounts have elevated privileges on the list website. There is no dedicated admin log-in button, but if you click “Add me to the list” and choose to authenticate via your Mastodon account, you can exit the “add or edit” form without saving and return to the main list view, now logged in (there will be a bar at the top of the page).

If you are logged in as one of the admin accounts, you can keep an eye on the top right of the page. FediRoster will alert you if there are any problems with the backend process.

You also get to see a list of currently pending account submissions that are not yet verified. For each of them, you can manually perform the verification from the web interface if you’re certain the submission has come from the person in question.

As an admin, you have the option to add, edit, or delete list entries. Use this ability with great restraint. Participants trust that they are in charge of their own personal information and can decide for themselves when to make changes. It’s one thing if someone asks you to correct a typo for which they don’t feel like going through the authentication process again, but you should not take action on someone else’s behalf unless you are completely sure it is what the person wants, and you should never make additions to your list just because you think someone “should” be on it.

You can also read and manage the block list. Your FediRoster installation has a block list that can contain entries added manually or imported from a Mastodon server block list (more on that in a bit). The block list table lets you add new blocks by entering an address to be blocked, which must be either a fediverse account name in the “double @” format, i.e. @person@example.com, or just a server name. Along with the block address, you can optionally store a reason, which is just a text field for supplemental information for the block. If a new list addition matches a block list entry, either through an exact account match or a fully blocked server, it is not added to the list and the submitter receives a message to that effect.

In addition to entering blocks one by one, you have the option of importing a domain block list from a Mastodon server you run. If you go into the Mastodon preferences, then to “Moderation,” “Federation” and then click “Export,” you will receive a file named domain_blocks.csv which contains all the server-wide blocks configured on this server. Copy this file into your FediRoster installation’s data directory, and the software will pick it up and honor all its blocks for your account list as well. (Exported personal block lists are currently not supported.)

By the way: FediRoster comes with a templated privacy policy. Make sure to check it over to see if everything aligns with your own practices.

FAQ

A few questions that I have come across in FediRoster’s short lifetime:

Is it possible to add fields for academic credentials? I would like to be able to filter my list by position / team size / number of publications / etc.

I understand how these kinds of information could be useful, but they run counter to the intended function of FediRoster, which is to connect people on social media on equal footing. As such, they will not be added to the software. The people on your list are of course free to use their name and keywords fields however they want, including for their official job titles if that is something they or your community at large values.

Why are the list shoutout posts by the bot always set to “Followers only”? I would like to configure them to be public.

The bot posts are deliberately coded so that they are only visible to existing followers. As described in the bot setup section, there are good reasons to not have a public duplicate of the contents of the list as they get added. It is a minor downside that people cannot boost their own list entry bot post, but overall, the privacy of people who may opt to remove their information from the list has to take priority.

License

FediRoster (c) Julian Fietkau

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See LICENSE for details.

The pixel art assets making up the FediRoster icon have been created by Nina and are committed to the public domain under Creative Commons Zero. The FediRoster website contains an icon creator that you can use to generate icon asset files for your own FediRoster installation. Depending on availability, Nina is happy to be hired to create bespoke icons for you.