From 88c930cbc5ed036edf671614f2cfcba82e6c2502 Mon Sep 17 00:00:00 2001 From: jcstein Date: Fri, 6 Mar 2026 00:22:42 -0700 Subject: [PATCH 1/3] docs: add celestia-app docker setup guide --- app/operate/consensus-validators/_meta.js | 1 + .../consensus-validators/docker/page.mdx | 188 ++++++++++++++++++ .../install-celestia-app/page.mdx | 4 +- app/operate/getting-started/docker/page.mdx | 2 + 4 files changed, 194 insertions(+), 1 deletion(-) create mode 100644 app/operate/consensus-validators/docker/page.mdx diff --git a/app/operate/consensus-validators/_meta.js b/app/operate/consensus-validators/_meta.js index e0ea4102984..a397974a3a3 100644 --- a/app/operate/consensus-validators/_meta.js +++ b/app/operate/consensus-validators/_meta.js @@ -1,5 +1,6 @@ const meta = { "install-celestia-app": "Install celestia-app", + docker: "Docker images", "consensus-node": "Run a consensus node", "validator-node": "Run a validator node", "cli-reference": "CLI commands reference", diff --git a/app/operate/consensus-validators/docker/page.mdx b/app/operate/consensus-validators/docker/page.mdx new file mode 100644 index 00000000000..ec990e8e738 --- /dev/null +++ b/app/operate/consensus-validators/docker/page.mdx @@ -0,0 +1,188 @@ +--- +sidebar_label: Docker images +description: Running celestia-app using Docker images. +--- + +import { Callout, Steps, Tabs } from 'nextra/components' + +# 🐳 Docker setup for celestia-app + +This page has instructions to run `celestia-appd` using Docker images. + +If you are looking for instructions to run `celestia-node` using Docker, refer +to the [celestia-node Docker page](/operate/getting-started/docker). + +## Prerequisites + +- [Docker Desktop for Mac or Windows](https://docs.docker.com/get-docker) +- [Docker Engine for Linux](https://docs.docker.com/engine/install/) +- `curl` and `jq` + +## Quick start with persistent storage + + + +### Set network and version variables + + + + ```bash + export NETWORK=celestia + export CHAIN_ID={{constants['mainnetChainId']}} + export APP_VERSION={{mainnetVersions['app-latest-tag']}} + export NODE_VERSION={{mainnetVersions['node-latest-tag']}} + ``` + + + ```bash + export NETWORK=mocha + export CHAIN_ID={{constants['mochaChainId']}} + export APP_VERSION={{mochaVersions['app-latest-tag']}} + export NODE_VERSION={{mochaVersions['node-latest-tag']}} + ``` + + + ```bash + export NETWORK=arabica + export CHAIN_ID={{constants['arabicaChainId']}} + export APP_VERSION={{arabicaVersions['app-latest-tag']}} + export NODE_VERSION={{arabicaVersions['node-latest-tag']}} + ``` + + + + +If you are block syncing Mainnet Beta from genesis, use +`export APP_VERSION=v3.0.2` as a temporary workaround for +[celestia-app issue #4370](https://github.com/celestiaorg/celestia-app/issues/4370). +After sync completes, upgrade to the latest version. + + +### Create the node home directory + +```bash +mkdir -p $HOME/celestia-app-docker +``` + +Before mounting this directory, Linux users may need to set permissions: + +```bash +sudo chown 10001:10001 $HOME/celestia-app-docker +``` + +### Initialize the node home + +```bash +docker run --rm \ + -v $HOME/celestia-app-docker:/home/celestia/.celestia-app \ + ghcr.io/celestiaorg/celestia-app:$APP_VERSION \ + init "docker-node" --chain-id $CHAIN_ID +``` + +### Download the genesis file + +```bash +docker run --rm \ + -v $HOME/celestia-app-docker:/home/celestia/.celestia-app \ + ghcr.io/celestiaorg/celestia-app:$APP_VERSION \ + download-genesis $CHAIN_ID +``` + +### Configure persistent peers + + + + ```bash + PERSISTENT_PEERS=$(curl -sL https://raw.githubusercontent.com/cosmos/chain-registry/master/{{constants['mainnetChainId']}}/chain.json | jq -r '.peers.persistent_peers[].address' | tr '\n' ',' | sed 's/,$/\n/') + sed -i.bak -e "s/^persistent_peers *=.*/persistent_peers = \"$PERSISTENT_PEERS\"/" $HOME/celestia-app-docker/config/config.toml + ``` + + + ```bash + PERSISTENT_PEERS=$(curl -sL https://raw.githubusercontent.com/celestiaorg/networks/master/{{constants['mochaChainId']}}/peers.txt | tr '\n' ',') + sed -i.bak -e "s/^persistent_peers *=.*/persistent_peers = \"$PERSISTENT_PEERS\"/" $HOME/celestia-app-docker/config/config.toml + ``` + + + ```bash + PERSISTENT_PEERS=$(curl -sL https://raw.githubusercontent.com/celestiaorg/networks/master/{{constants['arabicaChainId']}}/peers.txt | tr '\n' ',') + sed -i.bak -e "s/^persistent_peers *=.*/persistent_peers = \"$PERSISTENT_PEERS\"/" $HOME/celestia-app-docker/config/config.toml + ``` + + + +### Start the container + +```bash +docker run -d \ + --name celestia-app \ + --restart unless-stopped \ + -v $HOME/celestia-app-docker:/home/celestia/.celestia-app \ + -p 26656:26656 \ + -p 26657:26657 \ + -p 9090:9090 \ + ghcr.io/celestiaorg/celestia-app:$APP_VERSION \ + start --home /home/celestia/.celestia-app --rpc.laddr tcp://0.0.0.0:26657 +``` + +### Check node status + +```bash +docker logs -f celestia-app +curl -s http://localhost:26657/status | jq '.result.sync_info' +``` + + + +## Run celestia-node in Docker against your containerized celestia-app + + +If you run a bridge node, make sure your consensus node config follows the +[bridge requirements](/operate/consensus-validators/consensus-node#optional-connect-a-consensus-node-to-a-bridge-node). + + + + +### Create a shared Docker network + +```bash +docker network create celestia-network +``` + +### Recreate celestia-app on the shared network + +```bash +docker stop celestia-app && docker rm celestia-app + +docker run -d \ + --name celestia-app \ + --restart unless-stopped \ + --network celestia-network \ + --network-alias celestia-app \ + -v $HOME/celestia-app-docker:/home/celestia/.celestia-app \ + -p 26656:26656 \ + -p 26657:26657 \ + -p 9090:9090 \ + ghcr.io/celestiaorg/celestia-app:$APP_VERSION \ + start --home /home/celestia/.celestia-app --rpc.laddr tcp://0.0.0.0:26657 +``` + +### Start celestia-node in the same Docker network + +```bash +docker run --rm -it \ + --name celestia-node \ + --network celestia-network \ + -e NODE_TYPE=light \ + -e P2P_NETWORK=$NETWORK \ + ghcr.io/celestiaorg/celestia-node:$NODE_VERSION \ + celestia light start --core.ip celestia-app --core.port 26657 --p2p.network $NETWORK +``` + + + +## Next steps + +- [Consensus node guide](/operate/consensus-validators/consensus-node) +- [Validator node guide](/operate/consensus-validators/validator-node) +- [celestia-node Docker guide](/operate/getting-started/docker) diff --git a/app/operate/consensus-validators/install-celestia-app/page.mdx b/app/operate/consensus-validators/install-celestia-app/page.mdx index 6f84c2da56a..51792d11e2d 100644 --- a/app/operate/consensus-validators/install-celestia-app/page.mdx +++ b/app/operate/consensus-validators/install-celestia-app/page.mdx @@ -8,7 +8,9 @@ import { Steps, Tabs } from 'nextra/components' This tutorial will guide you through installing celestia-app, both [from source](#building-binary-from-source) and with -[a pre-built binary](#installing-a-pre-built-binary) +[a pre-built binary](#installing-a-pre-built-binary). If you are looking for +Docker-based setup instructions, refer to the +[celestia-app Docker page](/operate/consensus-validators/docker). Celestia-app is the software that enables you to run consensus nodes (including validators) and provide RPC endpoints. diff --git a/app/operate/getting-started/docker/page.mdx b/app/operate/getting-started/docker/page.mdx index 9f4320bf1cf..a314ae21751 100644 --- a/app/operate/getting-started/docker/page.mdx +++ b/app/operate/getting-started/docker/page.mdx @@ -10,6 +10,8 @@ import { Steps, Tabs } from 'nextra/components' 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](/operate/data-availability/install-celestia-node). +If you are looking for instructions to run celestia-app in Docker, refer to +the [celestia-app Docker page](/operate/consensus-validators/docker). 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 From afc3190353407d9582e6e18cad3c9e8b3fca4312 Mon Sep 17 00:00:00 2001 From: jcstein <46639943+jcstein@users.noreply.github.com> Date: Thu, 30 Jul 2026 13:14:15 -0600 Subject: [PATCH 2/3] docs: refresh celestia-app Docker guide for current guidance Align with seeds-first P2P setup, gRPC core.port 9090, localhost-bound RPC/gRPC publishes, and cleaner peer list formatting. Co-authored-by: Cursor --- .../consensus-validators/docker/page.mdx | 72 ++++++++++++++++--- 1 file changed, 63 insertions(+), 9 deletions(-) diff --git a/app/operate/consensus-validators/docker/page.mdx b/app/operate/consensus-validators/docker/page.mdx index ec990e8e738..99d24693270 100644 --- a/app/operate/consensus-validators/docker/page.mdx +++ b/app/operate/consensus-validators/docker/page.mdx @@ -88,24 +88,69 @@ docker run --rm \ download-genesis $CHAIN_ID ``` -### Configure persistent peers +### Configure seeds + +Set seeds in `$HOME/celestia-app-docker/config/config.toml`: ```bash - PERSISTENT_PEERS=$(curl -sL https://raw.githubusercontent.com/cosmos/chain-registry/master/{{constants['mainnetChainId']}}/chain.json | jq -r '.peers.persistent_peers[].address' | tr '\n' ',' | sed 's/,$/\n/') + SEEDS=$(curl -sL https://raw.githubusercontent.com/celestiaorg/networks/master/{{constants['mainnetChainId']}}/seeds.txt | tr '\n' ',' | sed 's/,$//') + echo $SEEDS + sed -i.bak -e "s/^seeds *=.*/seeds = \"$SEEDS\"/" $HOME/celestia-app-docker/config/config.toml + ``` + + + ```bash + SEEDS=$(curl -sL https://raw.githubusercontent.com/celestiaorg/networks/master/{{constants['mochaChainId']}}/seeds.txt | tr '\n' ',' | sed 's/,$//') + echo $SEEDS + sed -i.bak -e "s/^seeds *=.*/seeds = \"$SEEDS\"/" $HOME/celestia-app-docker/config/config.toml + ``` + + + ```bash + # For Arabica, you can set seeds manually in the + # `$HOME/celestia-app-docker/config/config.toml` file: + # Comma separated list of seed nodes to connect to + seeds = "" + ``` + + + +### Optional: Configure persistent peers + + +If you set persistent peers, your node will **always** try to connect to these +peers. This is useful for a local devnet. In production, setting persistent +peers is advised only if you are running a +[sentry node](https://hub.cosmos.network/main/validators/security.html#sentry-nodes-ddos-protection). + + +You can get persistent peers from the +[@cosmos/chain-registry](https://github.com/cosmos/chain-registry) repository +(for Mainnet Beta) or +[@celestiaorg/networks](https://github.com/celestiaorg/networks) repository +(for Mocha and Arabica): + + + + ```bash + PERSISTENT_PEERS=$(curl -sL https://raw.githubusercontent.com/cosmos/chain-registry/master/{{constants['mainnetChainId']}}/chain.json | jq -r '.peers.persistent_peers[].address' | tr '\n' ',' | sed 's/,$//') + echo $PERSISTENT_PEERS sed -i.bak -e "s/^persistent_peers *=.*/persistent_peers = \"$PERSISTENT_PEERS\"/" $HOME/celestia-app-docker/config/config.toml ``` ```bash - PERSISTENT_PEERS=$(curl -sL https://raw.githubusercontent.com/celestiaorg/networks/master/{{constants['mochaChainId']}}/peers.txt | tr '\n' ',') + PERSISTENT_PEERS=$(curl -sL https://raw.githubusercontent.com/celestiaorg/networks/master/{{constants['mochaChainId']}}/peers.txt | tr '\n' ',' | sed 's/,$//') + echo $PERSISTENT_PEERS sed -i.bak -e "s/^persistent_peers *=.*/persistent_peers = \"$PERSISTENT_PEERS\"/" $HOME/celestia-app-docker/config/config.toml ``` ```bash - PERSISTENT_PEERS=$(curl -sL https://raw.githubusercontent.com/celestiaorg/networks/master/{{constants['arabicaChainId']}}/peers.txt | tr '\n' ',') + PERSISTENT_PEERS=$(curl -sL https://raw.githubusercontent.com/celestiaorg/networks/master/{{constants['arabicaChainId']}}/peers.txt | tr '\n' ',' | sed 's/,$//') + echo $PERSISTENT_PEERS sed -i.bak -e "s/^persistent_peers *=.*/persistent_peers = \"$PERSISTENT_PEERS\"/" $HOME/celestia-app-docker/config/config.toml ``` @@ -113,14 +158,20 @@ docker run --rm \ ### Start the container + +RPC (`26657`) and gRPC (`9090`) are published to localhost only in this +example. Do not publish these ports on all interfaces on a public host unless +you intend to expose them. P2P (`26656`) is published for peer connectivity. + + ```bash docker run -d \ --name celestia-app \ --restart unless-stopped \ -v $HOME/celestia-app-docker:/home/celestia/.celestia-app \ -p 26656:26656 \ - -p 26657:26657 \ - -p 9090:9090 \ + -p 127.0.0.1:26657:26657 \ + -p 127.0.0.1:9090:9090 \ ghcr.io/celestiaorg/celestia-app:$APP_VERSION \ start --home /home/celestia/.celestia-app --rpc.laddr tcp://0.0.0.0:26657 ``` @@ -136,6 +187,9 @@ curl -s http://localhost:26657/status | jq '.result.sync_info' ## Run celestia-node in Docker against your containerized celestia-app +celestia-node connects to consensus over gRPC (`--core.port`, default `9090`), +not Tendermint RPC. + If you run a bridge node, make sure your consensus node config follows the [bridge requirements](/operate/consensus-validators/consensus-node#optional-connect-a-consensus-node-to-a-bridge-node). @@ -161,8 +215,8 @@ docker run -d \ --network-alias celestia-app \ -v $HOME/celestia-app-docker:/home/celestia/.celestia-app \ -p 26656:26656 \ - -p 26657:26657 \ - -p 9090:9090 \ + -p 127.0.0.1:26657:26657 \ + -p 127.0.0.1:9090:9090 \ ghcr.io/celestiaorg/celestia-app:$APP_VERSION \ start --home /home/celestia/.celestia-app --rpc.laddr tcp://0.0.0.0:26657 ``` @@ -176,7 +230,7 @@ docker run --rm -it \ -e NODE_TYPE=light \ -e P2P_NETWORK=$NETWORK \ ghcr.io/celestiaorg/celestia-node:$NODE_VERSION \ - celestia light start --core.ip celestia-app --core.port 26657 --p2p.network $NETWORK + celestia light start --core.ip celestia-app --core.port 9090 --p2p.network $NETWORK ``` From 82f6b1cd52de218c1df8da9260697dd8d35f2830 Mon Sep 17 00:00:00 2001 From: jcstein <46639943+jcstein@users.noreply.github.com> Date: Thu, 30 Jul 2026 13:22:57 -0600 Subject: [PATCH 3/3] docs: omit host RPC/gRPC ports in shared Docker network example celestia-node reaches celestia-app over the Docker network on gRPC 9090, so publishing those ports to the host is unnecessary exposure. Co-authored-by: Cursor --- app/operate/consensus-validators/docker/page.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/app/operate/consensus-validators/docker/page.mdx b/app/operate/consensus-validators/docker/page.mdx index 99d24693270..cc2db1c2e1d 100644 --- a/app/operate/consensus-validators/docker/page.mdx +++ b/app/operate/consensus-validators/docker/page.mdx @@ -205,6 +205,10 @@ docker network create celestia-network ### Recreate celestia-app on the shared network +RPC and gRPC are not published to the host here. `celestia-node` reaches +`celestia-app` over the Docker network on gRPC port `9090`. Only P2P +(`26656`) is published for peer connectivity. + ```bash docker stop celestia-app && docker rm celestia-app @@ -215,8 +219,6 @@ docker run -d \ --network-alias celestia-app \ -v $HOME/celestia-app-docker:/home/celestia/.celestia-app \ -p 26656:26656 \ - -p 127.0.0.1:26657:26657 \ - -p 127.0.0.1:9090:9090 \ ghcr.io/celestiaorg/celestia-app:$APP_VERSION \ start --home /home/celestia/.celestia-app --rpc.laddr tcp://0.0.0.0:26657 ```