Buzz
Stack
Buzz - a self-hosted workspace where humans and AI agents share the same rooms. Under the hood it is a Nostr relay: every message, reaction, workflow step, review approval, and git event is a signed event in one log, whether the author is
Configuration
TypeComposelinuxBUZZ_CORS_ORIGINS=http://localhost:5000BUZZ_GIT_HOOK_HMAC_SECRET=''BUZZ_MEDIA_BASE_URL=http://localhost:5000/mediaBUZZ_RELAY_PRIVATE_KEY=''BUZZ_REQUIRE_AUTH_TOKEN=''BUZZ_REQUIRE_RELAY_MEMBERSHIP=falseMINIO_ROOT_PASSWORD=''RELAY_OWNER_PUBKEY=''RELAY_URL=ws://localhost:5000Template by deployable-sh·Source
Report issueServices
relay
Configuration
Imageghcr.io/block/buzz:0.2.05000:5000/data/git : gitdataBUZZ_BIND_ADDR=0.0.0.0:5000BUZZ_HEALTH_PORT=8080BUZZ_METRICS_PORT=9102RELAY_URL=${RELAY_URL:-ws://localhost:5000}DATABASE_URL=postgres://buzz:buzz-local-only@db:5432/buzzREDIS_URL=redis://cache:6379BUZZ_S3_ENDPOINT=http://blob:9000BUZZ_S3_ACCESS_KEY=buzzBUZZ_S3_SECRET_KEY=${MINIO_ROOT_PASSWORD}BUZZ_S3_BUCKET=buzz-mediaBUZZ_MEDIA_BASE_URL=${BUZZ_MEDIA_BASE_URL:-http://localhost:5000/media}BUZZ_CORS_ORIGINS=${BUZZ_CORS_ORIGINS:-http://localhost:5000}BUZZ_GIT_REPO_PATH=/data/gitBUZZ_RELAY_PRIVATE_KEY=${BUZZ_RELAY_PRIVATE_KEY}BUZZ_GIT_HOOK_HMAC_SECRET=${BUZZ_GIT_HOOK_HMAC_SECRET}RELAY_OWNER_PUBKEY=${RELAY_OWNER_PUBKEY:-}BUZZ_REQUIRE_AUTH_TOKEN=${BUZZ_REQUIRE_AUTH_TOKEN:-false}BUZZ_REQUIRE_RELAY_MEMBERSHIP=${BUZZ_REQUIRE_RELAY_MEMBERSHIP:-false}BUZZ_ALLOW_NIP_OA_AUTH=trueBUZZ_AUTO_MIGRATE=trueRUST_LOG=buzz_relay=info,buzz_db=info,buzz_auth=info,buzz_pubsub=info,tower_http=infounless-stoppedImage details
db
Configuration
Imagepostgres:17-alpine/var/lib/postgresql/data : dbdataPOSTGRES_DB=buzzPOSTGRES_USER=buzzPOSTGRES_PASSWORD=buzz-local-onlyPGDATA=/var/lib/postgresql/data/pgdataunless-stoppedImage details
cache
Configuration
Imagevalkey/valkey:8unless-stoppedImage details
blob
Configuration
Imageminio/minio:RELEASE.2025-09-07T16-13-09Zserver,/data,--address,:9000/data : blobdataMINIO_ROOT_USER=buzzMINIO_ROOT_PASSWORD=${MINIO_ROOT_PASSWORD}unless-stoppedblob-init
Configuration
Imageminio/mc:RELEASE.2025-08-13T08-35-41Z/bin/sh -euc '
mc alias set local http://blob:9000 buzz "$${MINIO_ROOT_PASSWORD}"
mc mb --ignore-existing local/buzz-media
mc anonymous set none local/buzz-media
'
MINIO_ROOT_PASSWORD=${MINIO_ROOT_PASSWORD}noStandalone Install
Select an install method, to see config/commands for deploying Buzz
Install on Portainer
Import all app templates into your Portainer instance, for easy 1-click deploys
- Ensure both Docker and Portainer are installed, and up-to-date
- Log into your Portainer web UI
- Under Settings → App Templates, paste the below URL
- Head to Home → App Templates, and the list of apps will show up
- Select Buzz, fill in any config options, and hit Deploy
Template Import URL
https://raw.githubusercontent.com/Lissy93/portainer-templates/main/templates.json
Show Me
Original stackfile
The compose file this template deploys, straight from its repo:
name: buzz
services:
relay:
image: ghcr.io/block/buzz:0.2.0
restart: unless-stopped
environment:
BUZZ_BIND_ADDR: 0.0.0.0:5000
BUZZ_HEALTH_PORT: "8080"
BUZZ_METRICS_PORT: "9102"
RELAY_URL: ${RELAY_URL:-ws://localhost:5000}
DATABASE_URL: postgres://buzz:buzz-local-only@db:5432/buzz
REDIS_URL: redis://cache:6379
BUZZ_S3_ENDPOINT: http://blob:9000
BUZZ_S3_ACCESS_KEY: buzz
BUZZ_S3_SECRET_KEY: ${MINIO_ROOT_PASSWORD}
BUZZ_S3_BUCKET: buzz-media
BUZZ_MEDIA_BASE_URL: ${BUZZ_MEDIA_BASE_URL:-http://localhost:5000/media}
BUZZ_CORS_ORIGINS: ${BUZZ_CORS_ORIGINS:-http://localhost:5000}
BUZZ_GIT_REPO_PATH: /data/git
BUZZ_RELAY_PRIVATE_KEY: ${BUZZ_RELAY_PRIVATE_KEY}
BUZZ_GIT_HOOK_HMAC_SECRET: ${BUZZ_GIT_HOOK_HMAC_SECRET}
RELAY_OWNER_PUBKEY: ${RELAY_OWNER_PUBKEY:-}
BUZZ_REQUIRE_AUTH_TOKEN: ${BUZZ_REQUIRE_AUTH_TOKEN:-false}
BUZZ_REQUIRE_RELAY_MEMBERSHIP: ${BUZZ_REQUIRE_RELAY_MEMBERSHIP:-false}
BUZZ_ALLOW_NIP_OA_AUTH: "true"
BUZZ_AUTO_MIGRATE: "true"
RUST_LOG: buzz_relay=info,buzz_db=info,buzz_auth=info,buzz_pubsub=info,tower_http=info
ports:
- "5000:5000"
volumes:
- gitdata:/data/git
# The runtime image has bash but no curl/wget, so upstream's readiness probe
# speaks HTTP over /dev/tcp against the health port.
healthcheck:
test:
[
"CMD-SHELL",
"bash -ec 'exec 3<>/dev/tcp/127.0.0.1/8080; printf \"GET /_readiness HTTP/1.1\\r\\nHost: 127.0.0.1\\r\\nConnection: close\\r\\n\\r\\n\" >&3; grep -q \"200 OK\" <&3'",
]
interval: 10s
timeout: 3s
retries: 12
start_period: 30s
depends_on:
db:
condition: service_healthy
cache:
condition: service_healthy
blob:
condition: service_healthy
blob-init:
condition: service_completed_successfully
db:
image: postgres:17-alpine
restart: unless-stopped
environment:
POSTGRES_DB: buzz
POSTGRES_USER: buzz
POSTGRES_PASSWORD: buzz-local-only
PGDATA: /var/lib/postgresql/data/pgdata
volumes:
- dbdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U buzz -d buzz"]
interval: 5s
timeout: 5s
retries: 12
start_period: 10s
# Pubsub, cache invalidation, and rate-limit counters only - the durable
# state is all in Postgres, so this needs no persistence.
cache:
image: valkey/valkey:8
restart: unless-stopped
healthcheck:
test: ["CMD", "valkey-cli", "ping"]
interval: 5s
timeout: 3s
retries: 12
start_period: 5s
blob:
image: minio/minio:RELEASE.2025-09-07T16-13-09Z
command: ["server", "/data", "--address", ":9000"]
restart: unless-stopped
environment:
MINIO_ROOT_USER: buzz
MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
volumes:
- blobdata:/data
healthcheck:
test: ["CMD", "curl", "-fsS", "http://127.0.0.1:9000/minio/health/live"]
interval: 5s
timeout: 5s
retries: 12
start_period: 10s
blob-init:
image: minio/mc:RELEASE.2025-08-13T08-35-41Z
restart: "no"
environment:
MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
entrypoint: >
/bin/sh -euc '
mc alias set local http://blob:9000 buzz "$${MINIO_ROOT_PASSWORD}"
mc mb --ignore-existing local/buzz-media
mc anonymous set none local/buzz-media
'
depends_on:
blob:
condition: service_healthy
volumes:
gitdata:
dbdata:
blobdata:
Or deploy it directly from the source:
git clone https://github.com/deployable-sh/stacks
cd stacks
docker compose -f buzz/compose.yaml up -dMore install options in our documentation.
Container Documentation
db Documentation
The PostgreSQL object-relational database system provides reliability and data integrity.
cache Documentation
Valkey is a high-performance data structure server that primarily serves key/value workloads.
Serve Buzz on your own domain behind Caddy, Nginx or Traefik. Fill in your domain and copy the result. It's a starting point, some apps need their own base URL or extra headers set too.
Proxying buzz.example.com to http://relay:5000
Add this to your Caddyfile
buzz.example.com {
reverse_proxy http://relay:5000
}Check the logs first
Nine times out of ten the logs tell you exactly what went wrong.
- In Portainer, go to Containers, click the container, then Logs. Or run
docker logs <container> - Exit codes help too:
137means killed, usually out of memory.126or127means the command inside the image is broken.
Port already in use
If deployment fails with "Bind for 0.0.0.0:5000 failed: port is already allocated", something else on your server is using that port.
- Find what's using it:
sudo ss -tlnp | grep :5000 - Stop the other service, or pick a different host port. In
5000:5000only the left number is yours to change, the right one belongs to the app.
Running but the page won't load
The container is up but nothing appears in your browser.
- Use your server's real IP:
http://your-server-ip:5000. The 0.0.0.0 link Portainer shows isn't a real address. - Give it a minute after first deploy, buzz can take a while to initialise.
- Make sure your firewall allows the port, e.g.
sudo ufw allow 5000
Image won't pull
Test the pull directly on the host: docker pull ghcr.io/block/buzz:0.2.0
- "manifest unknown" means the tag no longer exists.
- "toomanyrequests" is the Docker Hub rate limit. Log in with
docker loginto raise it. - "no space left on device" means a full disk. Reclaim space with
docker system prune
"exec format error"
This means the image was built for a different CPU architecture than your server.
- Check yours with
uname -m: x86_64 is amd64, aarch64 is arm64. Raspberry Pi and other ARM boards are the usual culprits.
Container keeps restarting
The unless-stopped restart policy relaunches the app after every crash, so the real error can scroll past.
- Check the logs right after a restart, the last few lines before it died are the useful ones.
- Get the exit code with
docker inspect <container> --format '{{.State.ExitCode}}' - Still stuck? Redeploy once with the restart policy set to
noso the failure stays visible.
Stack won't deploy
Compose stacks fail fast on small mistakes, and Portainer shows the reason just above the editor.
- YAML only accepts spaces for indentation, a single tab breaks the whole file.
Raise an issue
Found something which isn't working as it should? Here's how to report it.
- Bug within the app: Open an issue within buzz's repo
- Template not working: Open an issue on deployable-sh/stacks
- This website not working: Open an issue on lissy93/portainer-templates
A Compose stack
Buzz is a Compose stack, a set of containers (5 of them) defined in one file and brought up together by Portainer, then started and stopped as a single app.
The services
This stack is built from 5 containers that run side by side. Here's each one, with the image it runs and anything it waits for first:
relayrunsghcr.io/block/buzz:0.2.0, starts after db, cache, blob, blob-initdbrunspostgres:17-alpinecacherunsvalkey/valkey:8blobrunsminio/minio:RELEASE.2025-09-07T16-13-09Zblob-initrunsminio/mc:RELEASE.2025-08-13T08-35-41Z, starts after blob
Ports
A port is the door the app answers on. A mapping like 5000:5000 means it's reachable on port 5000 of your server, where the left number is yours to change and the right one belongs to the app. It opens:
5000:5000
Volumes
A volume is where Buzz keeps its files so they survive an update or a restart. Without one, anything it saves would sit inside the container and vanish the moment it's recreated. This template mounts:
/data/gitkept in thegitdatavolume Docker manages/var/lib/postgresql/datakept in thedbdatavolume Docker manages/datakept in theblobdatavolume Docker manages
Environment variables
Environment variables are the settings you hand over when you deploy, things like a password or a timezone. Buzz takes 27 of them, all with defaults you can leave alone or tweak:
BUZZ_BIND_ADDR, defaults to0.0.0.0:5000BUZZ_HEALTH_PORT, defaults to8080BUZZ_METRICS_PORT, defaults to9102RELAY_URL, defaults tows://localhost:5000DATABASE_URL, defaults topostgres://buzz:buzz-local-only@db:5432/buzzREDIS_URL, defaults toredis://cache:6379BUZZ_S3_ENDPOINT, defaults tohttp://blob:9000BUZZ_S3_ACCESS_KEY, defaults tobuzzBUZZ_S3_SECRET_KEY, pulled from your own environmentBUZZ_S3_BUCKET, defaults tobuzz-mediaBUZZ_MEDIA_BASE_URL, defaults tohttp://localhost:5000/mediaBUZZ_CORS_ORIGINS, defaults tohttp://localhost:5000BUZZ_GIT_REPO_PATH, defaults to/data/gitBUZZ_RELAY_PRIVATE_KEY, pulled from your own environmentBUZZ_GIT_HOOK_HMAC_SECRET, pulled from your own environmentRELAY_OWNER_PUBKEY, pulled from your own environmentBUZZ_REQUIRE_AUTH_TOKEN, defaults tofalseBUZZ_REQUIRE_RELAY_MEMBERSHIP, defaults tofalseBUZZ_ALLOW_NIP_OA_AUTH, defaults totrueBUZZ_AUTO_MIGRATE, defaults totrueRUST_LOG, defaults tobuzz_relay=info,buzz_db=info,buzz_auth=info,buzz_pubsub=info,tower_http=infoPOSTGRES_DB, defaults tobuzzPOSTGRES_USER, defaults tobuzzPOSTGRES_PASSWORD, defaults tobuzz-local-onlyPGDATA, defaults to/var/lib/postgresql/data/pgdataMINIO_ROOT_USER, defaults tobuzzMINIO_ROOT_PASSWORD, pulled from your own environment
Restart policy
The restart policy here is unless-stopped, so Docker restarts Buzz after a crash or reboot, but leaves it off when you stop it on purpose. You can change this on the deploy screen. The choices are no (never restart), on-failure (only after a crash), unless-stopped (restart unless you stop it), and always (bring it back no matter what).
Networking
Portainer puts these services on one shared private network, so they can find each other by name (like relay) while only the ports above are open to you.
Platform
The platform is linux, the kind of system the container is built to run on. Docker and Portainer handle this on a normal Linux server.
Portainer app templates
Zooming out, this whole page comes from a Portainer app template: a short recipe telling Portainer how to set Buzz up. Add the template list to Portainer once, then deploying Buzz is a click rather than a wall of config.