Bonfire has some excellent ideas when it comes to access control and extensibility, two things lacking in current fediverse platforms. Initially, I was interested to see how I could utilize this to supervise social media use of relatives with dementia.

WeDistribute wrote an article that dives into those features, so jump over there if you want a closer look.

My goal is to learn a bit more about how Bonfire works: the deployment process, the maintenance required, how plugins are managed, and the backend administration of the platform.

Additionally, I thought it would also be good exercise to document my installation process and share for others to reivew. That’s where we are today.

Expectations

Do not expect a fully usable, production ready instance at the end of this process. Installing this software should be considered experimental in nature. If you do decide to install it, be sure to provide feedback to the contributors.

Installation Guides

There’s a growing repository of docs for the install process. One thing to be aware of if you search “bonfire documentation” is that there are two distinct domains with the same documentation. I’ve verified in the official Matrix support channel that either version is fine, they are deployed from the same source.

• https://bonfirenetworks.org/docs/
• https://doc.bonfirenetworks.org/readme.html

I prefer the latter because it has search.

Here’s the GitHub Repo - I looked at the Issues list to see if something I was running up against was already reported.

Support

Bonfire runs a support channel on Matrix. I found it helpful and friendly. As always, remember that this is an open source project and treat it as such. This isn’t paid support, so be kind, patient, and considerate when requesting assistance

Contribute

If you’re interested enough in a project to attempt an install and end up needing some additional support through the chat rooms, consider contributing to the cause.

Let’s get started!

Initial Considerations

We all want to jump in, get it installed and GO! But as is the case with most platform installs, there are decisions best to make up front. I find it interesting as I try out different types of fediverse platforms, that many of these decisions are the same:

• Choose an install path
• Choose a domain / sub-domain
• Get an SSL certificate
• Choose an SMTP provider
• Choose an S3 storage bucket (optional)

Installation Path

Bonfire’s preferred method for installation is using CoOp Cloud, which I think is similar to using something like YunoHost. Here are the instructions for getting started as an “Operator” with the CoOp Cloud. After install of their server client, you can then install various recipes (including Bonfire) with a single click. I wasn’t familiar with this configuration, so I went with the Docker B1 easy install path.

Bonfire Flavor

Bonfire comes in various flavors (classic is available right now, more to come) For this install, I chose “classic” which is your normal social media feed.

Classic is also the recommended flavor by the Bonfire team at this stage of development.

Domain

Fediverse domains are extremely important. Once set, consider it committed for the long-term to your installation. Fediverse traffic will be delivered to it for ages to come. If you had a popular instance, then sell your domain, I feel sorry for the poor soul wondering what all these /inbox requests are coming at their server.

Switching to a different platform on the same domain, or even to a fresh install of the same platform can cause havoc as you’ll continue to receive requests related to the previous instance.

Note if you install through the CoOp Cloud, you will have two sites, one for the app you’re installing (bonfire) and one for the installer itself. The installer site doesn’t necessarily need a sub-domain, you can just use the IP address.

I’m going to try and attend a live stream of co-op being installed and used to setup several sites, so I’ll provide a bit more info here, and may even do another tutorial just for that process.

If you are going bare metal or docker, you can just use a sub-domain.

I chose this sub-domain.

• bonfire.box464.social

SSL Certificate

An SSL Certificate for root and wildcard, pointing to your server (or proxy…hopefully) So this is what I did.

• DNS - box464.social is now hitting my homelab, wildcard and root domain.
• DNS - bonfire.box464.social is hitting my homelab.
• Nginx Proxy Manager - bonfire.box464.social is directing to 192.168.1.233:4343
• Nginx Proxy Manager - Let’s Encrypt Wildcard SSL cert utilized

Home Lab - Static IP

Just to ensure we don’t have any conflicts later, I like to set this new ProxMox VM ip address as static in the LAN.

I’m using PiHole for DHCP , so I jumped over there to make this change. This is setup in PiHole > Settings > DHCP

Proxy

My homelab sends all traffic through an NGINX Proxy Manager, then on to local IPs. Bonfire by default includes a Caddy Proxy.

However, it’s simple to exclude. When you run Bonfire, you set it to only run the db and not spin up caddy.

just rel-run db or just rel-run-bg db to run in the background once you get the basics configured.

I setup my proxy to pass requests to bonfire.box464.social over to the IP and port 4343.

Email

I decided to use SendGrid for email as I am familiar with the prodcut. Setup steps are below. Just making a note of it here.

Storage

You can just store media on the local device, and if you’re just testing this, I might recommend that instead of setting up another complication here.

I have wanted to try out Cloudflare R2 as a storage backend, so going with that.

Using ProxMox VM

I have a nice ProxMox system in my homelab. It’s plenty powerful and I can run lots of experimental things on here without issue.

I’m only using this for a single or low usage instance (5 users at most) for testing and exploration.

The configuration I ran with is a little beefy for a 1 user instance. Why not.

• I bumped the stats to a bit more than a high end RasPi 4
• 3 cores, 2 sockets = 6 cores
• 16 GB RAM (8.192)
• 255 GB Storage (necessary, not sure)
• Plan to use Cloudflare CDN for media storage

TIP: After the initial Ubuntu VM creation, create a snapshot so you can start from HERE instead of going through the entire install process again if you screw up!

During install these choices were made:

• Install OpenSSH Server Snap
• Use my personal key for authentication

Installing the Guest Agent

This doesn’t happen by default, but is a recommended step when setting up a new VM on ProxMox.

What does this get you? Cleaner snapshots when you backup your system, among others. Always a good thing.

Also, in the ProxMox UI, under the VM’s Options tab, you will now see the VM’s IP address, which had alluded me previously.

Fairly simple to do on my Ubuntu system:

1
2
3

sudo apt-get install qemu-guest-agent
sudo systemctl start qemu-guest-agent
sudo systemctl enable qemu-guest-agent

If you run all three commands, a reboot isn’t necessary to get the agent up and running.

I recommend installing the agent, but if you don’t want to, there are a few other ways to find the IP:

• Go to your DHCP lease provider and find the VM’s MAC address - the related IP will be visible from there.
• If you’re logged on to the VM, use hostname -I to get the IP address

A big thanks to Івась Тарасик for pointing me to the right direction here with the missing qemu agent install.

Connecting to the server

Since I set the terminal to only allow connections wtih SSH keys, I setup my terminal with that information and login (I use Termius and it makes it pretty easy!)

Install Dependencies

Now it’s time to install dependencies.

Just

just is a way to organize scripts for project specific commands and make shortcuts, basically.

1

sudo snap install --edge --classic just

Docker

I had originally added docker as a snap but that was a mistake, I think. I reinstalled, then I had to add myself to the docker group so I don’t have to sudo everything.

Installing Docker on Ubuntu

Post install steps for linux

Following the post install steps, at least add your user to the docker group.

Backups and Snapshots

If you’re running on a ProxMox VM, this is a great time to take a snapshot and even setup a full backup in case the install goes south!

I did both.

Clone Bonfire

1

git clone --depth 1 https://github.com/bonfire-networks/bonfire-app.git bonfire && cd bonfire

Set Flavor

You should be in the bonfire directory. Run this.

1

export MIX_ENV=prod FLAVOUR=classic

Store Flavor in Startup

1

vim ~/.bashrc

Add the following lines at the bottom:

1
2

# Bonfire Flavor Config
export MIX_ENV=prod FLAVOUR=classic

Configuration

There are several parts to configuration. The first is to just get a baseline environment config setup. Be sure you’ve setup the appropriate flavor and environment (prod or dev) from the steps above before you continue.

Run Just

This creates some default configuration files. It uses the FLAVOUR and MIX_ENV configurations we set above to produce the files.

1

just config

After running this, I see a suggestion in the console (not the docs) to run the following command.

Now make sure to finish the flavour setup with just setup. You can also edit your config for flavour ‘classic’ in /.env and ./config/ more generally.

When I asked in Matrix, it was determined I should skip over this as the command is only for local builds, not using docker.

Environment File Configuration

We’re setting up the /configuration/prod/.env file that is also linked from ./.env, so from the base Bonfire project directory, open this file.

1

vim ./.env

These setting are throughout the ./.env file, so just find them and update them. Remember, I’m using my own Proxy Manager (NPM) so traffic will be forwarded to 4000. Public port will be 443.

IMPORTANT: You need to include the “APP_DOCKER_IMAGE” variable with the latest image flag here. This does not exist in the .env file by default. Setup will not work without this addition!

1
2
3
4
5
6
7

# custom docker image
APP_DOCKER_IMAGE=bonfirenetworks/bonfire:latest-classic-amd64
FLAVOUR=classic
HOSTNAME=bonfire.box464.social
SERVER_PORT=4000
PUBLIC_PORT=443
MAIL_BACKEND=sendgrid

Creating Secrets

In the env file there’s some secrets that need to be generated. There’s a handy tool you can use to generate a few. Make sure to store these securely somewhere outside of the env file as well!

1

just secrets

I stored the actual secrets in my password manager.

1
2
3
4
5

SECRET_KEY_BASE=<your-secret-01>
SIGNING_SALT=<your-secret-02>
ENCRYPTION_SALT=<your-secret-03>
POSTGRES_PASSWORD=<your-secret-04>
MEILI_MASTER_KEY=<your-secret-05>

Mail Delivery

The default mail vendor is Mailgun. Going against the grain here and using SendGrid, because I’m more familiar with it. With a bit of digging, it worked fine.

• Using SendGrid
• Setup Domain Authentication in SendGrid with the box464.social domain name
• Added and verified DSN entries in Cloudflare
• Create new API Key in SendGrid for Box464.social - you just need mail send access, that’s it!
• In Cloudflare, setup DMARC Management

Bonfire uses an extension called bonfire_mailer that is a shell for running bamboo

Bamboo has quite a few setups for various providers, it’s likely you will find your own. Initially I had setup to use SMTP with SendGrid but I switched to using the API since it’s simpler to configure.

Note that you also need to find MAIL_BACKEND, which is near the top of the config file, and update it to “sendgrid”

1
2
3
4

# email delivery if you use mailgun.com, edit with your domain and API key
MAIL_KEY=<your-api-key>
MAIL_DOMAIN=<your-root-domain>
MAIL_FROM=noreply@<your-root-domain>

I tested the API config in Postman successfully.

Be sure to store your SendGrid API Key somewhere safe.

Media Bucket Using Cloudflare R2 Storage

I’ll say it again, if you’re just kicking the tires, you might just want to skip this and just store images locally. It’s not a long term soultion, tho, as the fediverse tends to fill up storage buckets quickly with media.

It looks like there is some extra setup necessary for this because I’m not using their default bucket provider, Scaleway

Cloudflare R2 storage is S3 compatible and should work fine.

The region is: us-east-1 always, which is just made up for S3 API compatibility.

The necessary environment variables weren’t in the .env file by default, and I wasn’t sure where to look.

I reached out to Bonfire devs for pointers to the exact parameters I need to set and got the following response.

The upload settings are defined in https://github.com/bonfire-networks/bonfire_files/blob/main/lib%2Fruntime_config.ex#L26

This is a compiled file, so you’re not going to find it on the server directly. You’re just looking at that file and pulling out the environment variables needed:

1
2
3
4
5
6
7

UPLOADS_S3_BUCKET=<bucket_name>
UPLOADS_S3_ACCESS_KEY_ID=<access_key_id>
UPLOADS_S3_SECRET_ACCESS_KEY=<secret_access_key>
UPLOADS_S3_REGION=us-east-1
UPLOADS_S3_HOST=<cf-account-id>.r2.cloudflarestorage.com
UPLOADS_S3_SCHEME=https://
UPLOADS_S3_PORT=443

One this missing as a variable is an UPLOADS_S3_HOST_ALIAS which is useful with Cloudflare in particular as it serves cached and proxied files only if you use an alias. This option exists in other configurations like Mastodon, so I hope to see it make it into Bonfire as well.

[!WARNING] While Cloudflare R2 worked, and I am able to upload images and have them stored in the bucket, some other platforms are having some difficulty with it - Pixelfed and Friendica and Catodon.

I’m beginning to think this is a ME problem (my Cloudflare R2 setup) and not Bonfire….I bet it has something to do with requiring signed URLs maybe?

Verify your tooling

At this point we’re almost ready to spin up the docker images. One last verification is to check the 3 items you’ll need installed for this process.

1
2
3

docker version
docker compose version
just --version

If any of those don’t return a response or error out, you’ve missed something. Re-install / fix docker permissions for your user.

Take a snapshot

At this point, all the config values are set! It’s time to take a snapshot again before I run the next steps and mux something up.

Installation

You stuck through it and made it here! Let’s do this.

Following the documentation, after triple checking my work, I ran the following. Remember! I have my own NGINX Proxy Manager, so by adding the “db” parameter, I am EXCLUDING the packaged caddy spinup.

If you don’t have a proxy and want to use caddy, just exclude the “db” parameter.

1

just rel-run db

With that, you should see a streaming list whizz by of all the activities going on as your instance spins up!

Finally, you need to run the migration plan for the database. This streaming console of activity means you’re already in Elixir, and that’s where you need to run this command. Just start typing, and a prompt will appear at the bottom of your terminal while the stream continues. Hit enter, and ensure it runs successfully.

1

Bonfire.Common.Repo.migrate

If you visit your domain now, you should see Bonfire up and running!

At this point, you’re streaming the activity log in your terminal, so you probably want to run it in the background now that’s it’s all setup.

I stopped the system and then asked it to run in the background with this command:

1

just rel-run-bg db

Backups

I took another snapshot and then setup daily, weekly and monthly backups - locally for now.

Setting up accounts

The first account you create is going to be the admin account, although it isn’t clear that’s what is happening when you sign up. I would recommend creating an admin@yourdomain.com account, then you can create a normal user account for yourself.

Restricting Signups

I looked around at preferences and noticed that it was defaulted to open sign up. I immediately changed that to invite only after logging in.

Federation

Federation if turned off by default. You can turn it on, but be warned you will need to deal with some bugs.

A few things to be aware of in this build:

• Incoming federated posts do not include images
• Incoming federated posts do not generate link previews
• Composer: Hashtags aren’t linked when viewed on Mastodon
• Composer: Dialog sometimes doesn’t get pushed to the front of the UI
• Composer: Editing a post brings up the encoded content in the post dialog (shows markdown, encoded characters, etc.)
• Composer: If you remove the encoded content or try to add links, etc. to an edited post it doesn’t work well.
• Composer: Replying to an external user is doing something odd.
• Composer: Sometimes you can’t bring up the edit dialog on an existing post. Have not found a pattern.
• If I try to view a specific post in full detail (not just on timeline) I get a blank screen most of the time.

An external user noted that when I replied in a conversation thread, my reply-tos were not included in my message body and they thought it a bit confusing not to see. I’ve seen similar confusion when hashtags are not included in the body on another platform (postmarks) but we fixed that.

I think this is a ME problem, but I’m seeing this:

Outgoing posts with images display for a bit on other instances, but a day or two later aren’t accessible. This may be an issue with Cloudflare R2 and signed URLs.

Things to Do

There are more things I want to experiment with before I close down this experimental instance!

• Explore specific scenarios with Circles and Boundaries
• Invite a couple of small groups to test them out?
• Check out other extensions and try installing one, disabling one, etc.