---
title: "Node and Docker"
description: "Validate the repository-owned Node Gateway, Worker, Admin API, Console, and PostgreSQL composition."
---

> Documentation Index
> Fetch the complete documentation index at: https://nexus.microvoid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Node and Docker

## Outcome

在 loopback 上运行仓库实际维护的 PostgreSQL、Admin API、Gateway、Worker 和 Console Composition，并清楚识别生产化前仍需替换的部分。

## Local composition

```sh title="Terminal"
cp .env.example .env
docker compose --env-file .env -f deploy/docker-compose/compose.yaml up --build -d
```

Compose 固定到 loopback：Admin `3000`、Gateway `4000`、Console `5173`、PostgreSQL `5432`。Worker Readiness 仅在 Compose 网络内的 `4001` 暴露。

```sh title="Terminal"
curl --fail http://127.0.0.1:3000/health/ready
curl --fail http://127.0.0.1:4000/health/ready
curl --fail --head http://127.0.0.1:5173/health/ready
docker compose --env-file .env -f deploy/docker-compose/compose.yaml ps
```

## What the images run

- `apps/api/Dockerfile` 启动 Admin/Auth/Webhook API。
- `apps/deploy-node/Dockerfile` 的 `gateway` Target 运行 Web Standard Gateway Adapter。
- 同一 Dockerfile 的 `worker` Target 处理 Outbox、Reservation recovery 和异步事件。
- `apps/console/Dockerfile` 构建并托管静态 Console。

也可以先构建 Node Adapter，再分别执行：

```sh title="Terminal"
pnpm --filter @nexus/deploy-node build
pnpm --filter @nexus/deploy-node start:gateway
pnpm --filter @nexus/deploy-node start:worker
```

## Production hardening required

当前 Compose 明确设置 `NEXUS_ENV=development`、本地 Provider Secret Driver 和开发默认 Secret。生产部署至少需要：

1. 替换所有数据库、Better Auth、Provider encryption 和 Captcha Secret。
2. 为外部连接启用 TLS，使用最小权限网络和数据库身份。
3. 用平台 Secret Manager 注入 Server-only 值，不在镜像或公开 `VITE_*` 变量中 Bake Secret。
4. 把持久化 PostgreSQL、备份、恢复、迁移 Owner 和容量规划移交给受控基础设施。
5. 配置独立域名、CORS/Origin、反向代理、Request size/timeout 和 graceful shutdown。
6. 采集 Gateway/API/Worker 日志、Metrics/Traces 与 Beta SLO 告警。

## Database ownership

Compose 的首次初始化 Mount 迁移文件只服务一次性本地 Volume。共享和生产数据库使用仓库迁移命令/发布工作流，不能依赖 `docker-entrypoint-initdb.d` 作为持续迁移工具。

```sh title="Terminal"
pnpm db:migrate
```

## Shutdown and recovery

应用的 `NEXUS_SHUTDOWN_GRACE_MS` 与平台 termination grace 应为进行中的 Stream 留出结算/释放窗口。停止本地服务不会删除 Volume：

```sh title="Terminal"
docker compose --env-file .env -f deploy/docker-compose/compose.yaml down
```

不要在普通停止流程使用 `down --volumes`；那会删除本地 PostgreSQL 数据。

## Check your work

- 四个公开 Health Check 通过，Worker 在 Compose 中为 Healthy。
- 完成一次 [local golden path](/docs/quickstarts/run-nexus-locally)，Reservation 进入终态。
- 镜像和运行日志不包含 `.env` Secret。
- 杀停 Gateway/Worker 后，恢复流程能处理未完成 Reservation，而不会重复扣量。

Source: https://nexus.microvoid.io/docs/deploy-nexus/node-docker/index.mdx