Budibase
Stack
Budibase allows no-code users to build apps quickly, with more functionality available with a little bit of inline code.
Services
app-service
Configuration
Imagebudibase.docker.scarf.sh/budibase/apps/plugins : /portainer/Files/AppData/Config/budibase/pluginsSELF_HOSTED=1COUCH_DB_URL=http://${COUCH_DB_USER}:${COUCH_DB_PASSWORD}@couchdb-service:5984WORKER_URL=http://worker-service:4003MINIO_URL=http://minio-service:9000MINIO_ACCESS_KEY=${MINIO_ACCESS_KEY}MINIO_SECRET_KEY=${MINIO_SECRET_KEY}INTERNAL_API_KEY=${INTERNAL_API_KEY}BUDIBASE_ENVIRONMENT=${BUDIBASE_ENVIRONMENT}PORT=4002JWT_SECRET=${JWT_SECRET}LOG_LEVEL=infoSENTRY_DSN=https://a34ae347621946bf8acded18e5b7d4b8@o420233.ingest.sentry.io/5338131ENABLE_ANALYTICS=trueREDIS_URL=redis-service:6379REDIS_PASSWORD=${REDIS_PASSWORD}BB_ADMIN_USER_EMAIL=${BB_ADMIN_USER_EMAIL}BB_ADMIN_USER_PASSWORD=${BB_ADMIN_USER_PASSWORD}PLUGINS_DIR=${PLUGINS_DIR}unless-stoppedworker-service
Configuration
Imagebudibase.docker.scarf.sh/budibase/workerSELF_HOSTED=1PORT=4003CLUSTER_PORT=${MAIN_PORT}JWT_SECRET=${JWT_SECRET}MINIO_ACCESS_KEY=${MINIO_ACCESS_KEY}MINIO_SECRET_KEY=${MINIO_SECRET_KEY}MINIO_URL=http://minio-service:9000APPS_URL=http://app-service:4002COUCH_DB_USERNAME=${COUCH_DB_USER}COUCH_DB_PASSWORD=${COUCH_DB_PASSWORD}COUCH_DB_URL=http://${COUCH_DB_USER}:${COUCH_DB_PASSWORD}@couchdb-service:5984SENTRY_DSN=https://a34ae347621946bf8acded18e5b7d4b8@o420233.ingest.sentry.io/5338131INTERNAL_API_KEY=${INTERNAL_API_KEY}REDIS_URL=redis-service:6379REDIS_PASSWORD=${REDIS_PASSWORD}unless-stoppedminio-service
Configuration
Imageminio/minioserver /data --console-address ":9001"/data : /portainer/Files/AppData/Config/minio/minio_dataMINIO_ACCESS_KEY=${MINIO_ACCESS_KEY}MINIO_SECRET_KEY=${MINIO_SECRET_KEY}MINIO_BROWSER=offunless-stoppedImage details
proxy-service
Configuration
Imagebudibase/proxy${MAIN_PORT}:10000PROXY_RATE_LIMIT_WEBHOOKS_PER_SECOND=10PROXY_RATE_LIMIT_API_PER_SECOND=20APPS_UPSTREAM_URL=http://app-service:4002WORKER_UPSTREAM_URL=http://worker-service:4003MINIO_UPSTREAM_URL=http://minio-service:9000COUCHDB_UPSTREAM_URL=http://couchdb-service:5984WATCHTOWER_UPSTREAM_URL=http://watchtower-service:8080RESOLVER=127.0.0.11unless-stoppedImage details
couchdb-service
Configuration
Imageibmcom/couchdb3/opt/couchdb/data : /portainer/Files/AppData/Config/couchdb/couchdb3_dataCOUCHDB_PASSWORD=${COUCH_DB_PASSWORD}COUCHDB_USER=${COUCH_DB_USER}unless-stoppedImage details
couch-init
Configuration
Imagecurlimages/curlsh,-c,sleep 10 && $${PUT_CALL}/_users && $${PUT_CALL}/_replicator; fg;PUT_CALL=curl -u ${COUCH_DB_USER}:${COUCH_DB_PASSWORD} -X PUT couchdb-service:5984Image details
redis-service
Configuration
Imageredisredis-server --requirepass ${REDIS_PASSWORD}/data : /portainer/Files/AppData/Config/redis/redis_dataunless-stoppedImage details
watchtower-service
Configuration
Imagecontainrrr/watchtower--debug --http-api-update bbapps bbworker bbproxy/var/run/docker.sock : /var/run/docker.sockWATCHTOWER_HTTP_API=trueWATCHTOWER_HTTP_API_TOKEN=budibaseWATCHTOWER_CLEANUP=truealwaysImage details
Standalone Install
Select an install method, to see config/commands for deploying Budibase
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 Budibase, 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:
# optional ports are specified throughout for more advanced use cases.
services:
app-service:
restart: unless-stopped
image: budibase.docker.scarf.sh/budibase/apps
container_name: bbapps
environment:
SELF_HOSTED: 1
COUCH_DB_URL: http://${COUCH_DB_USER}:${COUCH_DB_PASSWORD}@couchdb-service:5984
WORKER_URL: http://worker-service:4003
MINIO_URL: http://minio-service:9000
MINIO_ACCESS_KEY: ${MINIO_ACCESS_KEY}
MINIO_SECRET_KEY: ${MINIO_SECRET_KEY}
INTERNAL_API_KEY: ${INTERNAL_API_KEY}
BUDIBASE_ENVIRONMENT: ${BUDIBASE_ENVIRONMENT}
PORT: 4002
JWT_SECRET: ${JWT_SECRET}
LOG_LEVEL: info
SENTRY_DSN: https://a34ae347621946bf8acded18e5b7d4b8@o420233.ingest.sentry.io/5338131
ENABLE_ANALYTICS: "true"
REDIS_URL: redis-service:6379
REDIS_PASSWORD: ${REDIS_PASSWORD}
BB_ADMIN_USER_EMAIL: ${BB_ADMIN_USER_EMAIL}
BB_ADMIN_USER_PASSWORD: ${BB_ADMIN_USER_PASSWORD}
PLUGINS_DIR: ${PLUGINS_DIR}
depends_on:
- worker-service
- redis-service
volumes:
- /portainer/Files/AppData/Config/budibase/plugins:/plugins
worker-service:
restart: unless-stopped
image: budibase.docker.scarf.sh/budibase/worker
container_name: bbworker
environment:
SELF_HOSTED: 1
PORT: 4003
CLUSTER_PORT: ${MAIN_PORT}
JWT_SECRET: ${JWT_SECRET}
MINIO_ACCESS_KEY: ${MINIO_ACCESS_KEY}
MINIO_SECRET_KEY: ${MINIO_SECRET_KEY}
MINIO_URL: http://minio-service:9000
APPS_URL: http://app-service:4002
COUCH_DB_USERNAME: ${COUCH_DB_USER}
COUCH_DB_PASSWORD: ${COUCH_DB_PASSWORD}
COUCH_DB_URL: http://${COUCH_DB_USER}:${COUCH_DB_PASSWORD}@couchdb-service:5984
SENTRY_DSN: https://a34ae347621946bf8acded18e5b7d4b8@o420233.ingest.sentry.io/5338131
INTERNAL_API_KEY: ${INTERNAL_API_KEY}
REDIS_URL: redis-service:6379
REDIS_PASSWORD: ${REDIS_PASSWORD}
depends_on:
- redis-service
- minio-service
- couch-init
minio-service:
restart: unless-stopped
image: minio/minio
volumes:
- /portainer/Files/AppData/Config/minio/minio_data:/data
environment:
MINIO_ACCESS_KEY: ${MINIO_ACCESS_KEY}
MINIO_SECRET_KEY: ${MINIO_SECRET_KEY}
MINIO_BROWSER: "off"
command: server /data --console-address ":9001"
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
interval: 30s
timeout: 20s
retries: 3
proxy-service:
restart: unless-stopped
ports:
- "${MAIN_PORT}:10000"
container_name: bbproxy
image: budibase/proxy
environment:
- PROXY_RATE_LIMIT_WEBHOOKS_PER_SECOND=10
- PROXY_RATE_LIMIT_API_PER_SECOND=20
- APPS_UPSTREAM_URL=http://app-service:4002
- WORKER_UPSTREAM_URL=http://worker-service:4003
- MINIO_UPSTREAM_URL=http://minio-service:9000
- COUCHDB_UPSTREAM_URL=http://couchdb-service:5984
- WATCHTOWER_UPSTREAM_URL=http://watchtower-service:8080
- RESOLVER=127.0.0.11
depends_on:
- minio-service
- worker-service
- app-service
- couchdb-service
couchdb-service:
restart: unless-stopped
image: ibmcom/couchdb3
environment:
- COUCHDB_PASSWORD=${COUCH_DB_PASSWORD}
- COUCHDB_USER=${COUCH_DB_USER}
volumes:
- /portainer/Files/AppData/Config/couchdb/couchdb3_data:/opt/couchdb/data
couch-init:
image: curlimages/curl
environment:
PUT_CALL: "curl -u ${COUCH_DB_USER}:${COUCH_DB_PASSWORD} -X PUT couchdb-service:5984"
depends_on:
- couchdb-service
command: ["sh","-c","sleep 10 && $${PUT_CALL}/_users && $${PUT_CALL}/_replicator; fg;"]
redis-service:
restart: unless-stopped
image: redis
command: redis-server --requirepass ${REDIS_PASSWORD}
volumes:
- /portainer/Files/AppData/Config/redis/redis_data:/data
watchtower-service:
restart: always
image: containrrr/watchtower
volumes:
- /var/run/docker.sock:/var/run/docker.sock
command: --debug --http-api-update bbapps bbworker bbproxy
environment:
- WATCHTOWER_HTTP_API=true
- WATCHTOWER_HTTP_API_TOKEN=budibase
- WATCHTOWER_CLEANUP=true
labels:
- "com.centurylinklabs.watchtower.enable=false"
Or deploy it directly from the source:
git clone https://github.com/xneo1/portainer_templates
cd portainer_templates
docker compose -f Template/Stack/budibase.yml up -dMore install options in our documentation.
Container Documentation
minio-service Documentation
Multi-Cloud Object Storage
couchdb-service Documentation
An Apache CouchDB 3 image maintained by the IBM Cloudant team.
couch-init Documentation
Official curl docker (http://curl.se): command line tool and library for transferring data with URLs
redis-service Documentation
Redis is the world’s fastest data platform for caching, vector search, and NoSQL databases.
watchtower-service Documentation
A process for automating Docker container base image updates.
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.
Permission denied on volumes
If the logs show "permission denied", the app can't write to its data folder on the host.
- Fix the ownership:
sudo chown -R 1000:1000 /portainer/Files/AppData/Config/budibase/plugins(and the same for the other mapped folders)
Can't reach the Docker socket
budibase talks to Docker through /var/run/docker.sock. If the logs show
"permission denied while trying to connect to the Docker daemon socket", the app's user can't access it.
- Check the socket exists on the host:
ls -l /var/run/docker.sock - Run the container as root, or add the docker group's id to the container with
group_add.
Image won't pull
Test the pull directly on the host: docker pull budibase.docker.scarf.sh/budibase/apps
- "manifest unknown" means the tag no longer exists. This template uses
latest, so try pinning a specific version instead. - "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 budibase's repo
- Template not working: Open an issue on xneo1/portainer_templates
- This website not working: Open an issue on lissy93/portainer-templates
A Compose stack
Budibase is a Compose stack, a set of containers (8 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 8 containers that run side by side. Here's each one, with the image it runs and anything it waits for first:
app-servicerunsbudibase.docker.scarf.sh/budibase/apps, starts after worker-service, redis-serviceworker-servicerunsbudibase.docker.scarf.sh/budibase/worker, starts after redis-service, minio-service, couch-initminio-servicerunsminio/minioproxy-servicerunsbudibase/proxy, starts after minio-service, worker-service, app-service, couchdb-servicecouchdb-servicerunsibmcom/couchdb3couch-initrunscurlimages/curl, starts after couchdb-serviceredis-servicerunsrediswatchtower-servicerunscontainrrr/watchtower
Volumes
A volume is where Budibase 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:
/pluginsfrom/portainer/Files/AppData/Config/budibase/pluginson the host/datafrom/portainer/Files/AppData/Config/minio/minio_dataon the host/opt/couchdb/datafrom/portainer/Files/AppData/Config/couchdb/couchdb3_dataon the host/datafrom/portainer/Files/AppData/Config/redis/redis_dataon the host/var/run/docker.sockfrom/var/run/docker.sockon the host (a socket it talks to, not storage)
Environment variables
Environment variables are the settings you hand over when you deploy, things like a password or a timezone. Budibase takes 37 of them, all with defaults you can leave alone or tweak:
SELF_HOSTED, defaults to1COUCH_DB_URL, defaults tohttp://COUCH_DB_USER:COUCH_DB_PASSWORD@couchdb-service:5984WORKER_URL, defaults tohttp://worker-service:4003MINIO_URL, defaults tohttp://minio-service:9000MINIO_ACCESS_KEY, pulled from your own environmentMINIO_SECRET_KEY, pulled from your own environmentINTERNAL_API_KEY, pulled from your own environmentBUDIBASE_ENVIRONMENT, pulled from your own environmentPORT, defaults to4003JWT_SECRET, pulled from your own environmentLOG_LEVEL, defaults toinfoSENTRY_DSN, defaults tohttps://a34ae347621946bf8acded18e5b7d4b8@o420233.ingest.sentry.io/5338131ENABLE_ANALYTICS, defaults totrueREDIS_URL, defaults toredis-service:6379REDIS_PASSWORD, pulled from your own environmentBB_ADMIN_USER_EMAIL, pulled from your own environmentBB_ADMIN_USER_PASSWORD, pulled from your own environmentPLUGINS_DIR, pulled from your own environmentCLUSTER_PORT, pulled from your own environmentAPPS_URL, defaults tohttp://app-service:4002COUCH_DB_USERNAME, pulled from your own environmentCOUCH_DB_PASSWORD, pulled from your own environmentMINIO_BROWSER, defaults tooffPROXY_RATE_LIMIT_WEBHOOKS_PER_SECOND, defaults to10PROXY_RATE_LIMIT_API_PER_SECOND, defaults to20APPS_UPSTREAM_URL, defaults tohttp://app-service:4002WORKER_UPSTREAM_URL, defaults tohttp://worker-service:4003MINIO_UPSTREAM_URL, defaults tohttp://minio-service:9000COUCHDB_UPSTREAM_URL, defaults tohttp://couchdb-service:5984WATCHTOWER_UPSTREAM_URL, defaults tohttp://watchtower-service:8080RESOLVER, defaults to127.0.0.11COUCHDB_PASSWORD, pulled from your own environmentCOUCHDB_USER, pulled from your own environmentPUT_CALL, defaults tocurl -u COUCH_DB_USER:COUCH_DB_PASSWORD -X PUT couchdb-service:5984WATCHTOWER_HTTP_API, defaults totrueWATCHTOWER_HTTP_API_TOKEN, defaults tobudibaseWATCHTOWER_CLEANUP, defaults totrue
Restart policy
The restart policy here is unless-stopped, so Docker restarts Budibase 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 app-service) 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 Budibase up. Add the template list to Portainer once, then deploying Budibase is a click rather than a wall of config.