Run a node

Prerequisites

Everything else — PHP, MariaDB, Tor, nginx, processors — ships inside the image. You don't install anything else on the host.

• Docker 20.10+ (the Compose plugin is included)
• ~1 GB free disk for the image and database
• 512 MB RAM minimum (1 GB recommended)
• Free TCP ports for whatever you want to publish (default 80/443)

Get the code (or the image)

Two ways to start: clone the repo and build locally, or pull the prebuilt image straight from Docker Hub. Either way the only configuration file you'll touch is docker-compose.yml — it is heavily commented; uncomment what you need and everything else has working defaults.

• Clone & build — gets you the source, the docker-compose.yml, the helper scripts, and lets you patch or audit anything. Subsequent docker compose up calls without --build reuse the local image
• Pull from Docker Hub — faster, no source on disk. You still need a docker-compose.yml — either grab it from the repo or write a minimal one and replace the build: block with image: eiou/eiou:latest

Name your node

The container name and every volume name derive from NODE_NAME (default eiou-node). Set it to anything else when you want to run more than one node side by side without name collisions, or just to give the container a recognizable label. EIOU_NAME is separate — it sets the cosmetic display name in the local GUI header and is never sent to other nodes.

NODE_NAME (and every other env var on this page) can be supplied three ways — pick whichever fits your setup; the container reads the same variable either way:

• A .env file next to docker-compose.yml — docker compose auto-loads it. Best for values you want under version control or that change between hosts
• An environment: block directly in docker-compose.yml — what the External access, SSL, and Restore examples use. Best for values that travel with the compose file
• A -e flag on docker run if you're not using compose at all (e.g. docker run -e NODE_NAME=my-wallet ... eiou/eiou) — one-off launches and CI scripts

With the bundled Compose file, setting NODE_NAME=my-wallet creates container my-wallet and prefixes its seven named volumes with my-wallet-. A raw docker run command must declare those mounts explicitly.

Reach the node from outside Docker

Three ways to expose a node:

• Default (QUICKSTART=eiou) — the bundled docker-compose.yml exposes both http://eiou and https://eiou (with an auto-generated self-signed cert) inside the Docker network only. Private-address delivery fails closed unless you explicitly set EIOU_ALLOW_PRIVATE_DELIVERY=true. With that development-only opt-in, practical node-to-node reachability is HTTP: the default P2P_SSL_VERIFY=true still rejects self-signed HTTPS certificates unless you share a CA (see SSL certificates). Neither surface is reachable outside the Docker network
• Public IP or FQDN — set EIOU_HOST to a real address and (optionally) EIOU_PORT for a non-standard port. Pair with Let's Encrypt or a CA-signed cert (see SSL certificates) so peers don't trip over a self-signed warning
• Tor-only — comment out both QUICKSTART and EIOU_HOST in docker-compose.yml. The node skips HTTP/HTTPS entirely and is reachable only at its .onion address

When both EIOU_HOST and QUICKSTART are set, EIOU_HOST wins for the registered address (and for the SSL CN) — QUICKSTART stays around as the in-Docker hostname only. EIOU_NAME is purely the cosmetic display label in the local GUI; it never goes out on the wire.

SSL certificates

SSL only matters if the node is serving HTTP/HTTPS — i.e. you have a hostname set via QUICKSTART or EIOU_HOST. Tor-only nodes skip this entirely (Tor's onion routing handles encryption itself). When there is a hostname, the container generates a self-signed certificate on first boot whose Common Name matches the resolved address — priority SSL_DOMAIN > EIOU_HOST > QUICKSTART. For anything more than local testing, replace the self-signed cert. The four supported approaches are checked in priority order:

• External certs mounted at /ssl-certs (server.crt, server.key)
• Let's Encrypt — set LETSENCRYPT_EMAIL; needs a real FQDN in EIOU_HOST and port 80 reachable from the internet
• Local CA — mount ./ssl-ca with a ca.crt the container will trust
• Reverse proxy or Cloudflare Tunnel — terminate SSL outside the container and let it keep its self-signed cert internally

Cert validation on outbound P2P is strict. The default P2P_SSL_VERIFY=true rejects any self-signed cert, so stock containers can reach each other over HTTP but not HTTPS — you need either P2P_SSL_VERIFY=false (dev/testing only), a shared CA via P2P_CA_CERT, or a real Let's Encrypt / CA-signed cert before HTTPS P2P starts working between nodes. Browser-side cert behavior is independent — you'll still get a one-time warning for self-signed regardless of the P2P setting.

For multi-node SSL setups, wildcard certificates, and browser CA-trust installation see SSL Certificate Configuration.

Start the node

Configuration done — bring it up. The first boot generates a fresh BIP39-derived wallet, initializes MariaDB, brings up nginx and the P2P processors, and starts Tor. The container's healthcheck flips to healthy once MariaDB and the GUI are reachable — usually around two minutes. Tor reachability is a separate, slower stage and is not on the healthcheck path. (If you're migrating an existing wallet rather than starting fresh, see Restore from a seed phrase first.)

• MariaDB is the slowest step on first boot (encrypted redo log + TDE setup) — default timeout is 60 s with auto-recovery; total wait is typically 30–90 s
• Tor hidden service needs to (1) generate the .onion key, (2) bootstrap the local Tor process, and (3) publish the descriptor to the Tor directory authorities. Steps 1–2 finish in about a minute; step 3 commonly takes another 5–15 minutes before other nodes can actually reach you over Tor. The defaults EIOU_HS_TIMEOUT=60 and EIOU_TOR_TIMEOUT=120 only gate the in-container waits — raise them on WSL2 or slow links
• The container watchdog auto-restarts any processor that crashes; if Tor goes silent it republishes the descriptor automatically (~90 s verification window)
• Subsequent restarts skip wallet generation and come up in seconds. The .onion address is reused (it's derived from the seed), but Tor still needs to republish the descriptor — expect a few minutes before peers can reach the node again

Open the GUI

Point your browser at the node. With the default QUICKSTART=eiou setting, HTTP redirects to HTTPS and the certificate is self-signed — expect a one-time browser warning. The Tor address is reachable from Tor Browser with no warning at all.

• Local browser: https://localhost
• Tor Browser: open the node's .onion address (printed in the startup banner)
• Sign in with the auth code shown in the OPEN ALPHA banner the container prints on first boot

On first boot the container also writes the seed phrase + auth code to a single tmpfs file at /dev/shm/eiou_wallet_info_<random>. That file lives in RAM, has mode 0400, and is auto-deleted after 15 minutes — so copy the seed phrase out into your password manager before it vanishes. After it's gone (or any time on a restored node), eiou info --show-auth regenerates the auth-code-only file on demand with the same 15-minute TTL.

Persistent storage

Seven named Docker volumes survive restarts and rebuilds. The bundled Compose file prefixes their names with NODE_NAME. Treat the seven as one recovery set: mixing volumes from different recovery points is unsupported.

• {NODE_NAME}-mysql-data → /var/lib/mysql — transactions, contacts, balances (critical)
• {NODE_NAME}-config → /etc/eiou/config — wallet keys, encryption keys (critical)
• {NODE_NAME}-plugins → /etc/eiou/plugins — installed plugin directories
• {NODE_NAME}-plugin-scratch → /var/lib/eiou/plugin-scratch — durable private plugin state
• {NODE_NAME}-backups → /var/lib/eiou/backups — encrypted backups (critical)
• {NODE_NAME}-backup-locks → /var/lib/eiou/backup-locks — backup lifecycle and recovery coordination state (critical)
• {NODE_NAME}-ssl-cert → /var/lib/eiou/ssl — persisted TLS identity

Backups also run automatically every night, encrypted with AES-256-GCM — see the Backup section in System & Advanced for the live commands. To wipe these volumes (e.g. starting fresh) see Manage the container.

Restore from a seed phrase

You don't need this to start a new node — first boot generates a fresh wallet on its own. Reach for it when you're recovering: rebuilding on a new host after losing the volumes, migrating, or coming back from a docker compose down -v. Wallet keys, the Tor identity (so the same .onion), and the encryption master key are all deterministically derived from the 24-word BIP39 seed, which is why this works at all.

• Restoration only takes effect on a node with no existing wallet — if the config volume already holds keys, RESTORE_FILE is ignored. To force restore on a host that has run before, wipe the volumes first and bring the seed
• The seed is mounted as a read-only file at RESTORE_FILE — never appears in docker inspect, process listings, or shell history
• Restoration replays Tor identity and wallet keys; transaction history is not in the seed — that's what backups are for. Combine the two: seed for identity, encrypted backup for ledger

Manage the container

Day-to-day operations — check status, tail logs, restart cleanly, stop without losing data, and (deliberately) wipe the wallet. Replace eiou-node with whatever you set in NODE_NAME. The CLI lives inside the container; prepend docker exec <container> from the host.

Run multiple nodes

To run several independent nodes on one host, duplicate the service block in docker-compose.yml with a unique NODE_NAME, distinct published ports, and a separate set of volume names. Archived multi-node compose files (4-line, 10-line, 13-node cluster) live under tests/old/compose-files/ and serve as working starting points.

• Each node should publish its own host ports — pick a convention like 808X/844X
• Tor-only nodes don't need any published ports at all
• See Port Mappings for recommended layouts

Troubleshooting

The most common first-boot snags. For the long form — including TDE recovery and per-issue log paths — see Troubleshooting in Docker Configuration.