> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker Compose and blue-green deployment

> Deploy Profy with Docker Compose and Nginx, run zero-downtime blue-green releases, and orchestrate the Agent Runtime alongside Core and Web.

# Deployment

Profy uses Docker Compose for application deployment with Nginx as the public-facing reverse proxy. The platform supports **blue-green deployment** for zero-downtime releases. **Experts** run on the **Agent Runtime** (`services/agent-runtime`) inside **declarative sandboxes** (E2B/Docker), orchestrated alongside Core and Web in Compose.

## Deployment Architecture

```mermaid theme={null}
flowchart TB
    subgraph "Public Internet"
        Client[Browser / SDK]
    end

    subgraph "Host Machine"
        subgraph Nginx["Nginx (Host-Level)"]
            SSL[SSL Termination]
            Cache[Static Asset Cache]
            Proxy[Reverse Proxy]
        end

        subgraph "Docker Compose"
            Web["web<br/>Next.js :3000"]
            Core["core<br/>Hono API :8080"]
            AgentRT["agent-runtime<br/>Agent Runtime :8000"]
            Redis_C["redis<br/>Cache + Session"]
        end

        subgraph "External Services"
            PostgreSQL[(PostgreSQL)]
            S3[(S3)]
        end
    end

    Client --> SSL
    SSL --> Cache
    Cache --> Proxy
    Proxy -->|"/*"| Web
    Proxy -->|"/api/* · /openapi/*"| Core
    Web --> Core
    Web -->|"BACKEND_URL (SSE / invoke)"| AgentRT
    Core --> Redis_C
    Core --> PostgreSQL
    Core --> S3
```

## Prerequisites

| Requirement    | Version                                         |
| -------------- | ----------------------------------------------- |
| Docker         | Latest stable                                   |
| Docker Compose | v2+                                             |
| Nginx          | Host-level installation                         |
| Domain + SSL   | Valid certificate (Let's Encrypt or commercial) |
| Node.js        | >= 20 (for builds)                              |
| Bun            | Latest                                          |

## Docker Compose

The application stack is defined in `deploy/docker/docker-compose.yml`:

| Service         | Image                                | Port | Description                                     |
| --------------- | ------------------------------------ | ---- | ----------------------------------------------- |
| `core`          | Built from `services/core/`          | 8080 | Hono API backend                                |
| `web`           | Built from `apps/web/`               | 3000 | Next.js frontend                                |
| `agent-runtime` | Built from `services/agent-runtime/` | 8000 | Agent Runtime (FastAPI) for Experts / sandboxes |
| `redis`         | `redis:alpine`                       | 6379 | Cache, session store, rate limiting             |

### Quick Deploy

```bash theme={null}
./deploy/scripts/deploy.sh
```

Or manually:

```bash theme={null}
cd deploy/docker
docker compose up -d
```

## Blue-Green Deployment

The deploy script implements a blue-green strategy for zero-downtime updates.

### Slot Allocation

| Slot      | Core Port | Web Port (Prod) | Web Port (Test) |
| --------- | --------- | --------------- | --------------- |
| **Blue**  | 8080      | 3100            | 3000            |
| **Green** | 8081      | 3101            | 3001            |

### Deployment Flow

```mermaid theme={null}
sequenceDiagram
    participant D as Deploy Script
    participant G as Green Env
    participant N as Nginx
    participant B as Blue Env

    D->>D: Identify active slot (Blue)
    D->>G: Build & start Green containers
    D->>G: Run health checks

    alt Health check passes
        D->>N: Update upstream → Green
        N->>N: Reload config
        D->>B: Stop Blue containers
        D->>D: Record Green as active
    else Health check fails
        D->>G: Stop Green containers
        D->>D: Rollback — Blue remains active
    end
```

### Health Checks

The deploy script verifies the new environment before switching traffic:

1. Wait for containers to report healthy status
2. HTTP GET to `GET /health` endpoint
3. Verify response status code
4. Only proceed with traffic switch on success

If health checks fail, the script automatically rolls back by stopping the new environment and keeping the current one active.

## Nginx Configuration

Nginx runs at the host level and serves as the unified entry point.

### Routing Rules

```nginx theme={null}
# API routes → Core backend
location /api/ {
    proxy_pass http://core_upstream;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

# OpenAPI routes → Core backend (API Key auth)
location /openapi/ {
    proxy_pass http://core_upstream;
}

# Internal routes → Core (private network only)
location /internal/ {
    allow 10.0.0.0/8;
    allow 172.16.0.0/12;
    deny all;
    proxy_pass http://core_upstream;
}

# SSE / long-lived streams → Next.js (proxies to Agent Runtime as needed)
location ~ ^/api/(agent|sessions|tools|skills|credits)(/|$) {
    proxy_pass http://web_upstream;
    proxy_http_version 1.1;
    proxy_set_header Connection '';
    proxy_buffering off;
    proxy_cache off;
    chunked_transfer_encoding off;
}

# All other routes → Next.js
location / {
    proxy_pass http://web_upstream;
}
```

### Key Nginx Settings

| Setting                | Value    | Purpose                    |
| ---------------------- | -------- | -------------------------- |
| `proxy_buffering`      | `off`    | Required for SSE streaming |
| `proxy_read_timeout`   | `300s`   | Long-lived SSE connections |
| `client_max_body_size` | `50m`    | File upload support        |
| SSL                    | TLS 1.2+ | HTTPS termination          |

## Environment Variables

### Core API (`services/core`)

| Variable                   | Description                  | Required     |
| -------------------------- | ---------------------------- | ------------ |
| `DATABASE_URL`             | PostgreSQL connection string | Yes          |
| `REDIS_URL`                | Redis connection string      | Yes          |
| `JWT_SECRET`               | Secret key for JWT signing   | Yes          |
| `S3_ENDPOINT`              | S3-compatible storage URL    | Yes          |
| `S3_ACCESS_KEY`            | S3 access key                | Yes          |
| `S3_SECRET_KEY`            | S3 secret key                | Yes          |
| `WECHAT_PAY_APP_ID`        | WeChat Pay app ID            | For payments |
| `WECHAT_PAY_MCH_ID`        | WeChat Pay merchant ID       | For payments |
| `AGENT_INVOKE_URL`         | Agent engine endpoint        | For tasks    |
| `ALIYUN_SMS_ACCESS_KEY_ID` | Aliyun SMS key               | For SMS      |

### Frontend (`apps/web`)

| Variable              | Description                                                   | Required           |
| --------------------- | ------------------------------------------------------------- | ------------------ |
| `NEXT_PUBLIC_API_URL` | Core API base URL                                             | Yes                |
| `BACKEND_URL`         | Agent Runtime base URL (Compose: `http://agent-runtime:8000`) | For Experts / chat |
| `CORE_API_URL`        | Core API URL inside Docker network                            | Yes (Compose)      |

## Agent Runtime & declarative sandboxes

The **Agent Runtime** lives in `services/agent-runtime/` and is built as the `agent-runtime` (and optional `worker`) Compose services. Sandbox provisioning is owned by Core: the E2B template ID is driven by `SANDBOX_E2B_TEMPLATE_ID` (defaults to `profy-sandbox`) in `services/core/.env*`; agent-runtime only selects `SANDBOX_PROVIDER=e2b` and connects to the sandbox by ID. The sandbox image is built from `services/profy-sandbox/` (see `make deploy-sandbox`).

The Next.js app uses `BACKEND_URL` to reach the Agent Runtime for invoke/stream flows; no separate Kubernetes cluster is required for the Expert workforce model.

## Monitoring & Operations

### Health Endpoint

```bash theme={null}
curl https://your-domain.com/health
```

Returns `200 OK` when the Core API is operational.

### Container Logs

```bash theme={null}
docker compose logs -f core
docker compose logs -f web
```

### Rollback

If a deployment fails post-switch, re-run the deploy script — it will detect the current active slot and deploy to the standby slot, effectively rolling back.

## Related Pages

<CardGroup cols={2}>
  <Card title="Architecture" icon="sitemap" href="/en/documentation/architecture/overview">
    System architecture and routing overview
  </Card>

  <Card title="Agent Platform" icon="robot" href="/en/documentation/agent">
    Agent Runtime, Experts, and declarative sandboxes
  </Card>
</CardGroup>