Manual Installation
Warning: Gotcha ahead!
Broadcast can also be installed manually on your server with the Docker image.
This method is more complex than the automatic installation method, and so this is not recommended for most users. However, there are specific reasons why you might want to manually install and run Docker.
First, let’s talk about what functionalities are not available with the manual installation method.
Features not available with manual installation
1. Auto updates
You will need to manually update the Docker image to get the latest features and security updates. The compose file uses pull_policy: missing, so Docker pulls an image only when it is not on the server yet. A restart does not update Broadcast. To update, pull the new image and recreate the containers:
cd /home/your-user/broadcast docker compose -f docker-compose.manual.yml pull docker compose -f docker-compose.manual.yml up -d
If you run Broadcast with the systemd service from step 5, run sudo systemctl restart broadcast after the pull instead of the up -d command.
2. Backups
Automatic backups are not supported as this feature requires creating system services. You will need to back up the database yourself, or write a script that does it for you. The postgres container mounts db/backups at /backups, so you can write pg_dump output there.
3. Reverse proxy / multi-domains / SSL termination
You can still use multiple domains on a single server with Broadcast, but you will need to manually set up your server’s reverse proxy to handle this for you.
For example, if you are using Nginx or Caddy, you will need to manually set up the reverse proxy to handle the multiple domains.
You will also need to manually set up your SSL certificates.
Have the proxy set X-Forwarded-For. Broadcast reads the visitor’s address from it. If a request also carries a Forwarded header that names a different client, Broadcast ignores the Forwarded header.
Steps to manually install and run Broadcast
1. Create a directory to run Broadcast
Clone the Broadcast script file to your server:
git clone https://github.com/send-broadcast/broadcast-script.git /home/your-user/broadcast
Replace your-user with the username of the user account on your server.
Be careful to not run the broadcast.sh script, as that is used for the automatic installation method.
2. Modify the docker-compose.manual.yml file
There is a docker-compose.manual.yml file in the cloned repository. Every host path in it starts with the placeholder /home/replace-with-your-user/broadcast. Replace the placeholder with the path of your clone. From inside the clone, this command does it:
cd /home/your-user/broadcast sed -i "s|/home/replace-with-your-user/broadcast|$(pwd)|g" docker-compose.manual.yml grep -c replace-with-your-user docker-compose.manual.yml
The grep command prints 0 when no placeholder is left.
This changes a file that git tracks. If a later git pull in the clone stops because docker-compose.manual.yml has local changes, undo the change, pull, and then run the sed command again (and redo any other change you made to the file):
git checkout -- docker-compose.manual.yml git pull sed -i "s|/home/replace-with-your-user/broadcast|$(pwd)|g" docker-compose.manual.yml
3.0+
The file looks like this before the change. The plugins and egress services stay off until you turn them on (see Turn on plugins):
# docker-compose.manual.yml services: app: image: ${DOCKER_IMAGE:-gitea.hostedapp.org/broadcast/broadcast:latest} platform: linux/${TARGETARCH:-amd64} pull_policy: missing container_name: app restart: always env_file: - /home/replace-with-your-user/broadcast/app/.env volumes: - /home/replace-with-your-user/broadcast/app/storage:/rails/storage - /home/replace-with-your-user/broadcast/app/uploads:/rails/uploads - /home/replace-with-your-user/broadcast/logs:/rails/logs - /home/replace-with-your-user/broadcast/secrets:/run/secrets:ro environment: BROADCAST_PLUGINS_SAFE_MODE: ${BROADCAST_PLUGINS_SAFE_MODE:-0} ports: - "127.0.0.1:3000:3000" # Overrides default ports networks: - broadcast-network - plugins-internal depends_on: postgres: condition: service_healthy logging: driver: "json-file" options: max-size: "10m" max-file: "3" command: bin/rails server # Overrides default command job: image: ${DOCKER_IMAGE:-gitea.hostedapp.org/broadcast/broadcast:latest} platform: linux/${TARGETARCH:-amd64} pull_policy: missing container_name: job restart: always env_file: - /home/replace-with-your-user/broadcast/app/.env volumes: - /home/replace-with-your-user/broadcast/app/storage:/rails/storage - /home/replace-with-your-user/broadcast/app/uploads:/rails/uploads - /home/replace-with-your-user/broadcast/secrets:/run/secrets:ro environment: BROADCAST_PLUGINS_SAFE_MODE: ${BROADCAST_PLUGINS_SAFE_MODE:-0} networks: - broadcast-network - plugins-internal depends_on: postgres: condition: service_healthy command: - "bin/jobs" logging: driver: "json-file" options: max-size: "10m" max-file: "3" plugins: profiles: ["runtime"] image: ${DOCKER_IMAGE:-gitea.hostedapp.org/broadcast/broadcast:latest} platform: linux/${TARGETARCH:-amd64} pull_policy: missing container_name: plugins restart: always command: ["bin/plugin-runtime"] environment: PLUGIN_HOST_API_URL: http://app:3100 PLUGIN_EGRESS_URL: http://egress:4750 DENO_DIR: /tmp/deno PLUGINS_MEMORY_LIMIT_MB: ${PLUGINS_MEMORY_LIMIT_MB:-256} BROADCAST_PLUGINS_SAFE_MODE: ${BROADCAST_PLUGINS_SAFE_MODE:-0} volumes: - /home/replace-with-your-user/broadcast/secrets:/run/secrets:ro read_only: true tmpfs: - /tmp user: "1000:1000" cap_drop: [ALL] security_opt: ["no-new-privileges:true"] mem_limit: ${PLUGINS_MEMORY_LIMIT_MB:-256}m cpus: ${PLUGINS_CPU_LIMIT:-0.5} pids_limit: 512 networks: - plugins-internal logging: driver: "json-file" options: max-size: "10m" max-file: "3" egress: profiles: ["runtime"] image: ${DOCKER_IMAGE:-gitea.hostedapp.org/broadcast/broadcast:latest} platform: linux/${TARGETARCH:-amd64} pull_policy: missing container_name: egress restart: always command: ["sh", "-c", "until [ -s /run/secrets/plugin_runtime_secret ]; do sleep 30; done; exec broadcast-egress"] environment: PLUGIN_RUNTIME_URL: http://plugins:8787 BROADCAST_PUBLIC_IPS: ${BROADCAST_PUBLIC_IPS:-} volumes: - /home/replace-with-your-user/broadcast/secrets:/run/secrets:ro read_only: true user: "1000:1000" cap_drop: [ALL] security_opt: ["no-new-privileges:true"] mem_limit: 64m networks: - plugins-internal - plugins-egress logging: driver: "json-file" options: max-size: "10m" max-file: "3" postgres: image: postgres:17-alpine container_name: postgres restart: always env_file: - /home/replace-with-your-user/broadcast/db/.env volumes: - /home/replace-with-your-user/broadcast/db/backups:/backups - /home/replace-with-your-user/broadcast/db/postgres-data:/var/lib/postgresql/data - /home/replace-with-your-user/broadcast/db/init-scripts:/docker-entrypoint-initdb.d ports: - "127.0.0.1:5432:5432" healthcheck: test: ["CMD-SHELL", "pg_isready -U broadcast"] interval: 10s timeout: 5s retries: 10 start_period: 30s networks: - broadcast-network logging: driver: "json-file" options: max-size: "10m" max-file: "3" networks: broadcast-network: driver: bridge plugins-internal: driver: bridge internal: true # no internet route: plugins leave only through egress plugins-egress: driver: bridge
The file looks like this before the change:
# docker-compose.manual.yml services: app: image: ${DOCKER_IMAGE:-gitea.hostedapp.org/broadcast/broadcast:latest} platform: linux/${TARGETARCH:-amd64} pull_policy: missing container_name: app restart: always env_file: - /home/replace-with-your-user/broadcast/app/.env volumes: - /home/replace-with-your-user/broadcast/app/storage:/rails/storage - /home/replace-with-your-user/broadcast/app/uploads:/rails/uploads - /home/replace-with-your-user/broadcast/logs:/rails/logs ports: - "127.0.0.1:3000:3000" # Overrides default ports networks: - broadcast-network depends_on: postgres: condition: service_healthy logging: driver: "json-file" options: max-size: "10m" max-file: "3" command: bin/rails server # Overrides default command job: image: ${DOCKER_IMAGE:-gitea.hostedapp.org/broadcast/broadcast:latest} platform: linux/${TARGETARCH:-amd64} pull_policy: missing container_name: job restart: always env_file: - /home/replace-with-your-user/broadcast/app/.env volumes: - /home/replace-with-your-user/broadcast/app/storage:/rails/storage - /home/replace-with-your-user/broadcast/app/uploads:/rails/uploads networks: - broadcast-network depends_on: postgres: condition: service_healthy command: - "bin/jobs" logging: driver: "json-file" options: max-size: "10m" max-file: "3" postgres: image: postgres:17-alpine container_name: postgres restart: always env_file: - /home/replace-with-your-user/broadcast/db/.env volumes: - /home/replace-with-your-user/broadcast/db/backups:/backups - /home/replace-with-your-user/broadcast/db/postgres-data:/var/lib/postgresql/data - /home/replace-with-your-user/broadcast/db/init-scripts:/docker-entrypoint-initdb.d ports: - "127.0.0.1:5432:5432" healthcheck: test: ["CMD-SHELL", "pg_isready -U broadcast"] interval: 10s timeout: 5s retries: 10 start_period: 30s networks: - broadcast-network logging: driver: "json-file" options: max-size: "10m" max-file: "3" networks: broadcast-network: driver: bridge
Broadcast relies on 3 containers to run:
- The app container
- The job container
- The postgres container
3.0+
Plugins add two more containers, plugins and egress. They are optional. See Turn on plugins.
Certain volumes need to be mounted from your host machine to the containers in order to persist data.
The app and job containers run as uid 1000 inside the image, and they write to the
directories that docker-compose.manual.yml mounts into them: app/storage, app/uploads, and
logs. On the host, those directories must be owned by uid 1000 or the containers cannot write
them. Uploads then fail with “could not be saved: the server cannot write to its uploads folder”.
The automatic installer handles this for you; with a manual install it is your job:
cd /home/your-user/broadcast mkdir -p app/storage app/uploads logs sudo chown -R 1000:1000 app/storage app/uploads logs
If you use Docker named volumes instead of host folders, you can skip this step. The image creates
/rails/storage and /rails/uploads owned by uid 1000, so a new named volume starts writable. An
existing empty named volume gets the right owner when you upgrade. A named volume that already holds
files still needs the chown.
Note that if a user on your host already has uid 1000 (often the default cloud user, such as
ubuntu), that user can now write to these directories. That user almost always has sudo anyway,
so in practice nothing changes, but it is worth knowing.
ARM servers
By default, the compose file pulls gitea.hostedapp.org/broadcast/broadcast:latest, the amd64
image, and runs it with platform: linux/amd64. Two variables change this:
DOCKER_IMAGEsets the image of theappandjobcontainers.TARGETARCHsets their platform,linux/${TARGETARCH}. It does not choose the image.
On an ARM server (uname -m prints aarch64 or arm64), set both, the same way the automatic
installer does. Put them in a .env file next to docker-compose.manual.yml. Docker Compose reads
that file each time you run docker compose -f docker-compose.manual.yml:
cd /home/your-user/broadcast cat > .env <<'EOF' DOCKER_IMAGE=gitea.hostedapp.org/broadcast/broadcast-arm:latest TARGETARCH=arm64 EOF
On an amd64 server, do not create this file.
3. Create the .env files
You will need to create the .env files for the app/job and db containers.
The app and job containers share the same .env file, which is located in the /home/your-user/broadcast/app directory. The postgres container reads /home/your-user/broadcast/db/.env.
Copy the sample files from /home/your-user/broadcast/manual to the app and db directories:
cd /home/your-user/broadcast cp manual/app/.env.sample app/.env cp manual/db/.env.sample db/.env
There is some duplicate in the both the app and db .env files, so be careful to copy the correct values.
You will need to generate a SECRET_KEY_BASE value for the app container.
To do this, run the following command in the /home/your-user/broadcast/app directory:
openssl rand -hex 64
The value that is generated can be used for the SECRET_KEY_BASE variable in the .env file.
Next, you will need to generate a POSTGRES_PASSWORD value.
To do this, run the following command:
openssl rand -hex 32
Copy this value into both the app and db .env files. Note that in the app .env file, the password variable is called DATABASE_PASSWORD, and that in the db .env file, the password variable is called POSTGRES_PASSWORD.
Next, set the TLS_DOMAIN and LICENSE_KEY values to the domain name of your server and the license key you got from the customer dashboard.
Last, generate the three Active Record encryption keys for the app .env file. Broadcast uses them to encrypt two-factor secrets, backup destination credentials, and AI and Autopilot API keys. Run this command three times, once for each key:
openssl rand -hex 16
Put each result in its own variable in the app .env file:
ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY=first-value ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY=second-value ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT=third-value
Set all three. If one is missing, Broadcast uses none of them, and every save of an encrypted value fails.
Warning
Never change these keys after the first start. Broadcast cannot read values that it encrypted with the old keys. Keep a copy of the app .env file with your backups.
Optional: RAILS_LOG_LEVEL sets how much Broadcast logs. The default is info. See Monitoring and Logs for the values.
4. Run the docker compose file
Before you can run the docker compose file, you will need to ensure that Docker is already installed on your server.
Run every docker command in this step as the user that will run Broadcast. That user must be able to run docker without sudo, so add it to the docker group, then log out and log in again:
sudo usermod -aG docker your-user
The Broadcast image is in a private Docker registry, so the first pull fails until you log in. You need a registry username and password for this. The automatic installer gets them from your license key, but a manual install cannot. Email simon@sendbroadcast.net to get access to the private Docker registry.
When you have the username and password, log in:
docker login gitea.hostedapp.org
Run docker login as the same user that runs docker compose, and that the systemd service in step 5 runs as. Docker keeps the login in that user’s home directory.
Test running the Broadcast containers together with the following command:
docker compose -f docker-compose.manual.yml up
This should boot up the three containers and start the Broadcast app.
5. Setup monitored services
Once you have confirmed that everything is working correctly, press CTRL+C to stop the containers.
Next, you will need to setup monitored services for the containers.
If you are on a Linux system, you want to use systemd to manage running the containers.
For example, if you’re using systemd, create the file /etc/systemd/system/broadcast.service for the Broadcast containers. Replace your-user with your username in every line:
[Unit] Description=Broadcast Requires=docker.service After=docker.service [Service] Type=simple ExecStart=/usr/bin/docker compose -f /home/your-user/broadcast/docker-compose.manual.yml up ExecStop=/usr/bin/docker compose -f /home/your-user/broadcast/docker-compose.manual.yml down Restart=always User=your-user WorkingDirectory=/home/your-user/broadcast [Install] WantedBy=multi-user.target
User= must be the user from step 4, the member of the docker group that ran docker login. Then start the service, and enable it at boot:
sudo systemctl daemon-reload sudo systemctl enable --now broadcast
Turn on plugins
3.0+
Plugins are optional. Broadcast runs without them. They need two more containers: plugins runs the plugin code, and egress is its only way to the internet. Both are in docker-compose.manual.yml, but they stay off until you turn them on. Use a server with 4 GB of RAM for plugins. See System Requirements.
1. Make the runtime secret. The automatic installer makes it. A manual install must make it once:
cd /home/your-user/broadcast mkdir -p secrets openssl rand -hex 32 > secrets/plugin_runtime_secret sudo chown -R 1000:1000 secrets sudo chmod 0400 secrets/plugin_runtime_secret
Both containers wait until this file exists.
2. Turn on the containers. Add these lines to the .env file next to docker-compose.manual.yml (not app/.env). Put your server’s public IP addresses in BROADCAST_PUBLIC_IPS, comma-separated, so that plugins cannot reach your own server through its public address:
COMPOSE_PROFILES=runtime BROADCAST_PUBLIC_IPS=203.0.113.10
Then start them:
docker compose -f docker-compose.manual.yml up -d
3. Check it. docker logs plugins shows plugin runtime on :8787. In Broadcast, Application > Plugins shows the state of the runtime.
These settings in the same .env file change the limits:
| Setting | Default | Does |
|---|---|---|
PLUGINS_MEMORY_LIMIT_MB |
256 |
Memory for the plugins container, in MB |
PLUGINS_CPU_LIMIT |
0.5 |
CPUs for the plugins container |
BROADCAST_PLUGINS_SAFE_MODE |
0 |
1 turns every plugin off. See Install, Update and Publish Plugins |
The egress container has a fixed limit of 64 MB.
Single-container deployment (alternative)
For users on small servers with limited resources, you can run Broadcast as a single container instead of separating the app and job containers. This runs Solid Queue (the background job processor) inside the Puma web server process.
Configuration
To enable single-container mode, add the following environment variable to your app .env file:
SOLID_QUEUE_IN_PUMA=true
Broadcast reads this value as on or off: true, 1, yes and on turn it on, and anything else, including false, leaves it off.
Then modify your docker-compose.manual.yml to remove the job service entirely, leaving only the app and postgres services.
Async mode for lower memory usage
By default, Solid Queue runs in fork mode, which spawns separate processes for workers and dispatchers. On small servers, this can use significant memory.
To reduce memory usage, you can enable async mode, which runs workers in threads within the same process as Puma:
SOLID_QUEUE_IN_PUMA=true SOLID_QUEUE_SUPERVISOR_MODE=async
This configuration is ideal for low-traffic deployments on servers with limited RAM.
SOLID_QUEUE_SUPERVISOR_MODE only affects the web server when SOLID_QUEUE_IN_PUMA is on. In single-container mode the Jobs page shows the mode but cannot change it, so set it here and restart Broadcast.
Low memory mode with two containers
You do not need a single container to save memory. With the standard two containers, choose Low memory in the Job server memory mode panel on the Jobs page, save, and restart the job container:
docker compose -f docker-compose.manual.yml restart job
You can also set SOLID_QUEUE_SUPERVISOR_MODE=async in your app .env file instead. The variable takes priority over the Jobs page. See Performance Tuning for the trade-offs.
Trade-offs
| Mode | Pros | Cons |
|---|---|---|
| Two containers (default) | Better isolation, easier scaling, recommended for production | Uses more resources |
| Two containers, Low memory mode | Keeps the web interface separate from background work | All background work in one process |
| Single container (fork) | Simpler deployment, fewer containers | Still uses multiple processes |
| Single container (async) | Lowest memory usage | All work in one process, less isolation |
For most production deployments, the two-container setup is recommended. Single-container mode is best suited for personal projects or low-traffic sites where simplicity and resource savings are priorities.
Troubleshooting
“Missing Active Record encryption credential”
Saving a two-factor setup, an AI API key, an autopilot’s OpenRouter key or a backup destination fails, and the log shows:
Missing Active Record encryption credential: active_record_encryption.primary_key
Cause: Broadcast encrypts these values with three keys from the environment. The automatic installer generates them. Older versions of the sample app/.env file for manual installation do not contain them. Broadcast uses the keys only when all three are set, so one missing key disables all of them.
2.49+
At startup, the log shows a warning that names each missing variable. Broadcast also treats a value that starts with replace-with as missing.
Fix: generate three values, the same way the installer does:
openssl rand -hex 16
Run it three times and add all three results to your app .env file:
ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY=first-value ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY=second-value ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT=third-value
Then recreate the containers so they read the file:
docker compose -f docker-compose.manual.yml up -d
A plain docker compose restart does not read the .env file again. If you run Broadcast with the systemd service from step 5, run sudo systemctl restart broadcast instead. Never change these values once data is saved with them: Broadcast cannot read values encrypted with the old keys.
The app cannot connect to PostgreSQL
Cause: DATABASE_PASSWORD in the app .env file and POSTGRES_PASSWORD in the db .env file are different. PostgreSQL stores the password when it creates its data directory, on the first start. Changing POSTGRES_PASSWORD later does not change it.
Fix: set DATABASE_PASSWORD to the password the database was first created with. On a new installation with no data yet, you can instead stop the containers, delete db/postgres-data, make both values the same, and start again.
“A license key is required to use the test server”
Cause: LICENSE_KEY is missing from the app .env file.
Fix: add the key from your customer dashboard, then recreate the containers with docker compose -f docker-compose.manual.yml up -d (or sudo systemctl restart broadcast with the systemd service from step 5). See Setup.
Uploads fail
The upload shows “could not be saved: the server cannot write to its uploads folder”. The API returns a 422. Broadcast keeps no file asset for a failed upload.
Cause: the app or job container cannot write to /rails/uploads or /rails/storage. Usually the host folders are not owned by uid 1000, or the uploads folder is not mounted in one of the containers. A full disk gives the same message.
Find it: go to Application → Host System. A red banner, “A storage folder needs attention”, lists each problem per container (app and job) with its fix. Each container also writes a [StorageFolderCheck] line to its log when it starts:
- “/rails/uploads is not writable” comes with the
chowncommand to run. - “is not mounted in this container” comes with the volume line to add (
- <host folder>:/rails/uploads).
The app still starts when a folder has a problem.
Fix: run the chown command from step 2 again (sudo chown -R 1000:1000 <host folder>), add any missing volume line, then recreate the containers with docker compose -f docker-compose.manual.yml up -d.
CSV imports stay “in progress” and file assets show no dimensions
Cause: the job container cannot read uploaded files. Manual installations set up before November 2026 mount the uploads folder in the app container only.
Fix: in docker-compose.manual.yml, add this line under volumes: of the job service, below the storage line:
- /home/replace-with-your-user/broadcast/app/uploads:/rails/uploads
Then recreate the containers with docker compose -f docker-compose.manual.yml up -d. Then import the file again for each import that did not finish.