https://github.com/bryanlabs/cosmos-docker
Run thorchain in docker compose
https://github.com/bryanlabs/cosmos-docker
Last synced: 10 months ago
JSON representation
Run thorchain in docker compose
- Host: GitHub
- URL: https://github.com/bryanlabs/cosmos-docker
- Owner: bryanlabs
- License: mit
- Created: 2025-05-24T19:06:40.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-18T19:43:23.000Z (about 1 year ago)
- Last Synced: 2025-09-03T07:15:56.512Z (11 months ago)
- Language: Shell
- Size: 312 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Generic Cosmos Chain Docker
[](https://www.docker.com/)
[](https://docs.docker.com/compose/)
[](https://cosmos.network/)
[](https://opensource.org/licenses/MIT)
[](http://makeapullrequest.com)
Run any Cosmos chain fullnode in Docker Compose.
This Docker Compose setup provides a generic environment for running any Cosmos-based blockchain fullnode with integrated chain management tools and support for 200+ chains from the cosmos/chain-registry.
## 🚀 Quick Start
### Option 1: Use Existing Chain
```bash
# List available chains
make chains
# Set active chain (copies config to .env)
make use CHAIN=kaiyo-1
# Start the node
make start
```
### Option 2: Pull New Chain from Registry
```bash
# Pull chain config from cosmos/chain-registry
make pull CHAIN=osmosis
# Use the new chain
make use CHAIN=osmosis-1
# Start the node
make start
```
### Option 3: Create Custom Chain
```bash
# Create custom chain template
make create CHAIN=my-devnet
# Edit the configuration
nano chains/mainnet/my-devnet.env
# Use the custom chain
make use CHAIN=my-devnet
```
## 📁 Project Structure
```
cosmos-docker/
├── chains/
│ ├── mainnet/ # Production chain configurations
│ │ ├── kaiyo-1.env # Kujira mainnet
│ │ ├── osmosis-1.env # Osmosis mainnet
│ │ └── ...
│ └── testnet/ # Testnet configurations
├── scripts/
│ ├── chain-manager.sh # Chain management tool
│ ├── cr-env # Chain registry integration
│ └── ...
├── docs/
│ └── archive/ # Historical documentation
├── cosmos.yml # Main docker-compose file
├── Makefile # Build and management commands
└── README.md
```
## 🔧 Chain Management
The integrated chain manager supports 200+ chains from the cosmos/chain-registry:
```bash
# Chain Management Commands
make chains # List all available chains
make use CHAIN= # Set active chain
make pull CHAIN= # Pull from chain registry
make create CHAIN= # Create custom chain
make validate CHAIN= # Validate configuration
# Or use the script directly
./scripts/chain-manager.sh help
```
## Supported Chains
This setup works with any Cosmos-based blockchain. Pre-configured chains include:
**Mainnet:**
- **kaiyo-1** - Kujira mainnet
- **cosmoshub-4** - Cosmos Hub mainnet
- **osmosis-1** - Osmosis mainnet
- **phoenix-1** - Terra mainnet
- **noble-1** - Noble mainnet
- **thorchain-1** - THORChain mainnet
**Registry Integration:**
- 200+ chains available via `make pull CHAIN=`
- Automatic configuration from cosmos/chain-registry
- Snapshot auto-detection from Polkachu API
## System Requirements
- **CPU**: 4+ cores (8+ cores recommended for validator nodes)
- **RAM**: 16GB minimum (32GB+ recommended, varies by chain)
- **Storage**: 500GB+ SSD (varies significantly by chain)
- **Network**: Stable internet connection with good bandwidth
- **Docker**: Docker Engine 20.10+ and Docker Compose v2
- **OS**: Linux (Ubuntu 20.04+ recommended), macOS, or Windows with WSL2
## Prerequisites
1. Install Docker and Docker Compose:
```bash
# Ubuntu/Debian
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
# Log out and back in for group changes to take effect
```
2. Verify installation:
```bash
docker --version
docker compose version
```
## Validation
Before deploying, you can validate your setup using the included validation script:
```bash
./validate.sh
```
This script will:
- ✅ Check dependencies (Docker, Docker Compose, Make)
- ✅ Validate YAML syntax and Docker Compose configuration
- ✅ Test environment file formats
- ✅ Verify Makefile targets
- ✅ Check file structure and permissions
- ✅ Test Docker image availability
- ✅ Run basic security checks
## Development Mode
For development and testing, use the enhanced development configuration:
```bash
# Start with development overrides (debug logging, faster health checks)
docker compose -f cosmos.yml -f docker-compose.dev.yml up -d
# Start with development tools (includes utilities like curl, jq, htop)
docker compose -f cosmos.yml -f docker-compose.dev.yml --profile dev-tools up -d
# Start with full monitoring stack (Prometheus + Grafana)
docker compose -f cosmos.yml -f docker-compose.dev.yml --profile monitoring up -d
# Access development tools
docker compose exec dev-tools bash
# Access Grafana dashboard
open http://localhost:3000 # admin/admin
```
See `dev-config/README.md` for detailed development environment documentation.
## Available Make Commands
### Production Commands
- `make start` - Start cosmos node with monitoring
- `make stop` - Stop cosmos node
- `make restart` - Restart cosmos node
- `make logs` - Show cosmos service logs
- `make status` - Show comprehensive node status
- `make monitor` - Run monitoring script
- `make clean` - Remove all containers, volumes, and data
- `make help` - Show all available commands
### Development Commands
- `make dev` - Start with development configuration (debug logging, faster health checks)
- `make dev-tools` - Start with development tools (curl, jq, htop, etc.)
- `make dev-monitor` - Start with monitoring stack (Prometheus + Grafana)
- `make dev-all` - Start with all development features
- `make dev-stop` - Stop development environment
- `make dev-logs` - Show development logs
## Configuration
### Environment Files
This project provides pre-configured environment files for popular Cosmos chains:
1. **`thorchain-1.env`** - THORChain mainnet configuration
2. **`cosmoshub-4.env`** - Cosmos Hub mainnet configuration
3. **`osmosis-1.env`** - Osmosis mainnet configuration
4. **`noble-1.env`** - Noble mainnet configuration
5. **`theta-testnet-001.env`** - Cosmos Hub testnet configuration
### Main Configuration Options
The key settings you'll likely want to customize:
- `NODE_VERSION`: Node version to run (e.g., v18.1.0)
- `NODE_REPO`: Git repository URL for the node source code
- `DAEMON_NAME`: Name of the daemon binary (e.g., gaiad, osmosisd, thornode)
- `MONIKER`: Your node's moniker/name
- `NETWORK`: Chain ID (e.g., cosmoshub-4, osmosis-1)
- `GENESIS_URL`: URL to download the genesis file
- `SEEDS`: Comma-separated list of seed nodes for peer discovery
- `SNAPSHOT`: Optional snapshot URL for faster sync
- `SNAPSHOT_API_URL`: API endpoint to find latest snapshots
- `SNAPSHOT_BASE_URL`: Base URL for downloading snapshots
- `EXTRA_FLAGS`: Additional flags to pass to the daemon binary
- `LOG_LEVEL`: Logging level (info, warn, error, trace)
### Creating Custom Chain Configurations
To add support for a new Cosmos chain:
1. **Copy an existing configuration:**
```bash
cp cosmoshub-4.env mynewchain-1.env
```
2. **Update the key variables:**
```bash
# Edit the new file
nano mynewchain-1.env
# Update these required fields:
NETWORK=mynewchain-1
DAEMON_NAME=newchaind
NODE_VERSION=v1.0.0
NODE_REPO=https://github.com/mynewchain/mynewchain
GENESIS_URL=https://raw.githubusercontent.com/mynewchain/mainnet/genesis.json
SEEDS=your,seed,nodes,here
```
3. **Use your new configuration:**
```bash
cp mynewchain-1.env .env
make start
```
## Ports
The following ports are exposed by default (configurable in .env):
- `26657`: RPC port (Tendermint RPC)
- `26656`: P2P port (for peer connections)
- `9090`: gRPC port
- `9091`: gRPC-Web port
- `1317`: REST API port
- `26660`: Prometheus metrics port
**Note**: THORChain uses custom ports (27147/27146) which are pre-configured in `thorchain-1.env`.
## Data Persistence
### Storage Options
Cosmos blockchain data size varies significantly by chain:
- **Cosmos Hub**: ~500GB+
- **Osmosis**: ~1TB+
- **THORChain**: ~1TB+
- **Noble**: ~100GB+
You have two storage options:
#### Option 1: Docker Volume (Default)
Node data is stored in Docker volumes:
- `cosmos-data`: Blockchain data and configuration
- `cosmos-builds`: Built binaries
This is the default and simplest option. Docker manages the storage location.
#### Option 2: Custom Path (Recommended for Production)
For production deployments or when using a dedicated disk, the default path pattern is `/mnt/data/blockchain/{CHAIN-ID}`:
1. **Prepare your storage location:**
```bash
# Example: Mount a separate disk to /mnt/data
sudo mkdir -p /mnt/data/blockchain
sudo chown $(id -u):$(id -g) /mnt/data/blockchain
```
2. **The DATA_DIR is automatically set to:**
```bash
DATA_DIR=/mnt/data/blockchain/${NETWORK}
```
3. **For custom paths, modify DATA_DIR in your .env file:**
```bash
# Custom path example
DATA_DIR=/my/custom/path/cosmoshub-4
```
#### Typical Production Setup
```bash
# 1. Attach and mount a dedicated SSD
sudo mkfs.ext4 /dev/sdb
sudo mkdir -p /mnt/data
sudo mount /dev/sdb /mnt/data
echo '/dev/sdb /mnt/data ext4 defaults 0 2' | sudo tee -a /etc/fstab
# 2. Prepare cosmos directory (will be created per chain automatically)
sudo mkdir -p /mnt/data/blockchain
sudo chown $(id -u):$(id -g) /mnt/data/blockchain
# 3. Copy chain configuration (DATA_DIR already configured correctly)
cp cosmoshub-4.env .env
# 4. Start the node
make start
```
## Monitoring
Check node status:
```bash
# Service status
docker compose ps
# Node sync status (adjust port for your chain)
curl http://localhost:26657/status # Standard Cosmos
curl http://localhost:27147/status # THORChain
# View logs
docker compose logs cosmos
make logs
```
## Updates
To update to a new version:
1. Update `NODE_VERSION` in `.env`
2. Rebuild and restart:
```bash
docker compose down
docker compose up --build -d
```
## Troubleshooting
### Common Issues
**Node fails to start or crashes:**
```bash
# Check logs for errors
make logs
# Check system resources
docker stats
# Verify Docker has enough resources allocated
```
**Sync is very slow:**
- Ensure you have a fast SSD
- Check your internet connection speed
- Consider using a more recent snapshot
**Port conflicts:**
- Check if ports are already in use: `sudo netstat -tulpn | grep :26657`
- Modify port configuration in `.env` file
**Out of disk space:**
```bash
# Check disk usage
df -h
# Clean up Docker resources
make clean
docker system prune -af
```
**Permission errors:**
```bash
# Fix Docker permissions
sudo usermod -aG docker $USER
# Log out and back in
# Fix data directory permissions (if using custom DATA_DIR)
sudo chown -R $(id -u):$(id -g) /your/data/path
```
**Storage issues:**
```bash
# Check available space
df -h
# For custom data directory (per chain)
du -sh /mnt/data/blockchain/cosmoshub-4
# For Docker volumes
docker system df
```
### Getting Help
- Check logs: `make logs`
- Node status: `make status`
- Monitor health: `make monitor`
- Cosmos Documentation: https://docs.cosmos.network/
- Chain-specific documentation:
- THORChain: https://docs.thorchain.org/
- Osmosis: https://docs.osmosis.zone/
- Noble: https://docs.nobleassets.xyz/
## Chain-Specific Notes
### THORChain
- Uses custom ports (27147/27146)
- Requires specific snapshot format
- High storage requirements (~1TB+)
### Osmosis
- Very high storage requirements (~1TB+)
- Active development with frequent updates
- Rich ecosystem of tools
### Cosmos Hub
- Most stable and well-documented
- Moderate storage requirements (~500GB)
- Good for beginners
### Noble
- Lightweight chain focused on asset issuance
- Lower storage requirements (~100GB)
- Fast sync times
## Support
For chain-specific issues, consult the respective documentation linked above. For issues with this Docker setup, please open an issue in this repository.