Self-Hosting Troubleshooting

Common problems running a self-hosted BioNodulo instance.

Nodes fail with “cannot connect to Docker daemon”

The engine can’t reach the container runtime. Check that:

The Docker socket is mounted into the container (/var/run/docker.sock:/var/run/docker.sock).
The runtime is running on the host (docker info succeeds).
The container user has permission to access the socket.

Out-of-memory kills during runs

A node exceeded BIONODULO_MAX_RAM or the host’s available memory. Raise the cap (if the host has headroom), run a smaller input, or move heavy steps to larger hardware.

Editor loads but workflows don’t persist

BIONODULO_DATA_DIR isn’t backed by a persistent volume — data is lost on container restart. Mount a named volume or host path as shown in Docker Deployment.

Container starts then exits immediately

Usually a missing BIONODULO_SECRET_KEY. Set it to a strong random value and restart.

WebSocket / live updates not working behind a proxy

Ensure your reverse proxy forwards WebSocket upgrade headers (Upgrade/Connection) and doesn’t buffer event streams. Disable response buffering on the editor and event routes.

Collecting logs

docker compose logs -f bionodulo

Set BIONODULO_LOG_LEVEL=debug for verbose output when filing a GitHub issue.