#self-host env

8 messages · Page 1 of 1 (latest)

twin nebula
#

what is the npx convex deploy --cmd 'npm run build' version of self-host

vivid ridgeBOT
#

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

#

For self-hosted Convex deployments, the equivalent of the cloud-hosted command:

npx convex deploy --cmd 'npm run build'

is to use the same command, but you must set the environment variables to point to your self-hosted backend. Specifically, you need to set CONVEX_SELF_HOSTED_URL and CONVEX_SELF_HOSTED_ADMIN_KEY instead of CONVEX_DEPLOY_KEY. This tells the Convex CLI to deploy to your self-hosted instance rather than the Convex cloud.

Example usage in your environment (e.g., in a .env.local file or CI/CD environment variables):

CONVEX_SELF_HOSTED_URL='<https://<your-backend-url>'>
CONVEX_SELF_HOSTED_ADMIN_KEY='<your admin key>'

Then you can run:

npx convex deploy --cmd 'npm run build'

This will deploy your Convex functions to your self-hosted backend and run your frontend build, injecting the correct Convex URL for your frontend to use. The process is the same as with cloud deployments, but uses the self-hosted environment variables. Make sure not to mix cloud and self-hosted environment variables in the same environment to avoid deploying to the wrong backend Self-hosted development workflow.

If you need to customize the environment variable name for the Convex URL in your frontend, you can use the --cmd-url-env-var-name flag as with cloud deployments.

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

#

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

twin nebula
vivid ridgeBOT
#

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

#

The error

✖ Vercel build environment detected but CONVEX_DEPLOY_KEY is not set. Set this environment variable to deploy from this environment. See <https://docs.convex.dev/production/hosting>

occurs because, in a Vercel build environment, the Convex CLI expects a CONVEX_DEPLOY_KEY for cloud deployments. However, for self-hosted Convex, you should use CONVEX_SELF_HOSTED_URL and CONVEX_SELF_HOSTED_ADMIN_KEY instead.

The issue is that the Convex CLI currently does not support self-hosted deployments in Vercel build environments. This is explicitly mentioned in the self-hosted documentation:

If you're hosting your website on a provider like Netlify or Vercel using our production hosting instructions, be sure to swap out the environment variables in those instructions for the SELF_HOSTED equivalents.

... The CLI does not support self-hosted deployments yet.

source

So, if you try to run npx convex deploy in a Vercel build environment with only the self-hosted variables, the CLI will still look for CONVEX_DEPLOY_KEY and fail, because self-hosted support in the CLI for these environments is not yet implemented.

Workaround:
You will need to deploy your Convex functions to your self-hosted backend from a local environment or CI/CD system that is not a Vercel build environment. Then, build and deploy your frontend on Vercel, making sure it points to your self-hosted Convex backend via the appropriate environment variable (e.g., VITE_CONVEX_URL or NEXT_PUBLIC_CONVEX_URL).

Summary:

  • The Convex CLI does not currently support self-hosted deploys from within Vercel builds.
  • Deploy your Convex backend from outside Vercel, and only build your frontend on Vercel, pointing it to your self-hosted Convex backend.
#

If you need to automate this, consider using a separate CI/CD pipeline for backend deploys, or run the deploy step locally before pushing your frontend to Vercel Self-hosted README.

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