Skip to content

Commit e5431ea

Browse files
SPCFXDASPCFXDA
committed
feat(docker): add Dockerfile, Compose, and devcontainer
- docker/Dockerfile: linux/amd64 image based on node:22-slim, installs conflux-devkit globally, exposes ports 7748/8545/8546/12537/12535, persists data via /root/.conflux-devkit volume - docker/entrypoint.sh: translates DEVKIT_* env vars to CLI flags, always runs with --host 0.0.0.0 --no-open - docker/docker-compose.yml: service with named volume, health-check, restart:unless-stopped, and env var passthrough - docker/.env.example: template for DEVKIT_PORT/API_KEY/CORS_ORIGIN - .dockerignore: exclude node_modules, dist, .git, coverage etc. - .devcontainer/devcontainer.json: Node 22 + pnpm via corepack, Biome/ESLint/TypeScript/Docker extensions, port forwarding for all Conflux RPC ports (7748/8545/8546/12537/12535) - README.md: add Docker usage table and section, Codespaces section
1 parent b0a5899 commit e5431ea

File tree

7 files changed

+279
-0
lines changed

7 files changed

+279
-0
lines changed

‎.devcontainer/devcontainer.json‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
// .devcontainer/devcontainer.json
2+
// VS Code / GitHub Codespaces devcontainer for the cfxdevkit monorepo.
3+
//
4+
// Features:
5+
// • Node.js 22 + pnpm
6+
// • Biome, ESLint and TypeScript tooling pre-installed
7+
// • All workspace ports forwarded automatically
8+
// • `pnpm install` runs automatically after the container is created
9+
{
10+
"name": "cfxdevkit monorepo",
11+
12+
// Use the official Microsoft Node.js devcontainer image (Debian-based).
13+
"image": "mcr.microsoft.com/devcontainers/javascript-node:1-22-bookworm",
14+
15+
// ── Features ─────────────────────────────────────────────────────────────
16+
"features": {
17+
// Enable corepack so `pnpm` is available without a global install.
18+
"ghcr.io/devcontainers/features/node:1": {
19+
"version": "22",
20+
"nodeGypDependencies": false
21+
}
22+
},
23+
24+
// ── VS Code extensions ────────────────────────────────────────────────────
25+
"customizations": {
26+
"vscode": {
27+
"extensions": [
28+
"biomejs.biome",
29+
"dbaeumer.vscode-eslint",
30+
"ms-vscode.vscode-typescript-next",
31+
"esbenp.prettier-vscode",
32+
"ms-azuretools.vscode-docker",
33+
"redhat.vscode-yaml",
34+
"bradlc.vscode-tailwindcss",
35+
"streetsidesoftware.code-spell-checker"
36+
],
37+
"settings": {
38+
// Use Biome as the default formatter for JavaScript / TypeScript.
39+
"editor.defaultFormatter": "biomejs.biome",
40+
"editor.formatOnSave": true,
41+
"[javascript]": { "editor.defaultFormatter": "biomejs.biome" },
42+
"[typescript]": { "editor.defaultFormatter": "biomejs.biome" },
43+
"[json]": { "editor.defaultFormatter": "biomejs.biome" },
44+
"[jsonc]": { "editor.defaultFormatter": "biomejs.biome" }
45+
}
46+
}
47+
},
48+
49+
// ── Port forwarding ───────────────────────────────────────────────────────
50+
// Automatically forward the conflux-devkit UI and all RPC ports so you can
51+
// access them from your browser when running inside Codespaces.
52+
"forwardPorts": [7748, 8545, 8546, 12537, 12535],
53+
"portsAttributes": {
54+
"7748": { "label": "conflux-devkit UI", "onAutoForward": "openBrowser" },
55+
"8545": { "label": "EVM RPC (HTTP)", "onAutoForward": "silent" },
56+
"8546": { "label": "EVM RPC (WebSocket)", "onAutoForward": "silent" },
57+
"12537": { "label": "Conflux Core RPC (HTTP)", "onAutoForward": "silent" },
58+
"12535": { "label": "Conflux Core RPC (WebSocket)", "onAutoForward": "silent" }
59+
},
60+
61+
// ── Lifecycle hooks ───────────────────────────────────────────────────────
62+
"onCreateCommand": "corepack enable && corepack prepare pnpm@latest --activate",
63+
"postCreateCommand": "pnpm install",
64+
"postStartCommand": "pnpm build"
65+
}

‎.dockerignore‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
node_modules
2+
**/node_modules
3+
**/dist
4+
**/.turbo
5+
**/coverage
6+
**/*.log
7+
.git
8+
.devcontainer
9+
.vscode
10+
docs

‎README.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,44 @@ pnpm --filter conflux-devkit build # bundle CLI
8989
node devtools/devkit/dist/cli.js # run
9090
```
9191

92+
### Run with Docker
93+
94+
A pre-built Docker image is the easiest way to spin up `conflux-devkit` without
95+
installing Node.js locally. The image is `linux/amd64` only (mirrors the platform
96+
constraint of `@xcfx/node`).
97+
98+
```bash
99+
# One-liner — exposes UI + all RPC ports, persists chain data in a named volume
100+
docker run --rm \
101+
-p 7748:7748 -p 8545:8545 -p 8546:8546 \
102+
-p 12537:12537 -p 12535:12535 \
103+
-v conflux-devkit-data:/root/.conflux-devkit \
104+
-e DEVKIT_API_KEY=change-me \
105+
conflux-devkit
106+
107+
# Or with Docker Compose (recommended for repeated use)
108+
cd docker
109+
cp .env.example .env # set DEVKIT_API_KEY etc.
110+
docker compose up -d
111+
docker compose logs -f
112+
```
113+
114+
| Environment variable | CLI flag | Default | Description |
115+
|-----------------------|-----------------|-------------|--------------------------------------|
116+
| `DEVKIT_PORT` | `--port` | `7748` | Web UI port |
117+
| `DEVKIT_HOST` | `--host` | `0.0.0.0` | Bind address |
118+
| `DEVKIT_API_KEY` | `--api-key` | _(none)_ | Bearer token; recommended in Docker |
119+
| `DEVKIT_CORS_ORIGIN` | `--cors-origin` | _(none)_ | Allowed CORS origins (comma-separated)|
120+
121+
Build the image locally:
122+
123+
```bash
124+
docker build -t conflux-devkit -f docker/Dockerfile .
125+
```
126+
127+
See [docker/](docker/) for the full `Dockerfile`, `docker-compose.yml`, and
128+
`.env.example`.
129+
92130
---
93131

94132
## Quick start — framework packages
@@ -203,6 +241,21 @@ Build a single package and everything that depends on it:
203241
pnpm turbo build --filter=@cfxdevkit/core...
204242
```
205243

244+
### Codespaces / devcontainer
245+
246+
The repository ships a `.devcontainer/devcontainer.json` so you can open it
247+
instantly in GitHub Codespaces or any VS Code-compatible devcontainer host:
248+
249+
1. Click **Code → Codespaces → Create codespace on main** on GitHub, _or_
250+
2. In VS Code with the Dev Containers extension: **Reopen in Container**.
251+
252+
The container:
253+
- Uses `mcr.microsoft.com/devcontainers/javascript-node:22` (Debian bookworm)
254+
- Enables `pnpm` via corepack
255+
- Runs `pnpm install` and `pnpm build` automatically
256+
- Forwards ports 7748, 8545, 8546, 12537 and 12535
257+
- Installs Biome, ESLint, TypeScript and Docker VS Code extensions
258+
206259
---
207260

208261
## Dependency rules

‎docker/.env.example‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# docker/.env.example — copy to docker/.env and customise
2+
#
3+
# These values are read by docker-compose.yml.
4+
# Never commit .env with real secrets.
5+
6+
# Web UI port (default: 7748)
7+
# DEVKIT_PORT=7748
8+
9+
# Bearer token for /api routes. Strongly recommended when binding
10+
# to 0.0.0.0. Leave empty to disable authentication (localhost-only use).
11+
# DEVKIT_API_KEY=change-me
12+
13+
# Comma-separated list of allowed CORS origins.
14+
# Example: http://localhost:3000,https://my-dapp.example.com
15+
# DEVKIT_CORS_ORIGIN=

‎docker/Dockerfile‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# syntax=docker/dockerfile:1
2+
# ──────────────────────────────────────────────────────────────────────────────
3+
# conflux-devkit — standalone Docker image
4+
#
5+
# Supported platforms: linux/amd64 (linux/arm64 coming when @xcfx/node
6+
# publishes an arm64 linux binary)
7+
#
8+
# Build:
9+
# docker build -t conflux-devkit -f docker/Dockerfile .
10+
#
11+
# Run:
12+
# docker run --rm -p 7748:7748 -p 8545:8545 -p 8546:8546 \
13+
# -p 12537:12537 -p 12535:12535 \
14+
# -v conflux-devkit-data:/root/.conflux-devkit \
15+
# conflux-devkit
16+
# ──────────────────────────────────────────────────────────────────────────────
17+
18+
FROM --platform=linux/amd64 node:22-slim
19+
20+
LABEL org.opencontainers.image.title="conflux-devkit" \
21+
org.opencontainers.image.description="Conflux local development environment" \
22+
org.opencontainers.image.source="https://github.com/cfxdevkit/devkit"
23+
24+
# Install conflux-devkit globally from npm.
25+
# Pin to the exact version that was current when this Dockerfile was written;
26+
# change the version to upgrade. Use --os=linux and --cpu=x64 so npm selects
27+
# the correct @xcfx/node optional dependency even when building on macOS/ARM.
28+
ARG DEVKIT_VERSION=0.1.0
29+
RUN npm install -g \
30+
--os=linux --cpu=x64 \
31+
conflux-devkit@${DEVKIT_VERSION} \
32+
&& npm cache clean --force
33+
34+
# ── Ports ──────────────────────────────────────────────────────────────────
35+
# Web UI
36+
EXPOSE 7748
37+
# Conflux EVM JSON-RPC (HTTP)
38+
EXPOSE 8545
39+
# Conflux EVM JSON-RPC (WebSocket)
40+
EXPOSE 8546
41+
# Conflux Core JSON-RPC (HTTP)
42+
EXPOSE 12537
43+
# Conflux Core JSON-RPC (WebSocket)
44+
EXPOSE 12535
45+
46+
# ── Persistent data volume ──────────────────────────────────────────────────
47+
# Wallets and node chain data are stored under ~/.conflux-devkit.
48+
# Mount a named volume here so data survives container restarts.
49+
VOLUME ["/root/.conflux-devkit"]
50+
51+
# ── Environment variable → CLI flag mapping ─────────────────────────────────
52+
# DEVKIT_PORT Web UI port (default: 7748)
53+
# DEVKIT_HOST Bind address (default: 0.0.0.0)
54+
# DEVKIT_API_KEY Bearer token for /api routes (default: unset)
55+
# DEVKIT_CORS_ORIGIN Allowed CORS origin(s) (default: unset)
56+
ENV DEVKIT_HOST=0.0.0.0 \
57+
DEVKIT_PORT=7748
58+
59+
COPY docker/entrypoint.sh /usr/local/bin/entrypoint.sh
60+
RUN chmod +x /usr/local/bin/entrypoint.sh
61+
62+
ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]

‎docker/docker-compose.yml‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# docker-compose.yml — run conflux-devkit as a local service
2+
#
3+
# Usage:
4+
# docker compose up -d # start in background
5+
# docker compose logs -f # stream logs
6+
# docker compose down # stop (data volume is preserved)
7+
# docker compose down -v # stop AND delete chain data
8+
9+
services:
10+
devkit:
11+
build:
12+
context: ..
13+
dockerfile: docker/Dockerfile
14+
image: conflux-devkit:latest
15+
container_name: conflux-devkit
16+
platform: linux/amd64
17+
18+
# ── Ports ──────────────────────────────────────────────────────────────
19+
ports:
20+
- "${DEVKIT_PORT:-7748}:${DEVKIT_PORT:-7748}" # Web UI
21+
- "8545:8545" # EVM RPC (HTTP)
22+
- "8546:8546" # EVM RPC (WebSocket)
23+
- "12537:12537" # Core RPC (HTTP)
24+
- "12535:12535" # Core RPC (WebSocket)
25+
26+
# ── Persistent chain data ───────────────────────────────────────────────
27+
volumes:
28+
- conflux-devkit-data:/root/.conflux-devkit
29+
30+
# ── Configuration via environment variables ─────────────────────────────
31+
# Copy .env.example to .env and customise as needed.
32+
environment:
33+
DEVKIT_HOST: "0.0.0.0"
34+
DEVKIT_PORT: "${DEVKIT_PORT:-7748}"
35+
DEVKIT_API_KEY: "${DEVKIT_API_KEY:-}"
36+
DEVKIT_CORS_ORIGIN: "${DEVKIT_CORS_ORIGIN:-}"
37+
38+
restart: unless-stopped
39+
40+
# Simple health-check: the UI endpoint must respond with HTTP 200.
41+
healthcheck:
42+
test: ["CMD", "node", "-e",
43+
"require('http').get('http://localhost:${DEVKIT_PORT:-7748}/', r => process.exit(r.statusCode === 200 ? 0 : 1)).on('error', () => process.exit(1))"]
44+
interval: 10s
45+
timeout: 5s
46+
retries: 6
47+
start_period: 15s
48+
49+
volumes:
50+
conflux-devkit-data:
51+
driver: local

‎docker/entrypoint.sh‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
#!/bin/sh
2+
# entrypoint.sh — translate environment variables to CLI flags and start
3+
# conflux-devkit bound to all interfaces (no browser in a container).
4+
5+
set -e
6+
7+
ARGS="--host ${DEVKIT_HOST:-0.0.0.0} --port ${DEVKIT_PORT:-7748} --no-open"
8+
9+
if [ -n "${DEVKIT_API_KEY}" ]; then
10+
ARGS="${ARGS} --api-key ${DEVKIT_API_KEY}"
11+
fi
12+
13+
if [ -n "${DEVKIT_CORS_ORIGIN}" ]; then
14+
ARGS="${ARGS} --cors-origin ${DEVKIT_CORS_ORIGIN}"
15+
fi
16+
17+
# Allow callers to append arbitrary extra flags via DEVKIT_EXTRA_ARGS.
18+
if [ -n "${DEVKIT_EXTRA_ARGS}" ]; then
19+
ARGS="${ARGS} ${DEVKIT_EXTRA_ARGS}"
20+
fi
21+
22+
# shellcheck disable=SC2086
23+
exec conflux-devkit $ARGS "$@"

0 commit comments

Comments
 (0)