EVVM Docker

Containerized environment for deploying and managing EVVM Testnet Contracts without installing dependencies locally.

Deploy virtual EVM chains on testnets using Docker - no need to install Foundry, Bun, or manage dependencies manually. This repository provides a complete Docker environment with all tools pre-configured and ready to use.

What's Included

Docker Image with Foundry (forge, cast, anvil, chisel) and Bun pre-installed
Auto-cloning of the EVVM Testnet Contracts repository
EVVM CLI pre-configured and ready to use
Complete documentation with examples and guides
Make targets for common operations (optional)
Secure wallet management using Foundry's encrypted keystores
All project dependencies pre-installed

Quick Start

1. Clone or Download

git clone https://github.com/EVVM-org/evvm-docker
cd evvm-docker

Or download and extract the files manually.

2. Configure Environment

Create your .env file from the example:

cp .env.example .env
# Edit .env with your RPC URLs and API keys
nano .env

3. Build Docker Image

docker compose build

Or using Make:

make build

4. Import Your Wallet

# Start interactive session
docker compose run --rm --entrypoint /bin/bash evvm-cli

# Inside container, import your wallet
cast wallet import defaultKey --interactive
# Enter your private key when prompted
exit

5. Deploy EVVM

# Using docker compose
docker compose run --rm evvm-cli deploy

# Or using Make
make deploy

File Structure

evvm-docker/
├── 📄 README.md              # This file
├── 📄 QUICKSTART.md          # Quick start guide
├── 🐳 Dockerfile             # Docker image definition
├── 🐳 compose.yml            # Docker Compose configuration
├── 📝 .env.example           # Environment variables template
├── 🔧 Makefile               # Make commands (optional)
├── 📄 LICENSE                # MIT License
├── 🙈 .dockerignore          # Docker build exclusions
└── 🙈 .gitignore             # Git exclusions

Use Cases

Perfect for:

Testing EVVM without installing Foundry/Bun locally
CI/CD pipelines requiring consistent environments
Team development with standardized tooling
Windows users wanting easy access to Foundry tools
Quick deployments on any platform with Docker

Prerequisites

Docker (20.10+)
Docker Compose (2.0+)
At least 4GB of free disk space

Working with Wallets

Option 1: Import wallet inside container (Persistent)

Wallets are automatically persisted in a Docker volume, so you only need to import once:

# Start interactive session (only needed once for import)
docker compose run --rm --entrypoint /bin/bash evvm-cli

# Inside container, import your wallet
cast wallet import defaultKey --interactive
# Enter your private key when prompted

# Then run CLI commands
bun run cli/index.ts deploy
exit

Note: Your wallet will persist across container runs thanks to the foundry-keystores volume.

Option 2: Share Foundry keystore from host (Recommended for persistence)

Note: By default, wallets are now persisted in a Docker volume named foundry-keystores. They will be available across all container runs.

If you want to share wallets with your host machine instead, uncomment the alternative volume mount in compose.yml:

volumes:
  # Comment out the volume mount
  # - foundry-keystores:/root/.foundry/keystores
  
  # Uncomment the host mount
  - ~/.foundry/keystores:/root/.foundry/keystores:ro

Then import wallet on your host machine:

cast wallet import defaultKey --interactive

Your wallet will now be available in all container runs from both host and containers.

Environment Variables

Required variables in .env:

# For single-chain deployment
RPC_URL="https://your-rpc-url"

# For cross-chain deployment
EXTERNAL_RPC_URL="https://external-chain-rpc"
HOST_RPC_URL="https://host-chain-rpc"

# For registration
EVVM_REGISTRATION_RPC_URL="https://sepolia-rpc-url"

# For contract verification
ETHERSCAN_API="your_api_key"

See .env.example for all available options.

Available Commands

Using Docker Compose (Recommended)

docker compose run --rm evvm-cli help                       # Show CLI help
docker compose run --rm evvm-cli version                    # Display version
docker compose run --rm evvm-cli deploy                     # Deploy EVVM
docker compose run --rm evvm-cli register                   # Register EVVM
docker compose run --rm evvm-cli setUpCrossChainTreasuries  # Setup cross-chain
docker compose run --rm evvm-cli dev                        # Developer utilities
docker compose run --rm evvm-cli install                    # Install dependencies
docker compose run --rm --entrypoint /bin/bash evvm-cli     # Interactive shell

Using Make (Optional)

make help          # Show all available commands
make build         # Build Docker image
make deploy        # Deploy EVVM
make register      # Register EVVM
make shell         # Interactive shell
make version       # Show version
make stop          # Stop containers (keep data)
make clean-image   # Remove image only (keep wallets/data)
make clean         # Remove everything (images + wallets + data)
make clean-wallets # Remove only saved wallets

Examples

Deploy EVVM on a single chain

# 1. Configure .env
echo 'RPC_URL="https://sepolia-rollup.arbitrum.io/rpc"' > .env

# 2. Run deployment
docker compose run --rm evvm-cli deploy

Deploy cross-chain EVVM

# 1. Configure .env
cat > .env << EOF
EXTERNAL_RPC_URL="https://sepolia-rollup.arbitrum.io/rpc"
HOST_RPC_URL="https://0xrpc.io/sep"
EOF

# 2. Run deployment
docker compose run --rm evvm-cli deploy

Register EVVM in the registry

# 1. Ensure you have deployed first
# 2. Configure registration RPC
echo 'EVVM_REGISTRATION_RPC_URL="https://gateway.tenderly.co/public/sepolia"' >> .env

# 3. Run registration
docker compose run --rm evvm-cli register

Run Foundry commands

# Compile contracts
docker compose run --rm evvm-cli forge build

# Run tests
docker compose run --rm evvm-cli forge test

# Start local testnet (Anvil)
docker compose run --rm -p 8545:8545 evvm-cli anvil --host 0.0.0.0

# Use cast to check block number
docker compose run --rm evvm-cli cast block-number --rpc-url https://eth.llamarpc.com

Persisting Data

Deployment outputs

Deployment results are saved to output/ directory which is mounted as a volume. This ensures your deployment data persists across container runs.

# View deployment results
ls output/evvmDeployment.json

Wallet keystores

If you import a wallet inside the container without mounting the keystore directory, it will be lost when the container is removed. Use Option 2 in the Working with Wallets section to persist wallets.

Advanced Usage

Run specific Foundry commands

# Run forge tests
docker compose run --rm evvm-cli forge test

# Run anvil (local testnet)
docker compose run --rm -p 8545:8545 evvm-cli anvil --host 0.0.0.0

# Use cast
docker compose run --rm evvm-cli cast block-number --rpc-url https://eth.llamarpc.com

Development mode

For development with live code changes, mount the source directory:

Edit compose.yml:

volumes:
  - ../:/workspace

Then rebuild inside container:

docker compose run --rm --entrypoint /bin/bash evvm-cli
bun install
forge build

Troubleshooting

Stop containers and remove everything

To pause or completely remove the Docker setup:

# Just stop running containers (data persists)
docker compose stop
# Or
make stop

# Stop and remove containers (volumes/data persist)
docker compose down

# Remove image but keep wallets and data
docker compose down --rmi all
# Or
make clean-image

# Complete cleanup: remove containers, images, volumes, and all data
docker compose down --rmi all --volumes --remove-orphans
# Or
make clean

Cleanup comparison:

Action	Command	Image	Wallets	Outputs	Containers
Stop	`make stop`	✅ Keep	✅ Keep	✅ Keep	⏸️ Stop
Clean wallets	`make clean-wallets`	✅ Keep	❌ Remove	✅ Keep	🗑️ Remove
Clean image	`make clean-image`	❌ Remove	✅ Keep	✅ Keep	🗑️ Remove
Clean all	`make clean`	❌ Remove	❌ Remove	❌ Remove	🗑️ Remove

To verify everything is removed:

# Check images
docker images | grep evvm

# Check volumes  
docker volume ls | grep evvm-docker

# Check containers
docker ps -a | grep evvm

Remove wallets and start fresh

If you need to delete imported wallets:

# Remove the wallet volume
docker volume rm evvm-docker_foundry-keystores

# Or remove all data (wallets + outputs)
docker compose down --volumes

Then reimport your wallet as described in Working with Wallets.

Docker not running

# Linux
sudo systemctl start docker

# macOS
open -a Docker

# Windows
# Start Docker Desktop from Start menu

Permission issues

If you encounter permission errors with mounted volumes:

# On Linux, ensure proper permissions
chmod 644 .env
chmod -R 755 output/

# Linux - add user to docker group
sudo usermod -aG docker $USER
# Log out and back in

Network connectivity

If RPC URLs are not accessible:

# Test from host
curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  YOUR_RPC_URL

Use network_mode: host in compose.yml if accessing local nodes

Update repository

The repository is cloned during build. To update:

# Rebuild the image without cache
docker compose down --rmi all --volumes
docker compose build --no-cache

Or manually inside container:

docker compose run --rm --entrypoint /bin/bash evvm-cli
git pull origin main
git submodule update --init --recursive
bun install
forge install

Security

Important Security Practices:

Never commit .env files - Keep your RPC URLs and API keys secret
Never store private keys in .env - Use Foundry's encrypted keystore
Use read-only mounts (:ro) for sensitive files when possible
Be cautious with volume mounts - Only mount necessary directories
Review the Dockerfile before building to understand what's installed
Keep Docker images updated - Rebuild periodically for security patches

Security

Important Security Practices:

Never commit .env files - Keep your RPC URLs and API keys secret
Never store private keys in .env - Use Foundry's encrypted keystore
Use read-only mounts (:ro) for sensitive files when possible
Be cautious with volume mounts - Only mount necessary directories
Review the Dockerfile before building to understand what's installed
Keep Docker images updated - Rebuild periodically for security patches

Documentation

QUICKSTART.md - Quick start guide
README.md - Full documentation (this file)
EVVM Docs - Official EVVM documentation
Foundry Book - Foundry documentation
Bun Docs - Bun documentation

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Links

EVVM Website: https://www.evvm.info/
EVVM Testnet Contracts: https://github.com/EVVM-org/Testnet-Contracts
Docker Hub: (Coming soon)
Documentation: https://www.evvm.info/docs/

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
QUICKSTART.md		QUICKSTART.md
README.md		README.md
docker-compose.yml		docker-compose.yml

License

EVVM-org/evvm-docker

Folders and files

Latest commit

History

Repository files navigation

EVVM Docker

What's Included

Quick Start

1. Clone or Download

2. Configure Environment

3. Build Docker Image

4. Import Your Wallet

5. Deploy EVVM

File Structure

Use Cases

Prerequisites

Working with Wallets

Option 1: Import wallet inside container (Persistent)

Option 2: Share Foundry keystore from host (Recommended for persistence)

Environment Variables

Available Commands

Using Docker Compose (Recommended)

Using Make (Optional)

Examples

Deploy EVVM on a single chain

Deploy cross-chain EVVM

Register EVVM in the registry

Run Foundry commands

Persisting Data

Deployment outputs

Wallet keystores

Advanced Usage

Run specific Foundry commands

Development mode

Troubleshooting

Stop containers and remove everything

Remove wallets and start fresh

Docker not running

Permission issues

Network connectivity

Update repository

Security

Security

Documentation

Contributing

Links

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages