Upgrading to Broadcast 3.0

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.

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.

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 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:

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:

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:

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.

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.

Use 4 GB of RAM if you run plugins. Without plugins, 2 GB is still the minimum. See 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.

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

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.