Hyperion

All-in-one Docker setup for Hyperion History API with infrastructure services.

Overview

This repository provides a , fully configurable Docker setup that combines:

Hyperion History API - Blockchain history and streaming API
Elasticsearch - Data storage and search
RabbitMQ - Message queue for indexing pipeline
Redis - Caching and rate limiting
Kibana (optional) - Data visualization
Redis Commander (optional) - Redis management UI

All configuration is done via environment variables, making it easy to deploy for different chains and environments.

Quick Start

1. Clone and Initialize

# Clone this repository
git clone <repo-url> hyperion
cd hyperion

# Initialize - automatically clones hyperion-history-api with submodules
./init.sh

The init.sh script will:

Clone hyperion-history-api from GitHub with all submodules
Create .env from template
Initialize git submodules (node-abieos, etc.)

2. Configure

Edit .env to configure your chain and credentials:

# Required: Chain configuration
CHAIN_NAME=wire
CHAIN_DISPLAY_NAME=Wire Network
CHAIN_ID=<your-chain-id>
CHAIN_HTTP_ENDPOINT=https://your-chain-api.com
CHAIN_SHIP_ENDPOINT=ws://your-ship-endpoint:8080

# Required: Change these passwords!
ELASTIC_PASSWORD=your-secure-password
REDIS_PASSWORD=your-secure-password
RABBITMQ_PASSWORD=your-secure-password
KIBANA_PASSWORD=your-secure-password

3. Start Services

./start.sh

The API will be available at http://localhost:7000

Directory Structure

hyperion/
├── Dockerfile                           #  Hyperion container
├── docker-compose.yaml                  # All services definition
├── entrypoint.sh                        # Container entrypoint script
├── .env.template                        # Environment variables template
├── config/
│   ├── connections.template.json        # Connections config template
│   └── chains/
│       └── wire.config.template.json    # Chain config template
├── hyperion-history-api/                # Hyperion source code (clone here)
├── init.sh                              # Initialization script
├── start.sh                             # Start services
├── stop.sh                              # Stop services
├── build.sh                             # Build images
├── logs.sh                              # View logs
└── README.md                            # This file

Configuration Reference

Chain Configuration

Variable	Description	Required
`CHAIN_NAME`	Chain identifier (e.g., `wire`, `eos`)	Yes
`CHAIN_DISPLAY_NAME`	Display name	Yes
`CHAIN_ID`	Chain ID from get_info	Yes
`CHAIN_HTTP_ENDPOINT`	RPC HTTP endpoint	Yes
`CHAIN_SHIP_ENDPOINT`	State History WebSocket	Yes
`CHAIN_CORE_TOKEN`	Core token symbol	No (default: `SYS`)

Infrastructure Credentials

Variable	Description	Required
`ELASTIC_PASSWORD`	Elasticsearch password	Yes
`REDIS_PASSWORD`	Redis password	Yes
`RABBITMQ_PASSWORD`	RabbitMQ password	Yes
`KIBANA_PASSWORD`	Kibana password	No

Indexer Configuration

Variable	Description	Default
`INDEXER_START_BLOCK`	First block to index	`0`
`INDEXER_STOP_BLOCK`	Last block (0 = continuous)	`0`
`INDEXER_LIVE_READER`	Follow live blocks	`true`
`INDEXER_LIVE_ONLY`	Only index live blocks	`false`
`INDEXER_ABI_SCAN_MODE`	ABI-only scanning	`false`
`INDEXER_REWRITE`	Rewrite existing data	`false`
`INDEXER_PURGE_QUEUES`	Clear queues on start	`true`
`INDEXER_FETCH_BLOCK`	Index block data	`true`
`INDEXER_FETCH_TRACES`	Index action traces	`true`
`INDEXER_PROCESS_DELTAS`	Process state deltas	`false`
`INDEXER_NODE_HEAP`	Node.js heap size (MB)	`4096`

API Configuration

Variable	Description	Default
`API_SERVER_PORT`	HTTP API port	`7000`
`API_STREAM_PORT`	WebSocket stream port	`1234`
`API_ENABLE_CACHING`	Enable response caching	`true`
`API_CACHE_LIFE`	Cache TTL (seconds)	`1`
`API_RATE_LIMIT_RPM`	Requests per minute	`1000`
`API_DISABLE_RATE_LIMIT`	Disable rate limiting	`false`
`API_ENABLE_STREAMING`	Enable WebSocket streaming	`true`
`API_PM2_SCALING`	Number of API processes	`1`
`API_NODE_HEAP`	Node.js heap size (MB)	`1024`

Scaling Configuration

Variable	Description	Default
`SCALING_READERS`	State history readers	`1`
`SCALING_DS_QUEUES`	Deserialization queues	`1`
`SCALING_DS_THREADS`	Deserialization threads	`1`
`SCALING_DS_POOL_SIZE`	Deserialization pool	`1`
`SCALING_INDEXING_QUEUES`	Indexing queues	`1`
`SCALING_BATCH_SIZE`	Batch size	`5000`
`SCALING_MAX_AUTOSCALE`	Max autoscale workers	`4`

Memory Limits

Variable	Description	Default
`ES_MEMORY_LIMIT`	Elasticsearch memory	`4G`
`INDEXER_MEMORY_LIMIT`	Indexer container memory	`6G`
`API_MEMORY_LIMIT`	API container memory	`2G`
`KIBANA_MEMORY_LIMIT`	Kibana memory	`4G`

Scripts

init.sh

Initializes the environment and clones hyperion-history-api:

./init.sh                      # Clone and initialize
./init.sh --branch develop     # Use specific branch
./init.sh --force              # Re-clone (removes existing)
./init.sh --skip-clone         # Use existing directory
./init.sh --repo <url>         # Clone from different repo

start.sh

Starts all services:

./start.sh              # Start in background
./start.sh --tools      # Include Kibana and Redis Commander
./start.sh --build      # Force rebuild images
./start.sh -f           # Run in foreground (show logs)

stop.sh

Stops all services:

./stop.sh               # Stop services
./stop.sh -v            # Stop and remove volumes (WARNING: deletes data)

build.sh

Builds Docker images:

./build.sh              # Build images
./build.sh --no-cache   # Build without cache

logs.sh

View service logs:

./logs.sh               # All services
./logs.sh --indexer     # Just indexer
./logs.sh --api         # Just API
./logs.sh --es          # Elasticsearch
./logs.sh --no-follow   # Don't follow (just show recent)
./logs.sh -n 500        # Show last 500 lines

API Endpoints

Once running, the API provides:

Health Check: GET http://localhost:7000/v2/health
Chain Info: GET http://localhost:7000/v1/chain/get_info
Actions: GET http://localhost:7000/v2/history/get_actions
Transaction: GET http://localhost:7000/v2/history/get_transaction
Account: GET http://localhost:7000/v2/state/get_account
API Docs: http://localhost:7000/v2/docs

Optional Tools

Enable with --profile tools:

docker compose --profile tools up -d

Kibana: http://localhost:5601
Redis Commander: http://localhost:8089
RabbitMQ Management: http://localhost:15672

Troubleshooting

Elasticsearch won't start

Increase vm.max_map_count:

sudo sysctl -w vm.max_map_count=262144
echo 'vm.max_map_count=262144' | sudo tee -a /etc/sysctl.conf

Check service health

docker compose ps
docker compose logs --tail=50 <service-name>

Reset everything

./stop.sh -v
./start.sh --build

View indexing progress

./logs.sh --indexer

Custom Chain Configuration

To add a new chain:

Create config template: config/chains/<chain>.config.template.json
Set CHAIN_NAME=<chain> in .env
Configure chain endpoints in .env
Restart services

License

FSL-1.1-Apache-2.0

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
config		config
.env.template		.env.template
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
build.sh		build.sh
docker-compose.bind.yaml		docker-compose.bind.yaml
docker-compose.yaml		docker-compose.yaml
entrypoint.sh		entrypoint.sh
init.sh		init.sh
logs.sh		logs.sh
start.sh		start.sh
stop.sh		stop.sh

Folders and files

Latest commit

History

Repository files navigation

Hyperion

Overview

Quick Start

1. Clone and Initialize

2. Configure

3. Start Services

Directory Structure

Configuration Reference

Chain Configuration

Infrastructure Credentials

Indexer Configuration

API Configuration

Scaling Configuration

Memory Limits

Scripts

init.sh

start.sh

stop.sh

build.sh

logs.sh

API Endpoints

Optional Tools

Troubleshooting

Elasticsearch won't start

Check service health

Reset everything

View indexing progress

Custom Chain Configuration

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages