Appearance

🐳 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 ​

Quick start ​

  1. Set the network you would like to run your node on:

    bash
    export NETWORK=celestia
    export NETWORK=celestia
    bash
    export NETWORK=mocha
    export NETWORK=mocha
    bash
    export NETWORK=arabica
    export NETWORK=arabica

  2. Set the node type

    bash
    export NODE_TYPE=light
    export NODE_TYPE=light
    bash
    export NODE_TYPE=bridge
    export NODE_TYPE=bridge
    bash
    export NODE_TYPE=full
    export NODE_TYPE=full

  3. Set an RPC endpoint for either Mainnet Beta, Mocha, or Arabica using the bare URL (without http or https):

    bash
    export RPC_URL=this-is-an-rpc-url.com
    export RPC_URL=this-is-an-rpc-url.com

  4. Run the image from the command line:

    bash
    docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \
    ghcr.io/celestiaorg/celestia-node:v0.17.2 \
    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.17.2 \
    celestia $NODE_TYPE start --core.ip $RPC_URL --p2p.network $NETWORK
    bash
    docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \
    ghcr.io/celestiaorg/celestia-node:v0.20.1-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.20.1-mocha \
    celestia $NODE_TYPE start --core.ip $RPC_URL --p2p.network $NETWORK
    bash
    docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \
    ghcr.io/celestiaorg/celestia-node:v0.20.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.20.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:

bash
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:

bash
sudo chown 10001:10001 $HOME/my-node-store
sudo chown 10001:10001 $HOME/my-node-store
bash
# 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:

bash
# --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:

bash
docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \
    -v $HOME/my-node-store:/home/celestia \
    ghcr.io/celestiaorg/celestia-node:v0.17.2 \
    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.17.2 \
    celestia light init --p2p.network $NETWORK
bash
docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \
    -v $HOME/my-node-store:/home/celestia \
    ghcr.io/celestiaorg/celestia-node:v0.20.1-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.20.1-mocha \
    celestia light init --p2p.network $NETWORK
bash
docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \
    -v $HOME/my-node-store:/home/celestia \
    ghcr.io/celestiaorg/celestia-node:v0.20.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.20.1-arabica \
    celestia light init --p2p.network $NETWORK

Start the node ​

Run the following command to start the node:

bash
# --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.

bash
docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \
    -v $HOME/my-node-store:/home/celestia \
    ghcr.io/celestiaorg/celestia-node:v0.17.2 \
    celestia light start --core.ip $RPC_URL --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.17.2 \
    celestia light start --core.ip $RPC_URL --p2p.network $NETWORK
bash
docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \
    -v $HOME/my-node-store:/home/celestia \
    ghcr.io/celestiaorg/celestia-node:v0.20.1-mocha \
    celestia light start --core.ip $RPC_URL --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.20.1-mocha \
    celestia light start --core.ip $RPC_URL --p2p.network $NETWORK
bash
docker run -e NODE_TYPE=$NODE_TYPE -e P2P_NETWORK=$NETWORK \
    -v $HOME/my-node-store:/home/celestia \
    ghcr.io/celestiaorg/celestia-node:v0.20.1-arabica \
    celestia light start --core.ip $RPC_URL --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.20.1-arabica \
    celestia light start --core.ip $RPC_URL --p2p.network $NETWORK

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.