Run with Docker

The node starts as a devnet full node: it finds peers, syncs and follows the tip. Open the dashboard at http://127.0.0.1:3000. It keeps its state in ~/mina-state, so a new container picks up where the last one stopped. --user runs it as you, so the files there stay yours.

If a container called mina already exists, or another program uses port 3000 or 8302, run this node with its own name, ports and state directory, as below. Two nodes must not share a state directory (see reuse a native node's state). Then use the new name, here mina2, in the docker commands on this page, and open the dashboard at http://127.0.0.1:3010.

The image runs mina: docker exec mina mina runs a second mina command in the same container.

docker pull prints the image's digest. Compare it with the one in the release notes; each release's notes list its image's digest.

A tag can be moved to another image; a digest can't. To run exactly the image you checked, use ghcr.io/minanode/mina-rust:0.20.0@sha256:66507e39fc2890ce37cf9d77b50517960b60887f5e655cfa2de5a35b2eeceab0 in place of ghcr.io/minanode/mina-rust:0.20.0 in the commands on this page. In Compose, set MINA_IMAGE to it in .env.

The GitHub CLI checks the image's build provenance. A passing check shows that the repository's Docker image workflow built the image from the signed release archives.

The compose file runs the same node, with the dashboard on this computer only, its SNARK worker controlled from the dashboard, and the state in ./mina-state. It starts again after a reboot.

Settings such as the work directory, the image tag, more node options and the ports go in .env; the file lists them. Stop the node with docker compose stop and start it again with docker compose start.

If you ran the quick start first, stop and remove its container with docker stop mina && docker rm mina. Its state stays in ~/mina-state: to keep that chain, set MINA_STATE_DIR in .env to its full path, which echo ~/mina-state prints.

If a container called mina already exists, or another program uses port 3000 or 8302, set this node up in its own directory with its own settings in .env, as below. Each directory keeps its own mina-state, so the two nodes never share state. Without its own COMPOSE_PROJECT_NAME, a second docker compose up -d replaces the first node's container.

Anything after the image name replaces the default command (node --network devnet), so give the whole command with your options. An option with an environment variable, listed by docker run --rm ghcr.io/minanode/mina-rust:0.20.0 node --help, may be set with -e instead.

The image sets MINA_HOME=/data and HOME=/data, so everything the node writes goes to the work directory, and MINA_HTTP_ADDR=0.0.0.0, so the dashboard is reachable through the published port. Leave these as they are. In Compose, put more options in MINA_NODE_ARGS in .env.

A plain -p 3000:3000 publishes the dashboard and the whole HTTP API on every network interface. On Linux, Docker's port rules come before ufw's, so ufw doesn't block a published port. On a server, keep 127.0.0.1:3000:3000 and open the dashboard through an SSH tunnel. To use another port on the host, change only the first number, as in 127.0.0.1:3010:3000. Worker control works at any port on 127.0.0.1.

Other listeners, such as --metrics-port, listen on 127.0.0.1 inside the container by default, which the host can't reach. Set their address option to 0.0.0.0 and publish the port on 127.0.0.1 as above.

Behind a router, forward TCP port 8302 to this machine and give the node your public address with --libp2p-external-ip 203.0.113.7. Inside the container, the node sees only Docker's private network and cannot discover that address.

For another peer port, use the same number on both sides and tell the node: -p 8312:8312 -e MINA_LIBP2P_PORT=8312, or MINA_LIBP2P_PORT=8312 in Compose's .env.

The directory mounted on /data is the node's work directory, as ~/.mina is for the native node. It outlives the container: docker rm, docker compose down and upgrades leave it in place.

To back it up, stop the node and copy the directory, for example with tar -czf mina-state.tar.gz -C ~ mina-state. Keep the copy private: it holds the peer identity. Never share a work directory between networks.

A named volume works too: -v mina-data:/data, without --user. The node then runs as the image's own user (uid 65532), and Docker keeps the files in its own storage.

If the node stops at start with Permission denied at /data, the directory isn't writable by the user it runs as. Create it yourself before the first start and run the container with --user "$(id -u):$(id -g)": if Docker creates a missing directory, root owns it.

A container may take over the state of a node you ran with the release binary, keeping its chain and peer id. Stop the native node first: never run two nodes on one work directory at the same time. Run the container as yourself, so the files keep their owner and the native binary can use the directory again later.

In Compose, set MINA_STATE_DIR to the directory's full path, such as /srv/mina-state, and your UID and GID in .env.

docker logs -f mina follows the log. The node also keeps its rotated log files in the work directory, which a new container keeps and mina report reads. The compose file and the --log-opt options in the docker run commands above limit Docker's own copy of the log to 30 MiB.

To collect a bug report, run mina report in the container. With -it it asks before printing the link to a pre-filled GitHub issue; without a terminal, add --yes. Or save it in the work directory with --output. Then follow reporting a bug.

In the container, ~ is /data: a report saved at ~/bug-reports/ is in ~/mina-state/bug-reports/ on the host.

docker stop mina stops the node, and docker start mina starts it again from its saved chain. So does docker compose up -d when it recreates the container. With --restart unless-stopped, it also starts again after a reboot or a crash, unless you stopped it.

To upgrade, pull the new tag, check its digest as in check the image, and run a new container on the same work directory:

The image checks the node every minute with mina node status --check: healthy means synced, with a recent tip and at least one peer. The first 10 minutes don't count, to leave time to sync. docker ps shows the result. The check asks port 3000 inside the container, so change only the host side of the port.

The compose file starts the node with --allow-worker-control, so you start, stop and price the worker on the dashboard's SNARK worker page. To start the worker with the node instead, add --run-snarker B62q... --snarker-fee FEE to the command, or to MINA_NODE_ARGS. The worker needs no private key. Fees and choosing jobs are on the SNARK worker page.

A producer adds docker-compose.block-producer.yml to the compose file. It mounts the key file read-only at /keys/producer-key, from ./keys/producer-key, outside the work directory, and reads the key's password from producer.env. It also waits 3 s into each won slot before sending the block. See block producer for the key and the producer page.

Put an existing key file at keys/producer-key, readable by you only. Or make a new one in the container:

Save the password, readable by you only. COMPOSE_FILE in .env adds the producer file to every docker compose command. Check that the node can open the key: the wallet address command prints its public key. For rewards to another account, add MINA_NODE_ARGS=--coinbase-receiver B62q... to .env.

Docker Desktop runs the Linux image in a virtual machine. On a Mac with Apple silicon, Docker pulls the ARM64 image, which runs natively; don't force --platform linux/amd64. On an Intel Mac or a Windows PC, it runs the x86-64 image, so the CPU needs BMI2 and ADX, as on Linux.

Give Docker Desktop's virtual machine the memory the requirements list for your role (Settings, Resources). On Windows, run the commands above in a WSL 2 terminal. The dashboard is at http://127.0.0.1:3000, as on Linux.

The image is built from the release archives, not from source. tools/release/docker/build-image.sh builds the same image from the downloaded release, with Docker or Podman. It checks SHA256SUMS.sig against the repository's docs/release/allowed_signers and the archives against SHA256SUMS. Then it builds the image for this machine as ghcr.io/minanode/mina-rust:0.20.0.