# Upgrading to Broadcast 3.0

> What changes when you upgrade a self-hosted Broadcast server from 2.x to 3.0. Plugins, a new interface, the removed Migration API, and what to check after the upgrade.

Source: https://sendbroadcast.net/docs/upgrading-to-3

Broadcast 3.0 adds plugins and a new interface. Your data, your forms and your API tokens stay as they are. Plugins are optional: a server with no plugins installed works as before.

## Quick summary

- **Your data stays.** Subscribers, broadcasts, sequences, templates and settings are kept.
- **Plugins are new and optional.** They need two more containers and, for most servers, 4 GB of RAM.
- **The interface is new.** The sidebar, the dashboard and the Host System page look different. Every page is still there.
- **One API is gone.** The Migration API (`/api/migration/v1`) is removed. Every other API works as before.

## Before you upgrade

**Make a backup first.** Go to **Application → Backups** and make a new backup. The upgrade changes the database, and a backup is the only way back. See [Backup & Recovery](https://sendbroadcast.net/docs/backup).

**Check your PostgreSQL version if you run your own database server.** Broadcast 3.0 needs PostgreSQL 15 or newer. The automatic installation runs PostgreSQL 17, so it needs nothing. On an older database server, Broadcast 3.0 does not start. See [The upgrade stops with a PostgreSQL message](#the-upgrade-stops-with-a-postgresql-message).

**Check what uses the Migration API.** If a script or an SDK reads `/api/migration/v1`, it stops working on 3.0. See [The Migration API is removed](#the-migration-api-is-removed).

The upgrade runs a check first. It warns about plugins that do not support the new version, and about plugins on a plugin API version that is about to end. A warning never stops the upgrade.

## Upgrade to 3.0

**An existing server.** Upgrade to 3.0.0:

```bash
cd /opt/broadcast
sudo ./broadcast.sh upgrade 3.0.0
```

The upgrade gets the new scripts first. They add the plugin containers.

**A server on the 3.0 beta.** A server on the `beta` branch gets 3.0.0 with `sudo ./broadcast.sh upgrade`. It stays on the beta channel and gets the next betas too. To leave the beta channel, switch the script back to the `main` branch, then upgrade:

```bash
cd /opt/broadcast
sudo git fetch origin +refs/heads/main:refs/remotes/origin/main
sudo git checkout -B main origin/main
sudo ./broadcast.sh upgrade 3.0.0
```

**A new server.** The install command installs 3.0:

```bash
curl -fsSL https://sendbroadcast.net/install.sh | sudo bash
```

## Plugins

Plugins add features to Broadcast, such as polls and referral programs. Each plugin runs in its own process with only the permissions you approve. See [Plugins](https://sendbroadcast.net/docs/plugins).

Plugins need two more containers:

- `plugins` runs the plugin code.
- `egress` is the only way from the plugins to the internet.

They also need a runtime secret, a file in `secrets/plugin_runtime_secret`. On an automatic installation, the upgrade makes the secret and starts both containers. On a manual installation, you make the secret yourself and turn the containers on with `COMPOSE_PROFILES=runtime`. See the Turn on plugins section of [Manual Installation](https://sendbroadcast.net/docs/manual-installation).

Use 4 GB of RAM if you run plugins. Without plugins, 2 GB is still the minimum. See [System requirements](https://sendbroadcast.net/docs/system-requirements).

## The new interface

- **Sidebar.** Each user can change the default menu in a side panel, by drag and drop.
- **Quick jump.** Press **Cmd+K** (or **Ctrl+K**), or click **Jump to**, to find a page or a record by name.
- **Dashboard.** Growth, the last send and the release notes are on the dashboard. The release notes open in a drawer.
- **Host System.** The page starts with one verdict for the server, then one row for each resource. You can retry a group of failed jobs from it.
- **Application URLs.** Pages under **Application** now start with `/app` and do not name a channel. Old bookmarks still work: they redirect to the new address.

## The Migration API is removed

The read-only export at `/api/migration/v1` is removed in 3.0. It was used to move a whole installation to another server. To move a server now, use a backup. See [Backup & Recovery](https://sendbroadcast.net/docs/backup).

The SDKs from these versions on no longer have `client.migration`:

| SDK | Package | Without `client.migration` | Last version with it |
|---|---|---|---|
| broadcast-ruby | `broadcast-ruby` (RubyGems) | 0.11.0 | 0.10.x |
| broadcast-node | `@send-broadcast/sdk` (npm) | 0.8.0 | 0.7.x |
| broadcast-python | `broadcast-python` (PyPI) | 0.8.0 | 0.7.x |
| broadcast-php | `broadcast/broadcast-php` (Packagist) | 0.9.0 | 0.8.x |

To keep the Migration API on a 2.x server, stay on the last version with it.

## The database

3.0 adds database tables for plugins. The changes run when the app starts after the upgrade, as in every upgrade.

## What to check after the upgrade

1. Open the dashboard and the sidebar. Every menu item opens.
2. Open **Application → Host System**. The verdict is good, or each row says what to fix.
3. Send a test broadcast to yourself. Opens and clicks show in its stats.
4. Submit a test entry in an opt-in form on your website.
5. Run one request with each API token that you use.
6. If you turned on plugins, open **Application → Plugins**. It says **The plugin runtime is running**.

## Troubleshooting

### Application → Plugins says the runtime is not running

- Check that `secrets/plugin_runtime_secret` exists and is owned by uid 1000. The containers wait for it.
- On a manual installation, check that `COMPOSE_PROFILES=runtime` is in the `.env` file next to `docker-compose.manual.yml`.
- Run `docker logs plugins`. A running runtime shows `plugin runtime on :8787`.

### The upgrade stops with a PostgreSQL message

The log shows:

```
Broadcast 3 needs PostgreSQL 15 or newer. This database runs PostgreSQL 14. Upgrade PostgreSQL, then start Broadcast again.
```

Your database server runs PostgreSQL 14 or older, so Broadcast 3.0 does not start. The plugin tables are not made. Upgrade the database server to PostgreSQL 15 or newer, then start Broadcast again. A new installation stops with the same message before it makes any tables.

### A script that read the Migration API gets 404

The Migration API is removed in 3.0. Use a backup to move a server.