Skip to content

Commit a81adfb

Browse files
iamfjiamfj
committed
Enhance docs with DevContainer guide
- 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
1 parent 916e1d5 commit a81adfb

File tree

3 files changed

+148
-0
lines changed

3 files changed

+148
-0
lines changed

‎self-hosted/README.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,15 @@ Self-hosting Convex requires deploying three services:
2828
1. Your frontend app, which you can either host yourself or on a managed service
2929
like Netlify or Vercel.
3030

31+
> [!TIP]
32+
> **Local Development: Add Convex to Your Own DevContainer**
33+
>
34+
> Want to use Convex in your own project with a reproducible, containerized local development environment?
35+
> Check out our [DevContainer guide](./devcontainer/README.md) for step-by-step instructions on how to add Convex to > your own repository using Visual Studio Code and Docker. This approach lets you spin up a fully configured Convex > backend for local development, with no manual dependency setup required.
36+
>
37+
> **To get started:**
38+
> Follow the instructions in [self-hosted/devcontainer/README.md](./devcontainer/README.md) to add a DevContainer > configuration to your project and run Convex locally inside Docker.
39+
3140
# Self-hosting Convex
3241

3342
By default the Convex backend will store all state in a local SQLite database.

‎self-hosted/devcontainer/README.md

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