Quick Start

This guide goes from zero to a running Cocoon stack in under ten minutes. By the end, two Erigon chains, the backend proxy, admin dashboard, investor frontends, user database, and block explorer are all running locally via Docker Compose.

Prerequisites

Requirement	Minimum	Notes
Docker Engine	24.x or later	Docker Desktop also works
Docker Compose	v2.20 or later	Bundled with Docker Desktop
Git	Any recent version	For cloning the repo
RAM	16 GB recommended	8 GB minimum for single-chain only
Disk	20 GB free	For chain data volumes
CPU	4 cores recommended	The prover is CPU-intensive

warning

Apple Silicon (M-series) users: all images build natively for linux/arm64. If an exec format error appears on any container, ensure Docker Desktop is set to use the native ARM engine, not Rosetta emulation.

Step 1 — Clone the Repository

git clone https://github.com/erigontech/cocoon.git
cd cocoon

The stack lives in the mvp/ subdirectory:

cd mvp

All subsequent commands in this guide are run from the mvp/ directory.

Step 2 — Configure Environment Variables

Copy the example environment file and open it in an editor:

---

cp .env.example .env
$EDITOR .env

---

Copy-Item .env.example .env
notepad .env

The minimum required values are:

# Admin account — used for contract deployment and interop signing
# Use a dedicated key; never reuse a personal or production wallet key
INTEROP_ADMIN=0xYourAdminAddress
INTEROP_ADMIN_KEY=your_private_key_hex_no_0x_prefix

# Auth mode: "advisory" logs auth failures; "strict" rejects unauthenticated calls
AUTH_MODE=advisory

# Origins allowed to call the backend proxy (comma-separated)
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001,http://localhost:3011

danger

Never commit .env to version control. The file contains the admin private key. Verify .env is listed in .gitignore before proceeding.

For a full list of supported variables see Configuration.

Step 3 — Start the Stack

---

make

The Makefile target runs docker compose up --build -d and tails the logs.

---

docker compose up --build -d

---

To start only Chain A (lighter on resources):

docker compose up --build -d erigon deploy backend user_db dashboard frontend explorer

Docker builds all images on first run. This takes 3–8 minutes depending on the machine and network. Subsequent starts are fast because layers are cached.

Step 4 — Wait for Services to Become Healthy

The stack uses Docker health checks. The deploy and deploy-chain2 one-shot containers wait for their respective Erigon nodes to be healthy before deploying contracts. Watch progress:

docker compose ps

Expected output when everything is up:

NAME              STATUS              PORTS
erigon            healthy             0.0.0.0:8545->8545/tcp
erigon2           healthy             0.0.0.0:8555->8545/tcp
deploy            exited (0)
deploy-chain2     exited (0)
backend           healthy             0.0.0.0:8546->8546/tcp
backend2          healthy             0.0.0.0:8556->8546/tcp
user_db           healthy             0.0.0.0:8548->8548/tcp
dashboard         running             0.0.0.0:3000->3000/tcp
frontend          running             0.0.0.0:3001->3001/tcp
frontend2         running             0.0.0.0:3011->3001/tcp
explorer          running             0.0.0.0:3002->3002/tcp

note

The deploy containers exit with code 0 when contract deployment succeeds. If they show exited (1), check the logs with docker compose logs deploy.

Step 5 — Verify the Stack

Check the backend health endpoint:

curl http://localhost:8546/health

Expected response:

{"status":"ok","chainReachable":true}

Check the Erigon RPC directly:

curl -s -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"net_version","params":[]}' \
  http://localhost:8545 | python3 -m json.tool

Expected response (Chain A):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "33"
}

Check the latest block:

curl -s -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' \
  http://localhost:8545

The block number should be increasing (the Clique PoA engine produces a block every second).

Check the user database:

curl http://localhost:8548/health

Expected: {"status":"ok"}

Open the dashboard:

Navigate to http://localhost:3000 in a browser. The admin dashboard shows token balances, recent transfers, and the audit log for Chain A.

Open the block explorer:

Navigate to http://localhost:3002. Blocks appear in real time as the chain produces them.

Step 6 — Confirm Contract Deployment

Contract addresses are written to deployments.json after the deploy container completes. Verify the file exists and contains addresses:

cat deployments.json

The output is a JSON object with chainId: 33 and addresses for PermissionRegistry, MMFToken, Stablecoin, and the Uniswap V3 pool contracts.

For Chain B:

cat deployments.chain2.json

Next Steps

With the stack running:

• Configure backend services and RPC method allowlisting — see Backend Configuration.
• Manage user onboarding, KYC, and roles — see KYC & User Management.
• Review the immutable audit log and compliance reports — see Audit & Compliance Reporting.
• Explore the admin dashboard, investor portal, and block explorer — see User Interfaces.

Stopping the Stack

docker compose down

To stop and remove all data volumes (full reset):

docker compose down -v

warning

docker compose down -v deletes all chain data and the user database. Contract addresses in deployments.json will no longer match the new chain state. Only use this for a clean development reset.

Viewing Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f backend

# Last 100 lines of Erigon
docker compose logs --tail=100 erigon