Installation Guide

After following this guide, you will have a fully functioning copy of Broadcast installed and running on your server.

Quick answer

Broadcast installs on a fresh Ubuntu 24.04 or 26.04 server in about 30 minutes. There are three routes: the one-command automatic installer, which is the recommended path and also configures the software, provisions an SSL certificate, hardens the server, and enables automatic OS updates; a Docker image, if you want to run it inside your own container setup; and a manual install, for full control over each component. You need a fresh server and a primary domain name pointed at it. Additional domains can be added per broadcast channel afterwards, so one installation can serve several properties.

Our installer will automatically handle the following:

Installing the software
Configuring the software
Provisioning the SSL certificate
Securing the server
Handling automatic operating system updates

Prerequisites

To install Broadcast, you will need to have a fresh server installed with Ubuntu 24.04 or Ubuntu 26.04 (server edition).

You will also need to have a primary domain name which will be used to host the software. After installation, you can add additional domains per broadcast channel so that you can manage multiple properties from a single installation.

The minimum system requirements are:

2 GB of RAM
1 CPU Core
40 GB of disk space

However, we recommend the following system requirements if possible:

4 GB of RAM
2 CPU Cores
60+ GB of disk space

For hosting providers, we recommend:

Hetzner (Get €⁠20 credit with this signup link at Hetzner)
Digital Ocean (Get $200 credit with this signup link at Digital Ocean)
Linode (Get $100 credit with this signup link at Linode)

For the rest of the installation guide, we will assume you are using one of the above recommended providers.

If you are using a different provider, the installation will be similar if not the same. However, if you have any questions, please reach out to us from within the dashboard.

Installation

Installation is a straightforward process. It should take about 10 minutes to complete.

This video shows the automatic installation from start to finish:

There are two parts to the installation:

Server setup
Domain name set up

Step 1: Create the server

In your VPS provider’s dashboard, create a new server.

NOTE: At the present moment, DO NOT USE an INTEL-based server (ie. a server with an Intel CPU). At the present moment, we have observed a problem where the Docker images used for the application does not run properly even though it is cross compiled to do so. A fix will be going out on October 21, 2024 and will be generally available October 22, 2024.

Choose Ubuntu 24.04 or Ubuntu 26.04 (server edition) as the operating system.

Make sure you can login as root or ubuntu user. At most providers, you will need to specify a local public SSH key during the creation of your VPS.

If you do not have a local public SSH key, click here for instructions on generating one.

If you are new to SSH keys, keep your keys in a safe place. Without your keys, you will no longer be able to access your server if anything goes wrong.

To login to your system, type the following in your local terminal:

ssh root@your-server-ip

Replace your-server-ip with the IP address of your server.

On some Ubuntu systems, you will need to login as ubuntu user instead of root. Please see the next step for instructions on how to remove the ubuntu user and switch to the root user.

Step 1b: Removing the `ubuntu` user

You can skip this section if you are using a server that does not have the ubuntu user.

If the default installation creates a ubuntu user in preference of the root user, we will need to remove the ubuntu user and switch to the root user.

The ubuntu user is not required, and its uid/gid number conflicts with that of the user permissions of the running application.

To remove the ubuntu user, you first need to login as the ubuntu user:

ssh ubuntu@your-server-ip

Once logged in, you need to type the following command to allow your root user to be able to login:

sudo su
nano /root/.ssh/authorized_keys

Within this file, you will see the following line:

no-port-forwarding,no-agent-forwarding,no-X11-forwarding,command="echo 'Please login as the user \"ubuntu\" rather than the user \"root\".';echo;sleep 10" ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCs+Q5+...

Remove everything before the ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCs+Q5+... so you can log back in as the root user.

Save the file and exit.

Keep your terminal open just in case you made an error in saving the file and lock yourself out of your server.

In a different terminal, try logging in as the root user:

ssh root@your-server-ip

If it works, you can proceed to the next step and close your previous terminal.

Step 2: Install the software

After you are logged into your server, run the installer:

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

The installer is a script in our broadcast-script repository. Read it before you run it if you like.

The installer never changes an existing installation. If Broadcast is already installed on the server, it stops and changes nothing. To update an existing server, use ./broadcast.sh upgrade from /opt/broadcast instead.

Step 3: Answer the installer’s questions

The installer asks for two things:

Your primary domain name
Your license key

The license key can be found in your account dashboard and it is in the format XXXXX-XXXXX-XXXXX-XXXXX-XXXXX: five groups of five characters. It contains lower case letters and numbers, and dashes. Older keys in the shorter format XXXXX-XXXXX-XXXXX-XX still work.

The installer checks the key with our license server before it changes anything on the server. Then it asks you to confirm, and reminds you to point your domain to the server (step 4). Do that before you press Enter.

The installation takes about 5-10 minutes, depending on your server’s performance and internet connection speed. When it is done, the server restarts after one minute.

Install with an AI agent, or without prompts

Give the answers as environment variables and the installer asks nothing. This is how Claude Code or another agent can install Broadcast over SSH:

curl -fsSL https://sendbroadcast.net/install.sh | sudo BROADCAST_DOMAIN=broadcast.example.com BROADCAST_LICENSE=XXXXX-XXXXX-XXXXX-XXXXX-XXXXX bash

To skip the restart at the end, set BROADCAST_NO_REBOOT=1 as well. The installer writes a log to /var/log/broadcast-install.log.

Step 4: Configure your domain name

Before the installer continues, configure your domain name to point to the IP address of your server. Broadcast requests its TLS certificate for that name as soon as it starts.

You will need to add an A record to your domain name to point to the IP address of your server.

In general, we recommend that you use a subdomain as the primary domain name for your installation.

For example, let’s say you own the domain name example.com, you can use broadcast.example.com as the primary domain name for the installation. This way, you can leave the “root” domain name of example.com for your website.

Once you add the A record, it may take up to 24 hours for the DNS records to propagate through the internet. If you are using Cloudflare, it will only take a few minutes.

Step 5: Verify the installation

Once the installation is complete, you can access your dashboard at https://[your primary domain].

When you access your dashboard for the first time, you will be prompte to create an admin user account and your first “broadcast channel”.

You can think of a broadcast channel as a “list” you want to maintain. Within a channel, you can transmit broadcasts (email blasts), create automation sequences, manage subscribers, and send transactional emails.

You will need to configure an SMTP server to transmit emails from Broadcast. You will need at least one SMTP server. However, Broadcast supports (and recommends) using multiple SMTP servers to improve deliverability of the type of emails you are sending. Please refer to our documentation guide for more information about this feature.

Troubleshooting

Every installer error starts with Error:. Unless it says otherwise, the installer stopped before it changed anything, so you can fix the cause and run the same command again.

“the installer must run as root”

Error: the installer must run as root. Use: curl -fsSL https://sendbroadcast.net/install.sh | sudo bash

Fix: put sudo before bash, as in the command above. sudo curl ... | bash is not the same: it runs curl as root and the installer as your user.

“Broadcast needs Ubuntu Server 24.04 or 26.04”

Error: this server runs debian 12. Broadcast needs Ubuntu Server 24.04 or 26.04.

Fix: rebuild the server with Ubuntu 24.04 or 26.04 (server edition). The installer supports no other operating system or version.

“ports 80 and 443 must be free for Broadcast”

Error: ports 80 and 443 must be free for Broadcast, but something is listening:

The lines after it show the program on each port.

Cause: Broadcast serves HTTP and HTTPS itself. Another web server on the same ports would let the install finish, but Broadcast could never start.

Fix: stop that service, for example with sudo systemctl disable --now nginx apache2, then run the installer again. Broadcast needs a server of its own.

“only 3 GB of disk space is free”

Error: only 3 GB of disk space is free on /opt. Broadcast needs at least 5 GB free to install (40 GB disk recommended).

Fix: use a server with a larger disk. Below 20 GB free, the installer continues with a warning.

“there is no terminal to ask for the domain and license key”

Cause: the installer runs without a terminal, for example from a script or an agent, and you did not pass the answers.

Fix: pass both answers as environment variables, as in Install with an AI agent, or without prompts, or connect with ssh -t and run the installer again.

The license key is refused

The installer prints That does not look like a license key, The license server did not accept this key, or Invalid license key. Aborted. See License problems for each message, its cause and the fix.

“Broadcast is already installed on this server”

Error: Broadcast is already installed on this server (found /opt/broadcast/app/.env).

Cause: the installer never changes an existing installation. It found one of the files an installation creates.

Fix: use the command the installer prints for what you want to do. To upgrade, run sudo /opt/broadcast/broadcast.sh upgrade. To finish an install that stopped part way, run sudo /opt/broadcast/broadcast.sh install.

“/opt/broadcast already exists and is not a Broadcast checkout”

Fix: move the directory aside and run the installer again:

sudo mv /opt/broadcast /opt/broadcast.old

“the installer stopped”

Error: the installer stopped (exit 1). The full log is in /var/log/broadcast-install.log.

Cause: a step after the checks failed. The lines above the error show which one.

Fix: fix the cause, then finish the install with sudo /opt/broadcast/broadcast.sh install. If you need help, send /var/log/broadcast-install.log to support from your customer dashboard.