{"id":30715935,"url":"https://github.com/bryanlabs/cosmos-docker","last_synced_at":"2025-10-09T12:09:48.350Z","repository":{"id":295347926,"uuid":"989757934","full_name":"bryanlabs/cosmos-docker","owner":"bryanlabs","description":"Run thorchain in docker compose","archived":false,"fork":false,"pushed_at":"2025-06-18T19:43:23.000Z","size":319,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-03T07:15:56.512Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bryanlabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-24T19:06:40.000Z","updated_at":"2025-06-18T19:43:26.000Z","dependencies_parsed_at":"2025-05-25T03:28:41.868Z","dependency_job_id":"66872d37-6adf-4e31-a38d-004340976dbe","html_url":"https://github.com/bryanlabs/cosmos-docker","commit_stats":null,"previous_names":["bryanlabs/thorchain-docker","bryanlabs/cosmos-docker"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bryanlabs/cosmos-docker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bryanlabs%2Fcosmos-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bryanlabs%2Fcosmos-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bryanlabs%2Fcosmos-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bryanlabs%2Fcosmos-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bryanlabs","download_url":"https://codeload.github.com/bryanlabs/cosmos-docker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bryanlabs%2Fcosmos-docker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279001439,"owners_count":26083078,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-03T07:10:02.103Z","updated_at":"2025-10-09T12:09:48.299Z","avatar_url":"https://github.com/bryanlabs.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Generic Cosmos Chain Docker\n\n[![Docker](https://img.shields.io/badge/Docker-2496ED?style=flat-square\u0026logo=docker\u0026logoColor=white)](https://www.docker.com/)\n[![Docker Compose](https://img.shields.io/badge/Docker%20Compose-2496ED?style=flat-square\u0026logo=docker\u0026logoColor=white)](https://docs.docker.com/compose/)\n[![Cosmos](https://img.shields.io/badge/Cosmos-2E3148?style=flat-square\u0026logo=cosmos\u0026logoColor=white)](https://cosmos.network/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)\n\nRun any Cosmos chain fullnode in Docker Compose.\n\nThis 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.\n\n## 🚀 Quick Start\n\n### Option 1: Use Existing Chain\n```bash\n# List available chains\nmake chains\n\n# Set active chain (copies config to .env)\nmake use CHAIN=kaiyo-1\n\n# Start the node\nmake start\n```\n\n### Option 2: Pull New Chain from Registry\n```bash\n# Pull chain config from cosmos/chain-registry\nmake pull CHAIN=osmosis\n\n# Use the new chain\nmake use CHAIN=osmosis-1\n\n# Start the node\nmake start\n```\n\n### Option 3: Create Custom Chain\n```bash\n# Create custom chain template\nmake create CHAIN=my-devnet\n\n# Edit the configuration\nnano chains/mainnet/my-devnet.env\n\n# Use the custom chain\nmake use CHAIN=my-devnet\n```\n\n## 📁 Project Structure\n\n```\ncosmos-docker/\n├── chains/\n│   ├── mainnet/          # Production chain configurations\n│   │   ├── kaiyo-1.env   # Kujira mainnet\n│   │   ├── osmosis-1.env # Osmosis mainnet\n│   │   └── ...\n│   └── testnet/          # Testnet configurations\n├── scripts/\n│   ├── chain-manager.sh  # Chain management tool\n│   ├── cr-env           # Chain registry integration\n│   └── ...\n├── docs/\n│   └── archive/         # Historical documentation\n├── cosmos.yml           # Main docker-compose file\n├── Makefile            # Build and management commands\n└── README.md\n```\n\n## 🔧 Chain Management\n\nThe integrated chain manager supports 200+ chains from the cosmos/chain-registry:\n\n```bash\n# Chain Management Commands\nmake chains              # List all available chains\nmake use CHAIN=\u003cid\u003e      # Set active chain\nmake pull CHAIN=\u003cname\u003e   # Pull from chain registry\nmake create CHAIN=\u003cid\u003e   # Create custom chain\nmake validate CHAIN=\u003cid\u003e # Validate configuration\n\n# Or use the script directly\n./scripts/chain-manager.sh help\n```\n\n## Supported Chains\n\nThis setup works with any Cosmos-based blockchain. Pre-configured chains include:\n\n**Mainnet:**\n- **kaiyo-1** - Kujira mainnet\n- **cosmoshub-4** - Cosmos Hub mainnet  \n- **osmosis-1** - Osmosis mainnet\n- **phoenix-1** - Terra mainnet\n- **noble-1** - Noble mainnet\n- **thorchain-1** - THORChain mainnet\n\n**Registry Integration:**\n- 200+ chains available via `make pull CHAIN=\u003cname\u003e`\n- Automatic configuration from cosmos/chain-registry\n- Snapshot auto-detection from Polkachu API\n\n## System Requirements\n\n- **CPU**: 4+ cores (8+ cores recommended for validator nodes)\n- **RAM**: 16GB minimum (32GB+ recommended, varies by chain)\n- **Storage**: 500GB+ SSD (varies significantly by chain)\n- **Network**: Stable internet connection with good bandwidth\n- **Docker**: Docker Engine 20.10+ and Docker Compose v2\n- **OS**: Linux (Ubuntu 20.04+ recommended), macOS, or Windows with WSL2\n\n## Prerequisites\n\n1. Install Docker and Docker Compose:\n```bash\n# Ubuntu/Debian\ncurl -fsSL https://get.docker.com -o get-docker.sh\nsudo sh get-docker.sh\nsudo usermod -aG docker $USER\n\n# Log out and back in for group changes to take effect\n```\n\n2. Verify installation:\n```bash\ndocker --version\ndocker compose version\n```\n\n## Validation\n\nBefore deploying, you can validate your setup using the included validation script:\n\n```bash\n./validate.sh\n```\n\nThis script will:\n- ✅ Check dependencies (Docker, Docker Compose, Make)\n- ✅ Validate YAML syntax and Docker Compose configuration\n- ✅ Test environment file formats\n- ✅ Verify Makefile targets\n- ✅ Check file structure and permissions\n- ✅ Test Docker image availability\n- ✅ Run basic security checks\n\n## Development Mode\n\nFor development and testing, use the enhanced development configuration:\n\n```bash\n# Start with development overrides (debug logging, faster health checks)\ndocker compose -f cosmos.yml -f docker-compose.dev.yml up -d\n\n# Start with development tools (includes utilities like curl, jq, htop)\ndocker compose -f cosmos.yml -f docker-compose.dev.yml --profile dev-tools up -d\n\n# Start with full monitoring stack (Prometheus + Grafana)\ndocker compose -f cosmos.yml -f docker-compose.dev.yml --profile monitoring up -d\n\n# Access development tools\ndocker compose exec dev-tools bash\n\n# Access Grafana dashboard\nopen http://localhost:3000  # admin/admin\n```\n\nSee `dev-config/README.md` for detailed development environment documentation.\n\n## Available Make Commands\n\n### Production Commands\n- `make start` - Start cosmos node with monitoring\n- `make stop` - Stop cosmos node  \n- `make restart` - Restart cosmos node\n- `make logs` - Show cosmos service logs\n- `make status` - Show comprehensive node status\n- `make monitor` - Run monitoring script\n- `make clean` - Remove all containers, volumes, and data\n- `make help` - Show all available commands\n\n### Development Commands\n- `make dev` - Start with development configuration (debug logging, faster health checks)\n- `make dev-tools` - Start with development tools (curl, jq, htop, etc.)\n- `make dev-monitor` - Start with monitoring stack (Prometheus + Grafana)\n- `make dev-all` - Start with all development features\n- `make dev-stop` - Stop development environment\n- `make dev-logs` - Show development logs\n\n## Configuration\n\n### Environment Files\n\nThis project provides pre-configured environment files for popular Cosmos chains:\n\n1. **`thorchain-1.env`** - THORChain mainnet configuration\n2. **`cosmoshub-4.env`** - Cosmos Hub mainnet configuration  \n3. **`osmosis-1.env`** - Osmosis mainnet configuration\n4. **`noble-1.env`** - Noble mainnet configuration\n5. **`theta-testnet-001.env`** - Cosmos Hub testnet configuration\n\n### Main Configuration Options\n\nThe key settings you'll likely want to customize:\n\n- `NODE_VERSION`: Node version to run (e.g., v18.1.0)\n- `NODE_REPO`: Git repository URL for the node source code\n- `DAEMON_NAME`: Name of the daemon binary (e.g., gaiad, osmosisd, thornode)\n- `MONIKER`: Your node's moniker/name\n- `NETWORK`: Chain ID (e.g., cosmoshub-4, osmosis-1)\n- `GENESIS_URL`: URL to download the genesis file\n- `SEEDS`: Comma-separated list of seed nodes for peer discovery\n- `SNAPSHOT`: Optional snapshot URL for faster sync\n- `SNAPSHOT_API_URL`: API endpoint to find latest snapshots\n- `SNAPSHOT_BASE_URL`: Base URL for downloading snapshots\n- `EXTRA_FLAGS`: Additional flags to pass to the daemon binary\n- `LOG_LEVEL`: Logging level (info, warn, error, trace)\n\n### Creating Custom Chain Configurations\n\nTo add support for a new Cosmos chain:\n\n1. **Copy an existing configuration:**\n```bash\ncp cosmoshub-4.env mynewchain-1.env\n```\n\n2. **Update the key variables:**\n```bash\n# Edit the new file\nnano mynewchain-1.env\n\n# Update these required fields:\nNETWORK=mynewchain-1\nDAEMON_NAME=newchaind\nNODE_VERSION=v1.0.0\nNODE_REPO=https://github.com/mynewchain/mynewchain\nGENESIS_URL=https://raw.githubusercontent.com/mynewchain/mainnet/genesis.json\nSEEDS=your,seed,nodes,here\n```\n\n3. **Use your new configuration:**\n```bash\ncp mynewchain-1.env .env\nmake start\n```\n\n## Ports\n\nThe following ports are exposed by default (configurable in .env):\n\n- `26657`: RPC port (Tendermint RPC)\n- `26656`: P2P port (for peer connections)\n- `9090`: gRPC port\n- `9091`: gRPC-Web port\n- `1317`: REST API port\n- `26660`: Prometheus metrics port\n\n**Note**: THORChain uses custom ports (27147/27146) which are pre-configured in `thorchain-1.env`.\n\n## Data Persistence\n\n### Storage Options\n\nCosmos blockchain data size varies significantly by chain:\n- **Cosmos Hub**: ~500GB+\n- **Osmosis**: ~1TB+  \n- **THORChain**: ~1TB+\n- **Noble**: ~100GB+\n\nYou have two storage options:\n\n#### Option 1: Docker Volume (Default)\nNode data is stored in Docker volumes:\n- `cosmos-data`: Blockchain data and configuration  \n- `cosmos-builds`: Built binaries\n\nThis is the default and simplest option. Docker manages the storage location.\n\n#### Option 2: Custom Path (Recommended for Production)\nFor production deployments or when using a dedicated disk, the default path pattern is `/mnt/data/blockchain/{CHAIN-ID}`:\n\n1. **Prepare your storage location:**\n```bash\n# Example: Mount a separate disk to /mnt/data\nsudo mkdir -p /mnt/data/blockchain\nsudo chown $(id -u):$(id -g) /mnt/data/blockchain\n```\n\n2. **The DATA_DIR is automatically set to:**\n```bash\nDATA_DIR=/mnt/data/blockchain/${NETWORK}\n```\n\n3. **For custom paths, modify DATA_DIR in your .env file:**\n```bash\n# Custom path example\nDATA_DIR=/my/custom/path/cosmoshub-4\n```\n\n#### Typical Production Setup\n```bash\n# 1. Attach and mount a dedicated SSD\nsudo mkfs.ext4 /dev/sdb\nsudo mkdir -p /mnt/data\nsudo mount /dev/sdb /mnt/data\necho '/dev/sdb /mnt/data ext4 defaults 0 2' | sudo tee -a /etc/fstab\n\n# 2. Prepare cosmos directory (will be created per chain automatically)\nsudo mkdir -p /mnt/data/blockchain\nsudo chown $(id -u):$(id -g) /mnt/data/blockchain\n\n# 3. Copy chain configuration (DATA_DIR already configured correctly)\ncp cosmoshub-4.env .env\n\n# 4. Start the node\nmake start\n```\n\n## Monitoring\n\nCheck node status:\n```bash\n# Service status\ndocker compose ps\n\n# Node sync status (adjust port for your chain)\ncurl http://localhost:26657/status  # Standard Cosmos\ncurl http://localhost:27147/status  # THORChain\n\n# View logs\ndocker compose logs cosmos\nmake logs\n```\n\n## Updates\n\nTo update to a new version:\n\n1. Update `NODE_VERSION` in `.env`\n2. Rebuild and restart:\n```bash\ndocker compose down\ndocker compose up --build -d\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**Node fails to start or crashes:**\n```bash\n# Check logs for errors\nmake logs\n\n# Check system resources\ndocker stats\n\n# Verify Docker has enough resources allocated\n```\n\n**Sync is very slow:**\n- Ensure you have a fast SSD\n- Check your internet connection speed\n- Consider using a more recent snapshot\n\n**Port conflicts:**\n- Check if ports are already in use: `sudo netstat -tulpn | grep :26657`\n- Modify port configuration in `.env` file\n\n**Out of disk space:**\n```bash\n# Check disk usage\ndf -h\n\n# Clean up Docker resources\nmake clean\ndocker system prune -af\n```\n\n**Permission errors:**\n```bash\n# Fix Docker permissions\nsudo usermod -aG docker $USER\n# Log out and back in\n\n# Fix data directory permissions (if using custom DATA_DIR)\nsudo chown -R $(id -u):$(id -g) /your/data/path\n```\n\n**Storage issues:**\n```bash\n# Check available space\ndf -h\n\n# For custom data directory (per chain)\ndu -sh /mnt/data/blockchain/cosmoshub-4\n\n# For Docker volumes\ndocker system df\n```\n\n### Getting Help\n\n- Check logs: `make logs`\n- Node status: `make status`\n- Monitor health: `make monitor`\n- Cosmos Documentation: https://docs.cosmos.network/\n- Chain-specific documentation:\n  - THORChain: https://docs.thorchain.org/\n  - Osmosis: https://docs.osmosis.zone/\n  - Noble: https://docs.nobleassets.xyz/\n\n## Chain-Specific Notes\n\n### THORChain\n- Uses custom ports (27147/27146)\n- Requires specific snapshot format\n- High storage requirements (~1TB+)\n\n### Osmosis  \n- Very high storage requirements (~1TB+)\n- Active development with frequent updates\n- Rich ecosystem of tools\n\n### Cosmos Hub\n- Most stable and well-documented\n- Moderate storage requirements (~500GB)\n- Good for beginners\n\n### Noble\n- Lightweight chain focused on asset issuance\n- Lower storage requirements (~100GB)\n- Fast sync times\n\n## Support\n\nFor chain-specific issues, consult the respective documentation linked above. For issues with this Docker setup, please open an issue in this repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbryanlabs%2Fcosmos-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbryanlabs%2Fcosmos-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbryanlabs%2Fcosmos-docker/lists"}