self-hosted/README.md
If you're new to Convex we recommend starting with the onboarding tutorial to familiarize yourself with the Convex development experience.
If you're in this README, you're interested in self-hosting
Convex on your own infrastructure or a managed hosting
provider. Support is available on the
Convex Discord in the #self-hosted channel.
If you don't specifically want to self-host, head over to the Convex docs to use the cloud-hosted product. Cloud-hosted Convex includes a generous free tier and provides a seamless, reliable, cost-effective platform that allows you to focus on building your application without worrying about infrastructure.
Self-hosting Convex requires deploying three services:
By default the Convex backend will store all state in a local SQLite database. We recommend starting with this basic configuration and then moving the container to a hosting provider or pointing the backend to a separate SQL database for a production-ready configuration as needed.
First download the
docker-compose.yml file.
Then, to start the backend and dashboard:
docker compose up
Once the backend is running you can use it to generate admin keys for the dashboard/CLI:
docker compose exec backend ./generate_admin_key.sh
Visit the dashboard at http://localhost:6791. The backend listens on
http://127.0.0.1:3210. The backend's http actions are available at
http://127.0.0.1:3211.
In your Convex project, add your url and admin key to a .env.local file (which
should not be committed to source control):
CONVEX_SELF_HOSTED_URL='http://127.0.0.1:3210'
CONVEX_SELF_HOSTED_ADMIN_KEY='<your admin key>'
Now you can run commands in your Convex project, to push code, run queries, import data, etc. To use these commands, you'll need the latest version of Convex.
npm install convex@latest
Now you can push code, run queries, import data, etc.
npx convex dev
npx convex --help # see all available commands
By default, the backend will store its data in a volume managed by Docker. Note that you'll need to set up persistent storage on whatever cloud hosting platform you choose to run the Docker container on (e.g. AWS EBS). By default the database is stored locally in SQLite but you may also point it to a SQL database either locally or on a cloud service of your choice following these instructions. You can also configure the backend to use S3 storage for exports, snapshots, modules, files, and search indexes following these instructions.
You should now be able to use the self-hosted backend. Read on for alternative hosting options for production workloads.
If you're using Convex Auth, follow the manual instructions to set up. The CLI does not support self-hosted deployments yet.
The Convex backend runs all database and compute functions but it doesn't host
your actual web app. 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.
e.g., instead of setting CONVEX_DEPLOY_KEY, you'll need to set
CONVEX_SELF_HOSTED_URL to the url where your Convex backend is hosted and
CONVEX_SELF_HOSTED_ADMIN_KEY to the admin key you generated with the
generate_admin_key.sh script.
Self-hosted Convex supports all the free-tier features of the cloud-hosted product. The cloud-hosted product is optimized for scale.
Join our Discord community for help and
discussions. The #self-hosted channel is the best place to go for questions
about self-hosting.
Report issues when building and using the open source Convex backend through GitHub Issues
We welcome bug fixes and love receiving feedback. We keep this repository synced with any internal development work within a handful of days.