🐳 Docker setup
This page has instructions to run celestia-node using Docker. If you are looking for instructions to run celestia-node using a binary, please refer to the celestia-node page.
Using Docker is the easiest way to run celestia-node for most users. Docker is a containerization platform that allows you to run celestia-node in an isolated environment.
This means that you can run celestia-node on your machine without having to worry about installing and configuring all of the dependencies required to run the node.
If you would like to learn more about key management in Docker, visit the Docker and cel-key
section.
The easiest way to install Docker is to use the Docker Desktop installer or Ubuntu. You can follow the instructions for your operating system.
Prerequisites
- Docker Desktop for Mac or Windows and a basic understanding of Docker
- Docker Engine for Linux and a basic understanding of Docker
Quick start
Set the network you would like to run your node on:
bashexport NETWORK=celestia
export NETWORK=celestia
bashexport NETWORK=mocha
export NETWORK=mocha
bashexport NETWORK=arabica
export NETWORK=arabica
Set the node type
bashexport NODE_TYPE=light
export NODE_TYPE=light
bashexport NODE_TYPE=bridge
export NODE_TYPE=bridge
bashexport NODE_TYPE=full
export NODE_TYPE=full
Set an RPC endpoint for either Mainnet Beta, Mocha, or Arabica using the bare URL (without http or https):
bashexport RPC_URL=this-is-an-rpc-url.com
export RPC_URL=this-is-an-rpc-url.com
Run the image from the command line:
bashdocker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \ ghcr.io/celestiaorg/celestia-node:v0.16.0 \ celestia $NODE_TYPE start --core.ip $RPC_URL --p2p.network $NETWORK
docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \ ghcr.io/celestiaorg/celestia-node:v0.16.0 \ celestia $NODE_TYPE start --core.ip $RPC_URL --p2p.network $NETWORK
bashdocker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \ ghcr.io/celestiaorg/celestia-node:v0.18.2-mocha \ celestia $NODE_TYPE start --core.ip $RPC_URL --p2p.network $NETWORK
docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \ ghcr.io/celestiaorg/celestia-node:v0.18.2-mocha \ celestia $NODE_TYPE start --core.ip $RPC_URL --p2p.network $NETWORK
bashdocker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \ ghcr.io/celestiaorg/celestia-node:v0.18.1-arabica \ celestia $NODE_TYPE start --core.ip $RPC_URL --p2p.network $NETWORK
docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \ ghcr.io/celestiaorg/celestia-node:v0.18.1-arabica \ celestia $NODE_TYPE start --core.ip $RPC_URL --p2p.network $NETWORK
Congratulations! You now have a celestia-node running!
If you would like to run the node with custom flags, you can refer to the celestia-node tutorial page. Refer to the ports section of the celestia-node troubleshooting page for information on which ports are required to be open on your machine.
Light node setup with persistent storage
If you delete a container that you started above, all data will be lost. To avoid this, you can mount a volume to the container. This will allow you to persist data even after the container is deleted.
First, you will need to create a directory on your host machine. This directory will be used to store the data for the container. Create a directory on your host machine and give it a name. For example, you can name it my-node-store
:
cd $HOME
mkdir my-node-store
cd $HOME
mkdir my-node-store
Now, you can mount this directory to the container. Before mounting a volume, you may need to set permissions for the user on the host machine by running:
sudo chown 10001:10001 $HOME/my-node-store
sudo chown 10001:10001 $HOME/my-node-store
# you're good to go 😎
# you're good to go 😎
Initialize the node store and key
In order to mount a volume to the container, you need to specify the path to the volume. When you run your container, you can specify the path to the volume using the --volume
(or -v
for short) flag. In this command, we'll create our key and initialize the node store, using the variables we set in the quick start section:
# --volume == -v [local path]:[container path]
docker run [args...] -v $HOME/my-node-store:/home/celestia \
celestia $NODE_TYPE init [args...]
# --volume == -v [local path]:[container path]
docker run [args...] -v $HOME/my-node-store:/home/celestia \
celestia $NODE_TYPE init [args...]
An example init command will look similar to below:
docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \
-v $HOME/my-node-store:/home/celestia \
ghcr.io/celestiaorg/celestia-node:v0.16.0 \
celestia light init --p2p.network $NETWORK
docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \
-v $HOME/my-node-store:/home/celestia \
ghcr.io/celestiaorg/celestia-node:v0.16.0 \
celestia light init --p2p.network $NETWORK
docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \
-v $HOME/my-node-store:/home/celestia \
ghcr.io/celestiaorg/celestia-node:v0.18.2-mocha \
celestia light init --p2p.network $NETWORK
docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \
-v $HOME/my-node-store:/home/celestia \
ghcr.io/celestiaorg/celestia-node:v0.18.2-mocha \
celestia light init --p2p.network $NETWORK
docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \
-v $HOME/my-node-store:/home/celestia \
ghcr.io/celestiaorg/celestia-node:v0.18.1-arabica \
celestia light init --p2p.network $NETWORK
docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \
-v $HOME/my-node-store:/home/celestia \
ghcr.io/celestiaorg/celestia-node:v0.18.1-arabica \
celestia light init --p2p.network $NETWORK
Start the node
Run the following command to start the node:
# --volume == -v [local path]:[container path]
docker run [...args] -v $HOME/my-node-store:/home/celestia \
celestia <node-type> start [...args]
# --volume == -v [local path]:[container path]
docker run [...args] -v $HOME/my-node-store:/home/celestia \
celestia <node-type> start [...args]
A full start command will look similar to below.
docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \
-v $HOME/my-node-store:/home/celestia \
ghcr.io/celestiaorg/celestia-node:v0.16.0 \
celestia light start --core.ip $RPC_URL
docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \
-v $HOME/my-node-store:/home/celestia \
ghcr.io/celestiaorg/celestia-node:v0.16.0 \
celestia light start --core.ip $RPC_URL
docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \
-v $HOME/my-node-store:/home/celestia \
ghcr.io/celestiaorg/celestia-node:v0.18.2-mocha \
celestia light start --core.ip $RPC_URL
docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \
-v $HOME/my-node-store:/home/celestia \
ghcr.io/celestiaorg/celestia-node:v0.18.2-mocha \
celestia light start --core.ip $RPC_URL
docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \
-v $HOME/my-node-store:/home/celestia \
ghcr.io/celestiaorg/celestia-node:v0.18.1-arabica \
celestia light start --core.ip $RPC_URL
docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \
-v $HOME/my-node-store:/home/celestia \
ghcr.io/celestiaorg/celestia-node:v0.18.1-arabica \
celestia light start --core.ip $RPC_URL
Congratulations! You now have a node running with persistent storage.
Video walkthrough
2.5 minute version
Troubleshooting
For security purposes Celestia expects to interact with the your node's keys in a read-only manner. This is enforced using linux style permissions on the filesystem. Windows NTFS does not support these types of permissions. As a result the recommended path for Windows users to mount a persisted volume is to do so within WSL. You can find instructions for installing WSL.