Run a node in Docker
Run lotusd from the published container image: tags, data volume, ports, a compose file, health check, logs and upgrades.
Every release publishes a container image of the node. It holds exactly the released lotusd binary on an Ubuntu 22.04 base, for linux/amd64.
Image and tags #
| Image | Content |
|---|---|
ghcr.io/lotusdevorg/lotusd | the node (lotusd) |
ghcr.io/lotusdevorg/lotus-cli | the command line client (lotus-cli) |
ghcr.io/lotusdevorg/lotus-tx, lotus-wallet, lotus-seeder | the other tools, one per image |
Each image is tagged with the version (12.4.15), with its X.Y line (12.4) and with latest.
Pull a version, not only latest, so that an upgrade is something you decide:
docker pull ghcr.io/lotusdevorg/lotusd:12.4.15
docker run --rm ghcr.io/lotusdevorg/lotusd:12.4.15 -versionThe release notes give the image digests. Pulling by digest (ghcr.io/lotusdevorg/lotusd@sha256:...) pins the exact image.
What is inside the image #
| Entrypoint | /opt/lotus/bin/lotusd |
| Default arguments | -printtoconsole -datadir=/root/.lotus |
| Data directory | /root/.lotus (mount a volume there) |
| User | root |
| Exposed ports | 10605 (P2P), 10604 (JSON-RPC, REST API, web UI) |
Arguments you put after the image name replace the default arguments, so repeat -printtoconsole -datadir=/root/.lotus when you add your own.
The image contains lotusd only. lotus-cli is a separate image, and there is no curl in either.
Ports #
| Port (mainnet) | What | Publish it? |
|---|---|---|
| 10605 | P2P | Yes, to the internet, so that other nodes can connect to yours |
| 10604 | JSON-RPC, REST API /api/v1, dashboard, wallet | On 127.0.0.1 only, then a reverse proxy if it must be public. See Security |
Testnet uses 11605 and 11604. Stratum (3334), the WebSocket listeners and the public NNG ports are off by default; publish them only when you turn those services on. See Stratum and Push interfaces.
A minimal docker run #
docker volume create lotus-data
docker run -d --name lotusd \
--restart unless-stopped \
--stop-timeout 120 \
-v lotus-data:/root/.lotus \
-p 10605:10605 \
-p 127.0.0.1:10604:10604 \
ghcr.io/lotusdevorg/lotusd:12.4.15 \
-printtoconsole -datadir=/root/.lotus \
-rpcbind=0.0.0.0 -rpcallowip=0.0.0.0/0Then check it from the host:
curl -s http://127.0.0.1:10604/api/v1/healthThe answer carries "status":"syncing" during the initial sync and "status":"ok" afterwards. The dashboard is at http://127.0.0.1:10604/dashboard.
-rpcbind=0.0.0.0 -rpcallowip=0.0.0.0/0 is needed because a request that comes through a published port does not arrive from the container's loopback: with -rpcallowip=127.0.0.1 the node answers 403 to it. What keeps the port private is the 127.0.0.1: prefix of -p. Never publish 10604 as -p 10604:10604 on a host reachable from the internet.
Compose file #
services:
lotusd:
image: ghcr.io/lotusdevorg/lotusd:12.4.15
container_name: lotusd
restart: unless-stopped
stop_grace_period: 120s
ports:
- "10605:10605"
- "127.0.0.1:10604:10604"
volumes:
- lotus-data:/root/.lotus
command:
- -printtoconsole
- -datadir=/root/.lotus
- -rpcbind=0.0.0.0
- -rpcallowip=0.0.0.0/0
healthcheck:
test: ["CMD", "bash", "-c", "exec 3<>/dev/tcp/127.0.0.1/10604"]
interval: 30s
timeout: 10s
retries: 3
logging:
driver: json-file
options:
max-size: "50m"
max-file: "5"
volumes:
lotus-data:docker compose up -d
docker compose psTo use a configuration file instead of command line options, put a lotus.conf in the volume (/root/.lotus/lotus.conf) or mount one there read-only. See Configuration.
Health check #
The health check of the compose file only tests that the HTTP port accepts connections, because the image has no HTTP client. For monitoring, probe the REST API from the host:
curl -sf http://127.0.0.1:10604/api/v1/healthIt is answered from a snapshot of the chain tip and does not wait while a block is being connected. status is ok when the node is synced and syncing during the initial block download; height, ibd, uptime_seconds and subversion are in the same object. While the chain is still loading the route answers 503.
Run lotus-cli #
Start the lotus-cli image in the node's network namespace, with the node's volume so that it finds the authentication cookie:
docker run --rm \
--network container:lotusd \
-v lotus-data:/root/.lotus:ro \
ghcr.io/lotusdevorg/lotus-cli:12.4.15 getblockchaininfoWith compose the volume is named after the project (<project>_lotus-data; docker volume ls shows it).
Logs #
With -printtoconsole the node writes its log to the container's output, and also to debug.log in the data directory.
docker logs -f --tail 100 lotusdThe logging block of the compose file keeps at most five files of 50 MB. To stop writing debug.log inside the volume, add -debuglogfile=0.
Upgrade #
- Read the notes of the release, and of every release between yours and it.
- Back up your wallet if the node holds one.
- Change the image tag in the compose file, then:
docker compose pull
docker compose up -d
curl -s http://127.0.0.1:10604/api/v1/healthThe version and subversion fields of the answer show what is running.
The data directory is kept as it is. The node needs time to flush its state when it stops: keep stop_grace_period: 120s (or docker stop -t 120). Going back to an older version is not always possible once a newer one has written to the data directory; the release notes say when it is not. See Upgrade.
Nodes must run 12.4.13 or later before the Napoleon activation (21 December 2026, 20:50 UTC). See Napoleon.
