# Bonfire Install Party #1 - collaborative notes

## Agenda / Notes
- Event @mobilizon: https://mobilizon.libretic.fr/events/c0c0b536-5216-412b-a277-1dadead06997

### Introductions
- [@[e-mail]](https://bonfire.cafe/@ivan)
- [@[e-mail]](https://bonfire.cafe/@mayel)
- [@[e-mail]](https://mastodon.social/@box464): https://spark.box464.social
- [@[e-mail]](https://social.coop/@flancian): https://flancia.org, https://anagora.org/@flancian, https://social.coop/@flancian -- will be installing bonfire.social.coop
- [@[e-mail]](https://campground.bonfire.cafe/pub/actors/Juan_PabloGarcia)*
- [@[e-mail]](https://bonfire.fishinthecalculator.me/@fishinthecalculator)
- Jamie, [Runrig](https://runrig.org), [@[e-mail]](https://social.coop/@jgaehring), [[e-mail]](mailto:[e-mail])
- @[e-mail]
- Anuj, [@[e-mail]](https://mastodon.social/@quillmatiq): https://quillmatiq.com

### Collaborative agenda
- Room temperature
- what do folks want to accomplish?
- levels of technical skills
- what is already set up (e.g. domain and server)
- Intro to co-op cloud and abra
- Uses docker through a command line tool for management (abra)
- Supports recipes
- Recipe (FYI): https://git.coopcloud.tech/coop-cloud/bonfire.git
- Limitation is that hosting both coop cloud and non-coop-cloud web apps on the same server is more difficult
- Set up walk-through
- `abra app new`, choose bonfire
- `abra app config bonfire.example.org`, magic happens here (see step 6 below)
- `abra app secret generate bonfire.example.org --all`
- `abra app deploy -C bonfire.example.org` ?
-
- *please add any other agenda points!*
-
- Post install basic configuration advice!
-
- After-party on the fedi!

-----------

## Draft Setup Guide (please feel free to add notes/comments/improvements!)

### Overview

This guideline goes through the six steps to set up a bonfire instance for your community 🔥 ✨

The general steps are
1. 🖥 Get a Server (such as hetzner.com)
2. Set up domain-name, mail and DNS
1. 👉 Domain name (through namecheap for example) or subdomain on an existing domain
2. 📧 Set up mail (such as Mailgun)
3. 🌐 DNS set up (such as FreeDNS or via the domain name provider)
3. 🌥 Install Coop-Cloud on your server
4. 🪄Install Abra on your computer
1. 🐰 Add your server to Abra
5. 🚦 Install Traefik
6. 🔥 Install Bonfire on your server

### Walkthrough

#### 1. Get a server

Bonfire can be setup on any server (dedicated/virtual/VPS/docker/homelab). Hetzner is a common choice to set up a [dedicated](https://www.hetzner.com/sb) or [virtual server](https://www.hetzner.com/cloud/) in EU.

- Hardware requirement: 8GB+ RAM
- If you don't already have an ssh key, create one on your computer in terminal. The command varies but is usually `ssh keygen`
- If you are new to ssh:
- Activate firewalls *after* completing set up to minimize the potential issues for trouble shooting

> [!Tip] Protip
> Save your SSH private and public keys (and password if you set one) in a password manager to minimize the chance of getting locked-out of your server!

> [!note] Note
> It is also possible to store data (such as uploaded images) in a cloud service rather than directly on your server (through any provider that supports the S3 API), but this isn't necessary to do up front.

#### 2. Set up a domain, Mail and DNS

##### 2.1 Domain name
The domain name can be a new domain like *yourdomain.net* that you purchase or a sub-domain of an existing site you already have such as *sub.yourdomain.net*. All users on your instance will have the domain you select as part of their username, such as `@[e-mail]`

In this step we can use a domain name service such as namecheap, which was used in this tutorial.

> [!tip] Protip
> It takes around 24h to propagate among the DNS servers so give yourself plenty of time to account for potential DNS set-up errors.

##### 2.2 Set up mail - SPF, DMARK, etc

Mailgun is one of manny services offering a free email routing service for up to 1 account. See [this page for alternatives and how to configure them](https://docs.bonfirenetworks.org/Bonfire.Mailer.html).

> [!Tip] Protip
> Your domain used for the bonfire instance (e.g. yourdomain.net or social.yourdomain.net) must be different from one for the email domain (e.g. email.yourdomain.net)

Follow [this guideline](https://documentation.mailgun.com/docs/mailgun/quickstart-guide/quickstart/) for info on how to set up your Mailgun account.

> [!tip] Protip
> On Mailgun the EU / US interfaces are separate, make sure you stick to the same interface (little flag at the top)

##### 2.3 Add the details to DNS

On the DNS service (usually using the domain name provider's dashboard) we will need to set up our details for the server and the email service.

The following outline is a general list of required details. the values are placeholders to show what it might look like. Brackets, such as `[insert]`, indicate that you add your own characters.

First you need DNS pointing the domain to the server:
- **IPv4** as an A record
- host: `@` to use `yourdomain.net` or e.g. `social` if you wanted to use `social.yourdomain.net`
- value: `[XXX.XXX.XXX.XXX]` (IP address of your server)
- **Wildcard** DNS as an A record
- host: `*` to use `yourdomain.net` or e.g. `*.social` if you wanted to use `social.yourdomain.net`
- value: `[XXX.XXX.XXX.XXX]` (IP address of your server)

It may looking something like this:

For email, use the info provided by the email service you set up (make sure you set up **all** of the different things provided, such as CNAME, DMARK, DKIM, and SPF, otherwise emails may not be delivered or end up in spam), here is an example of what it may look like when using mailgun.

- **CNAME** record
- host: `email.[sub]`
- value: `eu.mailgun.org.`
- **DMARC TXT** Record
- host: `dmarc.[sub]`
- value: `v=DMARC1; p=none; pct=100; fo=1; ri=3600; rua=mailto :fcf2` etc...
- **SPF TXT** Record
- host: `[sub]`
- value: `v=spf1 include:mailgun.org ~all`

###### Optionally
- add IPv6 as AAAA Record (*notice, different DNS require different formats for IPv6)* - add wildcard DNS as an AAAA record with * as the hostname and the server IPv6
- MX set up if you want to be able to receive emails as well

> [!Tip] Protip
> IPv6 sometimes messes things up. Optionally you can skip IPv6 to start with and add later once IPv4 is securely running.

#### 3. Install Coop-Cloud on server

Follow this [guide to install Coop Cloud](https://docs.coopcloud.tech/operators/tutorial/)

If you have any issues connecting with SSH, here's a [guide for coop-cloud ssh issues](https://docs.coopcloud.tech/abra/trouble/#ssh-connection-issues):

> [!Tip] Protip
> Ensure .ssh/config file is set up
> ```
> Host [yourdomain.net]
> HostName [yourdomain.net]
> User [root]
> IdentityFile ~/.ssh/[your_ssh_key]

#### 4. Install Abra

[Abra](https://docs.coopcloud.tech/abra/) is installed locally on your machine and acts as the remote control to Coop-Cloud, letting you manage software installations more easily from your local machine.

[Follow the Abra installation guide](https://docs.coopcloud.tech/abra/install/).

##### 4.1. Add your server to Abra

Here's a guide for how to [add your server](https://docs.coopcloud.tech/operators/tutorial/#install-abra) to Abra. This tutorial works well until you need to install the app. When you reach the "Nextcloud" part of the guide, switch back to this guide.

- The command for adding the server is `abra server add [yourdomain.net]` or e.g. `abra server add [social.yourdomain.net]` if using a subdomain
- To see that it works, check `abra server ls` and you'll get a cute happy message

> [!Tip] Protip
> Try pinging *traefik.yourdomain.net* to see that it works:
> `ping traefik.yourdomain.net`

#### 5. Install Traefik

[Traefik](https://doc.traefik.io/traefik/) is a proxy that supports developers with publishing services. This will make it easy to ensure that your bonfire instance is up to date!

Install by following this [recipie to install Traefik](https://recipes.coopcloud.tech/traefik).

Remember to add a valid email when configuring Traefik to generate a SSL certificate (abra app config traefik.yourdomain) - that's the only field you need to configure for traefik to work

> [!Tip] Protip
> You can try using --chaos to tell abra to use the recipe that you have set up locally rather than pulling it from the repository if the traefik setup is stucked

#### 6. Install Bonfire on Server

Follow the guidelines for the [Bonfire Recipe](https://recipes.coopcloud.tech/bonfire) through Abra (your remote control for Coop-Cloud)

- editing the config file
- `abra app config [yourdomain.net]`
- change the the email sending key

	MAIL_BACKEND=mailgun
	MAIL_DOMAIN=[yourdomain.net]
	MAIL_KEY=[your-mailgun-sending-key]
	MAIL_FROM=[[e-mail]]

- deploy
`abra app deploy [yourdomain.net]`

- if redeploying, you can force deploy
`abra app deploy [yourdomain.net] --force`

> [!Tip] Protip
> You can turn the `~/abra/servers/yourdomain.net` directory into a git repo and share it (privately!) with collaborators. It's also useful as a backup if you loose access to your machine or want to manager the server from a different place.

### 🎉 Tada 🎉

That's it! Now you should be able to share invite links to your instance.

> [!note] Notice
> The first person to sign up doesn't need to verify their email address and automatically becomes an admin. Email needs to be correctly configured and working for others to be able to sign up.

## FAQs

* connext to the bonfire app via command line:
abra app run [yourinstance.net] app bin/bonfire remote

* to migrate the DB manually: EctoSparkles.AutoMigrator.startup_migrations()

* how to sign up with command line:
* abra app run [yourinstance.net] app bin/bonfire remote
* Bonfire.Me.make_account_only("[e-mail]", "my pw")

* how to see logs:
* for bonfire logs: abra app logs [yourinstance.net] app
* to include logs of the DB and web proxy: abra app logs [yourinstance.net]
* Anyone tried to monitor bonfire with Graphana

* how to do backups?
* see this coopcloud recipe: https://recipes.coopcloud.tech/backup-bot-two

## Blocker / Issues

* Suggestion: I'd like to see documentation for various S3 vendor configs similar to the great docs you have for setting up SMTP. Thanks! (@box464)