# Introduction

This section is for engineers and platform teams deploying and operating Cocoon inside their own infrastructure. It covers everything from first-boot to production configuration.

{% hint style="info" %}
Cocoon is designed for **operator-hosted deployment**. Your chain data, keys, transaction history, and identity documents never leave your infrastructure. Ethereum receives only state roots and ZK proofs.
{% endhint %}

## What You Need

Running a Cocoon node requires three things:

1. **Docker and Docker Compose** — all services are packaged as containers. No additional runtime dependencies are needed on the host.
2. **The Cocoon repository** — the `mvp/` directory contains the full Docker Compose stack, contract deployment scripts, and configuration templates.
3. **Environment variables** — a small set of variables controls chain identity, inter-node interoperability, and admin keys. Copy `.env.example` to `.env` and fill in the required values before starting.

The stack is intentionally self-contained. A developer laptop can run the full two-chain configuration. A production deployment runs the same images on dedicated infrastructure behind your network perimeter.

## Deployment Architecture

### Single-node (one chain)

The simplest deployment runs a single Erigon node (Chain A, ID 33) with its associated backend proxy, admin dashboard, investor frontend, user database, and block explorer.

```mermaid
flowchart LR
    subgraph Host["Operator host"]
        ERI["Erigon\n(port 8545)"]
        BE["Backend proxy\n(port 8546)"]
        DB["User DB\n(port 8548)"]
        DASH["Admin dashboard\n(port 3000)"]
        FE["Investor frontend\n(port 3001)"]
        EXP["Explorer\n(port 3002)"]

        ERI --> BE
        BE --> DB
        DASH --> BE
        DASH --> DB
        FE --> BE
        FE --> DB
        EXP --> ERI
    end
```

This is the default configuration and the right starting point for most operators. All services communicate over an internal Docker network; only the ports you choose to expose are reachable from outside the host.

### Multi-node (two chains with interop)

The full MVP stack runs two independent chains (Chain A, ID 33 and Chain B, ID 34) with a cross-chain interoperability listener. Each chain has its own Erigon node, backend proxy, and investor frontend. The admin dashboard and user database are shared.

```mermaid
flowchart LR
    subgraph ChainA["Chain A (ID 33)"]
        E1["Erigon :8545"]
        B1["Backend :8546"]
        F1["Frontend :3001"]
    end
    subgraph ChainB["Chain B (ID 34)"]
        E2["Erigon :8555"]
        B2["Backend :8556"]
        F2["Frontend :3011"]
    end
    subgraph Shared["Shared"]
        UDB["User DB :8548"]
        DASH["Dashboard :3000"]
        EXP["Explorer :3002"]
    end

    B1 <-->|"interop\nevents"| B2
    B1 --> UDB
    B2 --> UDB
    DASH --> B1
    DASH --> B2
    DASH --> UDB
```

The interop listener watches each chain for cross-chain transfer events and calls the corresponding mint/burn on the peer chain using a configured admin key. See [Configuration](/operators/configuration.md) for `INTEROP_*` environment variables.

## Operator Responsibilities

Running a Cocoon node places several obligations on the operating institution:

**Infrastructure and availability.** Cocoon runs entirely within your infrastructure. You are responsible for uptime, backup, and disaster recovery of chain data volumes (`erigon-data`, `erigon2-data`) and the user database (`userdb-data`).

**Key management.** The admin key (`INTEROP_ADMIN_KEY`) authorises cross-chain mint operations and contract administration. Protect it with the same controls you would apply to any signing key. Never commit it to version control.

**Data residency.** Chain state, transaction history, identity documents, and audit logs all reside within your deployment. Do not expose the Erigon RPC port (8545) directly to the internet; traffic should pass through the backend proxy (8546), which enforces session validation and audit logging.

**Contract deployment.** On first boot the `deploy` container deploys all token, identity, and compliance contracts from the `contracts/` directory. The resulting addresses are written to `deployments.json`. If you redeploy contracts (e.g. after a chain reset), update any external integrations that hold hardcoded contract addresses.

**Regulatory compliance.** You operate the KYC/AML claim-issuance workflow. The platform enforces claims at transfer time, but the decisions behind those claims — who is approved, under what conditions, and for how long — remain your responsibility.

## Where to Go Next

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Quick Start</strong></td><td>Clone the repo, set your environment variables, and have the full stack running in under ten minutes.</td><td><a href="/pages/KW9OnEpXyHOf1xYy6vR5">/pages/KW9OnEpXyHOf1xYy6vR5</a></td></tr><tr><td><strong>Configuration</strong></td><td>Complete reference for every configuration parameter: chain, components, prover, identity contracts, torrent, auth, and RPC.</td><td><a href="/pages/PqBrxcG7AS3UBUHu70NR">/pages/PqBrxcG7AS3UBUHu70NR</a></td></tr><tr><td><strong>RPC Reference</strong></td><td>Full method listing for all custom JSON-RPC namespaces: token_, id_, auth_, qm_, proof_, and erigon_.</td><td><a href="/pages/2Gs22pf8m5D08OgkAG2Q">/pages/2Gs22pf8m5D08OgkAG2Q</a></td></tr></tbody></table>


---

# 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/operators.md?ask=<question>
```

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.