Improve local_backend and self-hosted readmes (#34006)

Reorder / change tone / encourage self-hosting and docker

GitOrigin-RevId: 24770f3eb7dca96d45eb7565d1671a61393385e2

Author: nipunn1313

README.md

@@ -7,9 +7,8 @@
 </p>
 
 [Convex](https://convex.dev) is the open-source reactive database designed to
-make life easy for web app developers, whether you're a human or an LLM. Fetch
-data and perform business logic with strong consistency by writing pure
-TypeScript.
+make life easy for web app developers, whether human or LLM. Fetch data and
+perform business logic with strong consistency by writing pure TypeScript.
 
 Convex replaces your database, server functions, scheduling, storage, vector
 search, etc. It includes
@@ -24,7 +23,8 @@ The best way to get started with Convex is to follow the
 The **[Convex managed hosted product](https://www.convex.dev/plans).** 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.
+infrastructure. Many small applications and side-projects can operate entirely
+on the free tier with zero cost and zero maintenance.
 
 Development of the Convex backend is led by the Convex team. We
 [welcome bug fixes](./CONTRIBUTING.md) and
@@ -33,9 +33,11 @@ synced with any internal development work within a handful of days.
 
 ## Self Hosting
 
-You can also opt to self-host Convex. Convex works with a variety of tools
-including Neon, Fly.io, RDS, sqlite, postgres, and more. There is a
-[self-hosting guide](./self-hosted/SELFHOSTING.md) available with some guidance.
+You can also opt to self-host Convex. The self-hosted product includes most
+features of the cloud product, including the dashboard and CLI. Self-hosted
+Convex works well with a variety of tools including Neon, Fly.io, Vercel,
+Netlify, RDS, Sqlite, Postgres, and more. There is a
+[self-hosting guide](./self-hosted/SELFHOSTING.md) available with instructions.
 Community support for self-hosting is available in the `#open-source` channel in
 the [Convex Discord](https://discord.gg/convex).
 
@@ -57,27 +59,6 @@ To see how to contribute, visit [Contributing.md](./CONTRIBUTING.md).
 Instead of self-hosting via docker, you can run the Convex backend locally on
 your own machine.
 
-## Using prebuilt binaries
-
-You can download the latest precompiled binary release from
-[Releases](https://github.com/get-convex/convex-backend/releases). Only Apple
-x64, Apple Arm64 (Apple silicon), and Linux x64 binaries are currently available
-for download.
-
-_Note: On MacOS you might need to hold the `option` key and double click the
-binary file in Finder once, to circumvent the
-[Gatekeeper](https://support.apple.com/en-us/102445) warning._
-
-Then you can run it:
-
-```sh
-./convex-local-backend
-```
-
-Adjust the path based on where you downloaded the binary to or add it to your
-`PATH`. The backend will store its database in the directory where it is
-executed **from** (not where the binary file lives).
-
 ## Building from source
 
 To get started, clone this repo:

self-hosted/SELFHOSTING.md

@@ -22,24 +22,56 @@ Development of the Convex backend is led by the Convex team. We
 [love receiving feedback](https://discord.gg/convex). We keep this repository
 synced with any internal development work within a handful of days.
 
-# Self Hosting Guide
-
-First, you'll want to be get the
-[convex-local-backend binary](../crates/local_backend/README.md#running-the-convex-backend).
-
-You can either build from source or use the precompiled binaries. Note that in
-order to self host properly, you will need to clone the `convex-backend`
-repository and get set up with rust, in order to use some of the administrative
-executables.
-
-## Select an instance name
+# Self Hosting Via Docker [recommended]
 
 Select a name for your instance. In the cloud product, this takes the form of
 something like "flying-fox-123". You can select whatever you want here. A good
 practice would be to pick something that matches the domain you host from,
 though it is not critical.
 
-## Generate a new instance secret
+You'll need to have [Docker](https://docs.docker.com/desktop/) installed to run
+convex in Docker.
+
+```sh
+cd self-hosted
+# Pull the latest docker images
+docker compose pull
+# Run the containers
+docker compose up
+```
+
+Once your Convex backend is running in Docker, you can ask it to generate admin
+keys for use from the dashboard/CLI.
+
+```sh
+docker exec convex-local-backend ./generate_admin_key.sh
+```
+
+Visit the dashboard at `http://localhost:6791`. Using your admin key, push code
+to your backend. Admin key should be kept secure to just the developers who are
+administering the application on your backend.
+
+```sh
+cd your_project
+npm install
+npx convex dev --admin-key 'flying-fox-123|01c046ab1512d9306a6abda3eedec5dfe862f1fe0f66a5aee774fb9ae3fda87706facaf682b9d4f9209a05e038cbd6e9b8' --url "http://127.0.0.1:3210"
+```
+
+# Self Hosting Via Running Binary Directly
+
+### Get convex-local-backend Binary
+
+You can either [build from source](../README.md) or use the precompiled
+binaries. You can download the latest precompiled binary release from
+[Releases](https://github.com/get-convex/convex-backend/releases). If your
+platform is not supported, leave us a github issue. In the meantime, you can
+build from source.
+
+_Note: On MacOS you might need to hold the `option` key and double click the
+binary file in Finder once, to circumvent the
+[Gatekeeper](https://support.apple.com/en-us/102445) warning._
+
+### Generate a new instance secret
 
 Instance secret is the secret to the backend. Keep very safe and only accessible
 from the backend itself. Generate a new random instance secret with
@@ -51,7 +83,7 @@ cargo run -p keybroker --bin generate_secret
 It will look like this:
 `4361726e697461732c206c69746572616c6c79206d65616e696e6720226c6974`
 
-## Generate a new admin key
+### Generate a new admin key
 
 With the instance name and instance secret, generate an admin key. Admin key is
 required to push code to the backend and take other administrator operations.
@@ -63,7 +95,11 @@ cargo run -p keybroker --bin generate_key -- flying-fox-123 4361726e697461732c20
 It will look like
 `flying-fox-123|01c046ab1512d9306a6abda3eedec5dfe862f1fe0f66a5aee774fb9ae3fda87706facaf682b9d4f9209a05e038cbd6e9b8`
 
-## Run your backend instance
+### Run your backend instance
+
+Adjust the path based on where you downloaded the binary to or add it to your
+`PATH`. The backend will store its database in the current-working-directory
+(not where the binary file lives).
 
 Use the instance name and instance secret to start your backend.
 
@@ -75,30 +111,12 @@ You can run `./convex-local-backend --help` to see other options for things like
 changing ports, convex origin url, convex site url, local storage directories
 and other configuration.
 
-## Run your backend instance in Docker
-
-You'll need to have [Docker](https://docs.docker.com/desktop/) installed to run
-convex in Docker.
-
-```sh
-cd self-hosted
-# Pull the latest docker images
-docker compose pull
-# Run the containers
-docker compose up
-```
-
-Once your Convex backend is running in Docker, you can ask it to generate admin
-keys.
-
-```sh
-docker exec convex-local-backend ./generate_admin_key.sh
-```
+### Run the dashboard
 
-Visit the dashboard at `http://localhost:6791` and use the CLI to push functions
-with the `--admin-key $ADMIN_KEY` and `--url http://127.0.0.1:3210` flags.
+You can run the dashboard locally with `just rush install` and `npm run dev`
+from `npm-packages/dashboard-common`.
 
-## Push code to your backend
+### Use your backend.
 
 Using your admin key, push code to your backend. Admin key should be kept secure
 to just the developers who are administering the application on your backend.