# Quick Start This guide takes you from zero to a running Cocoon stack in under ten minutes. By the end you will have two Erigon chains, the backend proxy, admin dashboard, investor frontends, user database, and block explorer 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 | {% hint style="warning" %} **Apple Silicon (M-series) users:** all images build natively for `linux/arm64`. If you encounter `exec format error` on any container, ensure Docker Desktop is set to use the native ARM engine, not Rosetta emulation. {% endhint %} ## Step 1 — Clone the Repository ```bash git clone https://github.com/your-org/cocoon.git cd cocoon ``` The stack lives in the `mvp/` subdirectory: ```bash 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 your editor: {% tabs %} {% tab title="Linux / macOS" %} ```bash cp .env.example .env $EDITOR .env ``` {% endtab %} {% tab title="Windows (PowerShell)" %} ```powershell Copy-Item .env.example .env notepad .env ``` {% endtab %} {% endtabs %} The minimum required values are: ```dotenv # 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 ``` {% hint style="danger" %} **Never commit `.env` to version control.** The file contains your admin private key. Verify `.env` is listed in `.gitignore` before proceeding. {% endhint %} For a full list of supported variables see [Configuration](/operators/configuration.md). ## Step 3 — Start the Stack {% tabs %} {% tab title="Using make" %} ```bash make ``` The `Makefile` target runs `docker compose up --build -d` and tails the logs. {% endtab %} {% tab title="Using Docker Compose directly" %} ```bash docker compose up --build -d ``` {% endtab %} {% tab title="Single chain only" %} To start only Chain A (lighter on resources): ```bash docker compose up --build -d erigon deploy backend user_db dashboard frontend explorer ``` {% endtab %} {% endtabs %} Docker builds all images on first run. This takes 3–8 minutes depending on your 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. You can watch progress: ```bash 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 ``` {% hint style="info" %} The `deploy` containers exit with code 0 when contract deployment succeeds. If they show `exited (1)`, check the logs with `docker compose logs deploy`. {% endhint %} ## Step 5 — Verify the Stack **Check the backend health endpoint:** ```bash curl http://localhost:8546/health ``` Expected response: ```json {"status":"ok","chainReachable":true} ``` **Check the Erigon RPC directly:** ```bash 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): ```json { "jsonrpc": "2.0", "id": 1, "result": "33" } ``` **Check the latest block:** ```bash 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:** ```bash curl http://localhost:8548/health ``` Expected: `{"status":"ok"}` **Open the dashboard:** Navigate to in your browser. The admin dashboard shows token balances, recent transfers, and the audit log for Chain A. **Open the block explorer:** Navigate to . 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: ```bash cat deployments.json ``` You should see a JSON object with `chainId: 33` and addresses for `PermissionRegistry`, `MMFToken`, `Stablecoin`, and the Uniswap V3 pool contracts. For Chain B: ```bash cat deployments.chain2.json ``` ## Next Steps With the stack running you can:
Onboard an investorUse the admin dashboard to whitelist an address on the MMF token, or call token_onboardInvestor directly via the RPC.
Issue a token subscriptionHave a whitelisted investor call token_subscribe or use the investor frontend at port 3001 to subscribe stablecoin for MMF shares.
Deploy a custom tokenCall token_deploy via the RPC to deploy a new ERC-3643 permissioned token with your own compliance parameters.
Configure for productionReview the full Configuration reference and harden the deployment: replace demo keys, restrict port exposure, and enable strict auth mode.
## Stopping the Stack ```bash docker compose down ``` To stop and remove all data volumes (full reset): ```bash docker compose down -v ``` {% hint style="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. {% endhint %} ## Viewing Logs ```bash # All services docker compose logs -f # Specific service docker compose logs -f backend # Last 100 lines of Erigon docker compose logs --tail=100 erigon ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://cocoon.erigon.tech/operators/quick-start.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.