---
name: bonfire
description: Recipe for self-hosting Bonfire — a modular, federated (ActivityPub/Fediverse) social networking framework built with Elixir/Phoenix. Supports multiple "flavours" (Social, Community, Ember, Open Science, Coordination, Cooperation) for different community needs.
---

# Bonfire

Modular, federated social networking framework built on Elixir/Phoenix and ActivityPub. Self-hosting gives communities full control over their digital space with federation to the broader Fediverse (Mastodon, Pleroma, etc.). Ships multiple "flavours" for different use-cases — from classical social networking to cooperative resource management. Upstream: <https://github.com/bonfire-networks/bonfire-app>. Hosting guide: <https://github.com/bonfire-networks/bonfire-app/blob/main/docs/DEPLOY.md>. License: AGPLv3.

Bonfire Social 1.0 is stable; other flavours (Community, Coordination, Cooperation) are alpha/beta.

## Compatible combos

| Infra | Runtime | Notes |
|---|---|---|
| Any VPS/bare metal | Docker Compose + `just` | Official method. Uses `docker-compose.release.yml`. |
| Co-op Cloud server | Abra CLI | Recommended for sysadmins hosting multiple federated apps. Uses the official Co-op Cloud recipe. |
| Any Linux host | Bare-metal (Elixir release) | Requires Elixir 1.16 or 1.17.3+, PostgreSQL 12+ with PostGIS extension, `just`. |
| Guix System | Guix service | Via `bonfire-guix` channel. |

## Flavours

Choose one before deploying:

| Flavour | Status | Use-case |
|---|---|---|
| `social` | **Stable (1.0)** | Classical social networking — posts, follows, reactions, groups |
| `ember` | Stable | Minimal base — just the basics |
| `community` | Beta | Groups and topics functionality |
| `open_science` | Alpha | Open science platform features |
| `coordination` | Pre-alpha | Work organisation, projects, tasks |
| `cooperation` | Pre-alpha | Cooperative production and resource exchange |

## Inputs to collect

| Phase | Prompt | Notes |
|---|---|---|
| flavour | "Which Bonfire flavour? (social / ember / community / ...)" | Determines Docker image and config set. Default: `social`. |
| domain | "What domain will Bonfire run on?" | Must have DNS pointing to server before deploy. |
| smtp | "Email provider and credentials?" | Required — Bonfire sends signup/notification emails. Supports any SMTP, Mailgun key preferred. |
| secrets | "Generate `SECRET_KEY_BASE`: `openssl rand -base64 64`" | Required Phoenix secret. |
| db | "PostgreSQL password?" | Auto-generated during `just config` or set manually. |

## Software-layer concerns

### Config paths
All config lives in `.env` at repo root (generated by `just config`). Edit with:
```bash
MIX_ENV=prod FLAVOUR=social WITH_DOCKER=yes just config
# then edit .env
```

### Key env vars

```
FLAVOUR=social          # or ember, community, etc.
MIX_ENV=prod
WITH_DOCKER=yes
APP_VERSION=latest      # or latest-rc, latest-beta, latest-alpha

# Domain
PUBLIC_URL=https://yourdomain.net

# Database (auto-configured in docker-compose)
DATABASE_URL=ecto://postgres:password@db/bonfire

# Secrets
SECRET_KEY_BASE=<64+ byte random string>

# Email (Mailgun example)
MAIL_BACKEND=mailgun
MAIL_DOMAIN=yourdomain.net
MAIL_KEY=<mailgun-sending-key>
MAIL_FROM=noreply@yourdomain.net
```

### Docker Compose (pre-built image method)

Upstream uses `docker-compose.release.yml` with `just` commands. Docker Hub images are at `bonfirenetworks/bonfire:<tag>-<flavour>` (e.g. `bonfirenetworks/bonfire:latest-social`).

```bash
# Initial setup
git clone --depth 1 https://github.com/bonfire-networks/bonfire-app.git bonfire && cd bonfire
export MIX_ENV=prod FLAVOUR=social WITH_DOCKER=yes

# Generate .env and configure
just config
# Edit .env: set domain, SMTP, adjust APP_VERSION if desired

# First-run setup (database migrations, etc.)
just setup-prod

# Start in background
just rel-run-bg
```

The compose stack includes:
- `app` — Bonfire application container
- `db` — PostgreSQL with PostGIS
- Caddy reverse proxy (configured in `config/deploy/Caddyfile2-https`)

### Ports
- 80/tcp — HTTP (Caddy, redirects to HTTPS)
- 443/tcp — HTTPS (Caddy + Let's Encrypt)
- 4000/tcp — Bonfire app (internal; fronted by Caddy)

### Admin account
The first person to sign up at `https://yourdomain.net/signup` is automatically granted instance admin. The instance is invite-only by default after that.

To create an account from CLI (iex console):
```bash
just cmd _build/prod/rel/bonfire/bin/bonfire remote
# In iex:
Bonfire.Me.make_account_only("my@email.net", "my pw")
```

## Upgrade procedure

```bash
# Pull latest image
docker compose -f docker-compose.release.yml pull app
# Re-deploy
just rel-run-bg
```

Or with Co-op Cloud:
```bash
abra app deploy YOUR_APP_DOMAIN_NAME --force
```

Check release notes at: <https://github.com/bonfire-networks/bonfire-app/releases>

## Gotchas

- **`just` required** — Almost all management commands go through `just`. Install it before setup: <https://github.com/casey/just#packages>
- **Elixir version constraints** — Versions 1.17.0–1.17.2 have a compilation freeze bug with the Pathex library. Use Elixir 1.16 or 1.17.3+. Set `WITH_PATHEX=0` in env to bypass if needed.
- **PostGIS required for bare-metal** — The PostgreSQL database must have the `postgis` and `citext` extensions. Pre-built Docker image handles this automatically; bare-metal installs need them manually: `CREATE EXTENSION IF NOT EXISTS postgis WITH SCHEMA public;`
- **Instance is invite-only after first signup** — The first account bypasses this restriction and becomes admin. Share invites from the admin settings to onboard users.
- **Flavour is set at deploy time** — Changing flavours after initial setup requires a fresh install; it determines which Docker image and extension set is used.
- **Co-op Cloud is the recommended production path** — For hosting multiple federated apps (Bonfire + Mastodon + Matrix, etc.), Co-op Cloud + Abra provides the best operational experience.
- **ActivityPub federation requires public HTTPS** — Your domain must be publicly reachable with valid TLS for federation with Mastodon/Pleroma/etc. to work.

## References
- Upstream repo: <https://github.com/bonfire-networks/bonfire-app>
- Hosting guide: <https://github.com/bonfire-networks/bonfire-app/blob/main/docs/DEPLOY.md>
- Co-op Cloud recipe: <https://recipes.coopcloud.tech/bonfire>
- Docker Hub images: <https://hub.docker.com/r/bonfirenetworks/bonfire/tags>
- Community chat (Matrix): <https://matrix.to/#/#bonfire-networks:matrix.org>
- Release notes: <https://github.com/bonfire-networks/bonfire-app/releases>
