Broadcast Docs
Back to main site
On this page

Manual Installation

Warning: Gotcha ahead!

Although we provide a guide below, please note that manual installation is not supported due to the variety of ways that people run their servers. You may, however, still reach out to us and we can offer general guidance.

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:

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

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

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

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

YAML
# 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

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:

Shell
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_IMAGE sets the image of the app and job containers.
  • TARGETARCH sets 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:

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

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

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

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

Shell
openssl rand -hex 16

Put each result in its own variable in the app .env file:

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

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

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

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

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

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

Shell
COMPOSE_PROFILES=runtime
BROADCAST_PUBLIC_IPS=203.0.113.10

Then start them:

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

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

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

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

Shell
openssl rand -hex 16

Run it three times and add all three results to your app .env file:

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

Shell
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 chown command 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:

YAML
      - /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.