Skip to main content

Deployment Modes

Monolythium supports two primary deployment modes for running validator and RPC nodes. This guide helps you choose the right approach for your use case.

Overview​

ModeBest ForComplexityProduction Ready
Host-NativeProduction validators, bare-metal deploymentsMediumYes
DockerDevelopment, testing, quick prototypesLowYes

Both modes are fully supported and maintained. Your choice depends on operational preferences, infrastructure requirements, and team expertise.

Comparison Table​

AspectHost-NativeDocker
Process Managersystemddocker-compose
Binary Location/usr/local/bin/monodInside container
Data Directory~/.monod/ (host)Volume-mounted from host
Key StorageHost filesystemContainer filesystem (volume-backed)
UpgradesCosmovisor or manualReplace container image
Resource Controlsystemd limitsDocker limits (--memory, --cpus)
Network PortsDirect host bindingDocker port mapping
Loggingjournalctldocker logs + journalctl
Backup/RestoreDirect filesystem accessVolume backup
Toolingmonoctl (Mono Commander)monoctl docker commands
Multi-NodeMultiple systemd unitsdocker-compose scale
PrerequisitesGo 1.24+ (if building)Docker, docker-compose

Decision Tree​

Choose Host-Native If:​

  • You are running a production validator with strict uptime requirements
  • Your infrastructure uses bare-metal servers or VMs without Docker
  • You prefer systemd for process management and logging
  • You need direct control over binary versions and dependencies
  • Your team has experience with Linux system administration
  • You want to use Cosmovisor for automatic upgrades

Choose Docker If:​

  • You are developing or testing Monolythium integrations
  • You want a quick setup without installing system dependencies
  • Your infrastructure is container-based (Kubernetes, ECS, etc.)
  • You prefer declarative configuration via docker-compose
  • You need to run multiple isolated nodes on the same host
  • Your team has Docker expertise
  • You are running on macOS (systemd not available)

Mode-Specific Guides​

Host-Native Deployment​

Full guide: Linux Host-Native Installation

Quick summary:

  1. Install Go 1.24+ or download pre-built binary
  2. Create dedicated monod user (recommended)
  3. Initialize node with monod init
  4. Configure systemd service
  5. Join network using monoctl join
  6. Start service with systemctl start monod

Key commands:

# Using Mono Commander
monoctl monod install
monoctl join --network Sprintnet
monoctl systemd install --user monod

# Manual systemd
sudo systemctl daemon-reload
sudo systemctl enable monod
sudo systemctl start monod

Docker Deployment​

Full guide: Docker Node Deployment

Quick summary:

  1. Install Docker and docker-compose
  2. Initialize Docker setup with monoctl docker init
  3. Configure environment variables and ports
  4. Start node with monoctl docker up
  5. Monitor logs with monoctl docker logs

Key commands:

# Using Mono Commander (Recommended)
monoctl docker init --network Sprintnet
monoctl docker up
monoctl docker status
monoctl docker logs --follow
monoctl docker restart
monoctl docker upgrade --version latest

# Direct docker-compose
docker-compose up -d
docker-compose logs -f monod
macOS Requirement

macOS users must use Docker mode as systemd is not available on macOS. Use the monoctl docker commands for all node operations.

Hybrid Approach​

Some operators run different modes for different purposes:

  • Validator: Host-native for maximum control and performance
  • RPC/Archive Node: Docker for easier scaling and management
  • Development: Docker for rapid iteration and testing

This is a valid strategy that leverages the strengths of each approach.

Migration Between Modes​

Host-Native to Docker​

  1. Stop the host-native service: sudo systemctl stop monod
  2. Back up ~/.monod/ directory
  3. Initialize Docker setup: monoctl docker init --network <NETWORK>
  4. Copy data directory to Docker volume: cp -r ~/.monod/ /var/lib/docker/volumes/monod-data/
  5. Start Docker node: monoctl docker up -d

Docker to Host-Native​

  1. Stop Docker containers: monoctl docker down
  2. Copy data from volume: docker cp monod:/root/.monod ~/.monod
  3. Install monod binary: Installation Guide
  4. Configure systemd service: monoctl systemd install
  5. Start service: sudo systemctl start monod

Performance Considerations​

Host-Native​

  • Pros: Lower overhead, direct system access, fine-grained resource control
  • Cons: Requires more manual configuration, dependency management

Docker​

  • Pros: Isolated environment, consistent across platforms, easy rollback
  • Cons: Small performance overhead (~1-3%), additional abstraction layer

For production validators, host-native is recommended to minimize any potential performance impact. For RPC nodes and development, Docker's convenience often outweighs the minimal overhead.

Security Considerations​

Host-Native​

  • Keys stored in ~/.monod/keyring-backend-*
  • Access controlled via filesystem permissions
  • Requires careful user/group management
  • Direct exposure to host system

Docker​

  • Keys stored in container filesystem (volume-backed)
  • Container isolation provides additional security boundary
  • Easier to implement network segmentation
  • Requires proper volume permission management

Both modes support hardware security modules (HSM) for validator signing keys when configured appropriately.

Next Steps​

Choose your deployment mode and follow the corresponding guide:

  1. Host-Native: Linux Host-Native Installation
  2. Docker: Docker Node Deployment
  3. Tooling: Mono Commander - Works with both modes

After deployment: