Quick start

Quick Start

Get a fully indexed Celestia node running in minutes with Docker Compose.

Prerequisites

• Docker + Docker Compose
• A running Celestia node with RPC, REST, and WebSocket endpoints accessible
• Disk space: ~3 TB for a full mainnet archive
• RAM: 16 GB minimum recommended

1. Clone and configure

git clone https://github.com/celenium-io/celestia-indexer.git
cd celestia-indexer
cp .env.example .env   # if provided, otherwise create .env manually

Edit .env with your node endpoints and database credentials:

# Celestia node endpoints
CELESTIA_NODE_URL=http://your-node:26657
CELESTIA_NODE_API_URL=http://your-node:1317
CELESTIA_NODE_WS_URL=ws://your-node:26657/websocket
CELESTIA_DAL_API_URL=http://your-node:26658

# Database
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_password
POSTGRES_DB=celestia

# Network
NETWORK=celestia   # or mocha / arabica

# Optional: Celestials profile data
CELESTIALS_API_URL=https://celestials.celenium.io
CELENIUM_BLOBS_API_URL=https://api-mainnet.celenium.io

2. Start services

docker-compose up -d --build
# or:
make compose

This starts:

• db — TimescaleDB 15.8 on 127.0.0.1:5432
• cache — Valkey 8.0.2 on 127.0.0.1:6379
• indexer — begins syncing from the Celestia node
• api — public REST API on 127.0.0.1:9876
• private-api — admin API on 127.0.0.1:9877

3. Verify

Check that the API is responding:

curl http://localhost:9876/v1/head

Example response:

{
  "id": 1,
  "hash": "...",
  "height": 2500000,
  "time": "2024-01-15T12:00:00Z",
  "stats": {
    "tx_count": 42,
    "blobs_count": 10,
    "blobs_size": 102400
  }
}

Check sync progress in logs:

docker-compose logs -f indexer

Common Operations

View logs

docker-compose logs -f            # all services
docker-compose logs -f indexer    # indexer only
docker-compose logs -f api        # API only

Stop and restart

docker-compose down
docker-compose up -d

Access the database directly

docker-compose exec db psql -U $POSTGRES_USER -d $POSTGRES_DB

Query examples

# Latest block
curl http://localhost:9876/v1/head

# Block by height
curl http://localhost:9876/v1/block/1000000

# Address info
curl http://localhost:9876/v1/address/celestia1qgjla...

# Recent transactions
curl "http://localhost:9876/v1/tx?limit=10"

# Rollup leaderboard
curl http://localhost:9876/v1/rollup

# Gas price estimate
curl http://localhost:9876/v1/gas/price

Full API reference: api-docs.celenium.io

Troubleshooting

Port conflict

If 5432, 6379, 9876, or 9877 are already in use, override in docker-compose.yml or set different API_PORT, PRIVATE_API_PORT env vars.

Database connection refused

docker-compose ps       # check db container is running
docker-compose logs db  # look for startup errors

Indexer not progressing

docker-compose logs indexer | grep -i error

Common causes:

• Node endpoints unreachable — verify CELESTIA_NODE_URL
• Database not ready — wait for the db container to be healthy
• Chain is pruned — the node does not have the required historical blocks

Out of memory

Reduce POSTGRES_MAX_OPEN_CONNECTIONS and INDEXER_REQUEST_BULK_SIZE. 16 GB RAM is a practical minimum for mainnet.

Development Setup (without Docker)

For running individual components without Docker Compose:

Requirements: Go 1.26.x, PostgreSQL + TimescaleDB extension, Valkey

make init

# Run each service separately
make indexer
make api
make private_api
make celestials

See Development for the full development guide.

Production Recommendations

• Use a managed PostgreSQL/TimescaleDB service (e.g. AWS RDS + TimescaleDB extension, Timescale Cloud)
• Use a managed Valkey/Redis service (e.g. AWS ElastiCache)
• Place a reverse proxy (nginx, Caddy) in front of the API with TLS termination
• Set API_RATE_LIMIT to protect the API from abuse
• Set SENTRY_DSN for error tracking
• Set PROFILER_SERVER for Pyroscope performance profiling
• Monitor via the Prometheus /metrics endpoint (API_PROMETHEUS_ENABLED=true by default)
• Bind services to 127.0.0.1 (default in docker-compose) and expose only through a load balancer