Pelago - This Software Will Self-Destruct

Disclaimer: This code is in heavy early development and in early alpha. Bugs might be common and there may be breaking changes.

'Pelago or 'Archipelago' if you like using its formal name, is software designed to build archipelagos. What are those? Well, in short, they are opt-in federated networks that involve mutual allowlisting between "islands" or instances configured to federate via allowlisting rather than blocklisting, which is the usual default when you think about software like Mastodon.

Pelago was created to solve the real issues created when you set up an allowlisted server. At the same time, there are numerous benefits of allowlisting, but the reason people don't attempt it are the very real problems it creates. It is hoped 'Pelago can provide a solution to many of these.

The current instance used by the Island One Network is hosted at https://archipelago.1sland.social.

You're welcome to use this version to build your own networks, however:

DISCLAIMER: This software is in early alpha and under active development. We aren't encouraging mass installations of the software yet (use at your own risk) until we get things more solidified and work out some of the kinks. In the meantime, you're welcome to trial the public URL above. We plan to allow data exports/exfiltration of data you've entered, so you won't be locked in.

Getting Started - Docker

The easiest way to run Pelago is with Docker.

1. Clone this repo to a directory somewhere. cd to this directory and create an env file: cp .env.example .env.
2. Run docker compose up -d
3. That's it. You'll be running on localhost at port 3303. You can change the port in the docker-compose.yml, and then docker compose restart.

When you're done, type docker compose stop to stop the container.

Getting Started - CommandBox

1. Clone this repo to a directory somewhere and cd into the directory.
2. Download and Install CommandBox. (On MacOs, I recommend doing it via Homebrew.)
3. Run commandbox in the terminal with box. While you're in there, run update --system to grab the latest and greatest.
4. Inside of the CommandBox prompt:

cd /yourdirectory/pelago
install
task run initialize
start

5. That's it. You'll be running on localhost at port 3303. You can change the port in the server.json, and then restart in CommandBox.

When you're done in the commandbox prompt, type stop to stop the server and then type quit or exit to exit the box terminal.

The .env file, HothConfig, and error logs

Whatever method you choose, the .env file will be updated, one time, with a autogenerated secret key. Keep this SECRET_KEY value safe. Data encrypted in your database will need this key in order to decrypt it.

If for some reason the script does not properly create the HothConfig.cfc config file, you may need to go to the model/configs directory and cp HothConfig.cfc.example HothConfig.cfc before you'll be able to start the application.

You can hand-edit the HothConfig.cfc as you choose if you want it to email you errors and stack traces. It also has the exception log configuration directory, which by default is in a directory called ./logs that will be generated off of this webroot. The /logs path itself is inaccessible (blocked) from the web.

Note that SMTP configuration is optional, is not required to run 'Pelago, and is only used to email exceptions to yourself (at least at this time).

(Note that tools to review these exception logs and clear them out will be available in the /admin area for those with Super Admin privileges, so emailing exceptions to yourself is not required to discover recent issues.)

Pelago - Configuring the Application

(WIP) The short answer for now is that the .env file needs to have a ADMIN_NOTIFICATION_ACCOUNT assigned to a fediverse handle, and you need to log in with that account with Pelago which will automatically have superadmin privileges. This account does not require admin privileges on the instance, just the assignment of the account in the .env file will be enough to grant those privileges. Admin details can be reviewed by clicking on the profile in the upper right and clicking 'Admin' in the menu that appears. This will also allow you to give other users super admin privileges or suspend users from the instance.

Blocklists

Note that any enabled blocklists cannot login to 'Pelago. Only 'Fedinuke' is enabled by default.

Problems

(WIP) What follows are a few problems with allowlist networks, and how 'Pelago attempts to solve them.

Problem One: Discovery

How does a new island find or discover new instances to allowlist with?

In 'Pelago, you do this by finding networks and subscribing to their allowlists. Some networks are archipelagos: you can only join them if they allow you to join, because if you're both allowlist-based federation (islands) then all federation between you must be bi-directional. 'Pelago handles both invitation to a network as well as wanting to join it and subscribing to the network, being added to the allowlist feed, and eventual confirmation as a full member of the network.

Problem Two: Confirming Federation

In a typical allowlist or island network scenario, if you have ten different instances all federating with each other, how do you know they are federating? When a new instance joins the cluster, how do you confirm they've allowlisted everyone else in the cluster?

'Pelago handles that, too. It's a real pain in the real world, doing it the manual way, with a DM thread or something nagging all the admins to confirm federation over and over again, every time someone joins the network, and people do go on vacation, after all.

So instead, you log into 'Pelago and it snapshots an access_token with permissions to read your allowlist, and not much else. And it does this for everyone else in the network, and it really doesn't care, store, or database your allowlist, but what it will do is cross-check and make sure everyone has allowlisted everyone else.

It just won't work otherwise.

Why use GoToSocial?

It's just configured, out of the box, for this purpose. Really the only thing you need to change is the instance federation from "blocklist" (the default) to "allowlist" and it's already configured, ready to go, you have an island.

You can of course replicate this design with other software, but it's particularly hard to do with Mastodon because of its woeful privacy policy and relative lack of support for this use case.

While we can't rule out a hacked version of Mastodon might support the principles of island networks in the future, let's just say it was designed for a purpose and that purpose is not this purpose.