Skip to content

Commit 0706e63

Browse files
nipunn1313iamfj
authored and
Convex, Inc.
committed
convex-backend PR 84: Enhance docs with DevContainer guide (#37187)
- Added an example DevContainer configuration for running Convex in a containerized environment. - Updated `README.md` to include a guide on integrating Convex with DevContainers for reproducible local development. - The DevContainer setup includes necessary mounts, port forwarding, and commands for easy onboarding and consistent development experience. #79 Co-authored-by: Fabian Jocks <[email protected]> GitOrigin-RevId: a68728d9e1409f39717dc3ac01ea09f2dc7313e5
1 parent 804e1b9 commit 0706e63

File tree

2 files changed

+166
-0
lines changed

2 files changed

+166
-0
lines changed

‎self-hosted/devcontainer/README.md

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# Running Convex in a DevContainer for Local Development [Community maintained]
2+
3+
If you're working with Convex and want to use a consistent, container-based
4+
development environment, this guide provides a minimal setup using
5+
[DevContainers](https://containers.dev/) and Docker.
6+
7+
> [!IMPORTANT]
8+
> This approach is meant for **local development** and is not intended for
9+
> self-hosting Convex in production.
10+
11+
## What is a DevContainer?
12+
13+
A DevContainer is a development environment defined as code and backed by a
14+
Docker container. It integrates tightly with Visual Studio Code through the
15+
[Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
16+
17+
When you open a project with a `.devcontainer/devcontainer.json` file, VS Code
18+
automatically builds the container, installs dependencies, and mounts your
19+
project directory inside it.
20+
21+
This setup is especially useful for teams, open source contributors, or anyone
22+
who wants to avoid dependency drift between local machines.
23+
24+
## Why use a DevContainer?
25+
26+
- Reproducible local environment with no host machine setup required
27+
- Isolated from other projects and host system
28+
- Preconfigured runtimes, dependencies, tools and extensions (e.g., Node.js,
29+
pnpm, Convex CLI)
30+
- Easy onboarding for new team members or contributors
31+
32+
## Requirements
33+
34+
To use a DevContainer, you need to have the following installed:
35+
36+
- [Docker](https://www.docker.com/products/docker-desktop)
37+
- [Visual Studio Code](https://code.visualstudio.com/)
38+
- [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
39+
40+
## Minimal DevContainer Example for Convex
41+
42+
The following is a minimal example of a working
43+
`.devcontainer/devcontainer.json` setup using a Node.js/TypeScript base image.
44+
It binds the necessary Convex and pnpm directories, and explicitly forwards the
45+
required ports:
46+
47+
```jsonc
48+
{
49+
"name": "convex-dev",
50+
"image": "mcr.microsoft.com/devcontainers/typescript-node:1-22-bookworm",
51+
"workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
52+
53+
"postCreateCommand": "npm install -g convex && npx convex dev --once",
54+
"postAttachCommand": "git config --global diff.ool ...",
55+
"postStartCommand": "git config --global --add safe.directory /workspaces/${localWorkspaceFolderBasename}",
56+
57+
"mounts": [
58+
"source=${localEnv:HOME}/.ssh,target=/home/node/.ssh,type=bind,consistency=cached",
59+
"source=${localEnv:HOME}/.convex,target=/home/node/.convex,type=bind,consistency=cached",
60+
"source=${localEnv:HOME}/.cache/convex,target=/home/node/.cache,type=bind,consistency=cached",
61+
],
62+
63+
"remoteUser": "node",
64+
"forwardPorts": [3210, 6790, 6791],
65+
}
66+
```
67+
68+
You can adapt the image, remote user, or mounted paths depending on your project
69+
needs or base OS image.
70+
71+
### Explanation of the Configuration
72+
73+
This minimal setup includes just a few customizations that are important for
74+
Convex to run reliably inside a containerized environment.
75+
76+
#### `.convex` mount
77+
78+
```json
79+
"mounts": [
80+
"source=${localEnv:HOME}/.convex,target=/home/node/.convex,type=bind"
81+
]
82+
```
83+
84+
Convex stores some local state in the `.convex` directory (such as deployment
85+
metadata and generated admin keys). Mounting it from your host machine into the
86+
container ensures that:
87+
88+
- The state is preserved across container rebuilds.
89+
- You can reuse the same identity and credentials inside and outside the
90+
container.
91+
92+
Without this mount, Convex might behave as if it's being run for the first time
93+
every time you restart the container.
94+
95+
#### `.cache/convex` mount
96+
97+
```json
98+
"source=${localEnv:HOME}/.cache/convex,target=/home/node/.cache,type=bind,consistency=cached"
99+
```
100+
101+
During `pnpm convex dev`, the Convex CLI downloads necessary artifacts such as
102+
backend binaries and the dashboard frontend into the `.cache/convex` directory.
103+
By mounting this directory from the host into the container, those files are
104+
persisted between container rebuilds and restarts.
105+
106+
This avoids re-downloading the same artifacts every time the container is
107+
recreated, which speeds up startup and reduces bandwidth usage.
108+
109+
#### Forwarded ports
110+
111+
```json
112+
"forwardPorts": [3210, 6790, 6791]
113+
```
114+
115+
Convex uses these ports during local development:
116+
117+
- `3210` — the API server
118+
- `6790` — the web dashboard
119+
- `6791` — the internal health check used by the dashboard to determine if a
120+
local deployment is available
121+
122+
Forwarding these ports ensures that the services running inside the container
123+
are accessible from your host machine and from the dashboard itself.
124+
125+
#### `postCreateCommand`
126+
127+
```json
128+
"postCreateCommand": "npx convex dev --once"
129+
```
130+
131+
This command ensures the Convex development server is started as soon as the
132+
container is ready. The `--once` flag runs the server in one-off mode, avoiding
133+
watch mode or automatic restarts.
134+
135+
This is useful for initial setup to verify everything is working, but you can
136+
always stop it and run `pnpm convex dev` manually when actively working on your
137+
functions.

‎self-hosted/devcontainer/devcontainer.json

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
// For format details, see https://aka.ms/devcontainer.json. For config options, see the
2+
// README at: https://github.com/devcontainers/templates/tree/main/src/typescript-node
3+
{
4+
"name": "convex-dev",
5+
6+
// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
7+
"image": "mcr.microsoft.com/devcontainers/typescript-node:1-22-bookworm",
8+
"workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
9+
10+
// Lifecycle events
11+
"postCreateCommand": "npm install -g convex && npx convex dev --once",
12+
"postAttachCommand": "git config --global diff.ool ...",
13+
"postStartCommand": "git config --global --add safe.directory /workspaces/${localWorkspaceFolderBasename}",
14+
15+
"mounts": [
16+
"source=${localEnv:HOME}/.ssh,target=/home/node/.ssh,type=bind,consistency=cached",
17+
"source=${localEnv:HOME}/.convex,target=/home/node/.convex,type=bind,consistency=cached",
18+
"source=${localEnv:HOME}/.cache/convex,target=/home/node/.cache,type=bind,consistency=cached"
19+
],
20+
21+
// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
22+
"remoteUser": "node",
23+
24+
// Use 'forwardPorts' to make a list of ports inside the container available locally.
25+
"forwardPorts": [3210, 6790, 6791],
26+
27+
// Configure tool-specific properties.
28+
"customizations": {}
29+
}

0 commit comments

Comments
 (0)