Skip to content

README.md

Latest commit

 

History

History
145 lines (111 loc) · 5.65 KB

README.md

File metadata and controls

145 lines (111 loc) · 5.65 KB

Convex logo

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:

  1. The Convex backend
  2. The Convex dashboard
  3. Your frontend app, which you can either host yourself or on a managed service like Netlify or Vercel.

Self-hosting Convex

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.

Docker configuration

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.

Convex Auth

If you're using Convex Auth, follow the manual instructions to set up. The CLI does not support self-hosted deployments yet.

Deploying your frontend app

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.

Advanced Configuration

Limitations

Self-hosted Convex supports all the free-tier features of the cloud-hosted product. The cloud-hosted product is optimized for scale.

Questions and contributions

  • 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.