Local dev self hosted prepopulate env vars

[thorn dragon]

Is it possible to prepopulate the environment variables of the self hosted docker convex container when running it for local development?

[clear plank]

Hi @thorn dragon. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

---

Yes, you can, but there are two different “layers” of environment variables to keep in mind:

1. Backend/container configuration (Docker env vars)
   These are the variables that configure the self‑hosted Convex backend itself, e.g.:

   • CONVEX_CLOUD_ORIGIN
   • CONVEX_SITE_ORIGIN
   • DATABASE_URL (if using Postgres)
   • etc.

   When using the provided docker-compose.yml for self‑hosting, you set these as normal Docker environment variables (either directly in docker-compose.yml or via docker compose ... -e ...). [Self-host docker]

2. Deployment environment variables used by your Convex functions
   These are the ones your Convex code reads via process.env (e.g. POLAR_ACCESS_TOKEN, R2 credentials, etc.). Those are not read from .env.local or from the container’s process environment; they must be set as Convex deployment env vars via:

   • The Convex dashboard for that deployment, or
   • npx convex env set <name> <value> against that deployment. [CLI env; Env behavior]

For a self‑hosted backend used in local dev, the recommended flow is:

1. Run the self‑hosted backend via Docker (with its own config env vars in docker-compose.yml). [Self-host setup]
2. Set CONVEX_SELF_HOSTED_URL and CONVEX_SELF_HOSTED_ADMIN_KEY in your local .env.local so npx convex dev / npx convex deploy talk to that backend. [Dev workflow]
3. Use npx convex env set ... (or the self‑hosted dashboard) to populate the deployment env vars your code needs.

The knowledge sources don’t describe a way to “pre-seed” Convex deployment env vars purely via Docker container env vars; they must be set through the Convex env mechanism (CLI or dashboard) once the backend is running.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@thorn dragon Kapa.ai is still learning and improving, please let me know how I did by reacting below.

[thorn dragon]

Yeah I have a script that runns the convex env set in a loop but it needs to be sequential and it's slow... is there a way to run it in parallel or in bulk? as rn it errors out due to write conflicts if running more than one at a time

@clear plank Yeah I have a script that runns the convex env set in a loop but it needs to be sequential and it's slow... is there a way to run it in parallel or in bulk? as rn it errors out due to write conflicts if running more than one at a time

[clear plank]

Let me check the knowledge base for you again. One moment! :books:

---

There’s partial support, but with limitations.

From the docs and Discord threads, Convex env vars are meant to be set one‑by‑one via the CLI:

npx convex env set <name> <value>

This is the only documented way today; there’s no official “bulk set” or “parallel set” command, and the deployment‑API docs only expose a generic POST /update_environment_variables endpoint without public details on how to call it directly. [CLI env; Update env API]

People who automate this (e.g. with Doppler or CI) are doing exactly what you’re doing: scripting multiple npx convex env set calls, sequentially. [Doppler thread; Env automation]

Given that:

• Running multiple convex env set in parallel is not supported and can cause conflicts (as you’re seeing).
• There’s no documented bulk/parallel API for env vars yet.

So, based on the current docs, the safe option is:

• Keep them sequential (one convex env set at a time).
• If speed is an issue, minimize the number of env vars or how often you re‑set them (e.g. only update changed ones).

If you need true bulk/parallel behavior, that would be a feature request; the existing materials explicitly say they’re still thinking about better deployment‑management APIs for this use case. [Doppler thread]

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: