update fly.io self-hosting docs (#34141)

Updating fly.io docs

GitOrigin-RevId: 942dbde3e67e2564200c4cf48570c7c28de638c5

Author: ianmacartney

self-hosted/SELFHOSTING.md

@@ -18,9 +18,9 @@ Community support is available for self-hosted Convex in the `#open-source`
 channel in the [Convex Discord](https://discord.gg/convex).
 
 Development of the Convex backend is led by the Convex team. We
-[welcome bug fixes](./CONTRIBUTING.md) and
-[love receiving feedback](https://discord.gg/convex). We keep this repository
-synced with any internal development work within a handful of days.
+[welcome bug fixes](https://github.com/get-convex/convex-backend/blob/main/crates/convex/CONTRIBUTING.md)
+and [love receiving feedback](https://discord.gg/convex). We keep this
+repository synced with any internal development work within a handful of days.
 
 # Self Hosting Via Docker
 
@@ -35,6 +35,8 @@ docker compose pull
 docker compose up
 ```
 
+Note: if you see permissions issues, try `docker logout ghcr.io`.
+
 Once your Convex backend is running in Docker, you can ask it to generate admin
 keys for use from the dashboard/CLI.
 
@@ -81,14 +83,39 @@ connect to Postgres.
 
 # Self Hosting with [Fly.io](https://fly.io/)
 
-From the self-hosted directory, deploy the backend.
+## Setup
+
+Copy the
+[`self-hosted` files](https://github.com/get-convex/convex-backend/tree/main/self-hosted)
+to your local machine. You don't need to copy it into your project directory,
+but you can.
 
 ```sh
-fly launch
+npx degit get-convex/convex-backend/self-hosted ./self-hosted
+cd self-hosted
 ```
 
-Note the URL of the app that gets printed out, which will be of the form
-`https://<app-name>.fly.dev` (no trailing slash).
+Note: `degit` is a tool for copying files from git repositories.
+
+## Deploying the backend to Fly.io
+
+The backend "deploy" can mean two things:
+
+1. Deploying the Convex docker image to Fly.io.
+2. Deploying your app's Convex functions to the fly machine running Convex.
+
+Steps:
+
+1. Deploy the backend to Fly.io.
+
+   ```sh
+   fly launch
+   ```
+
+   Future deployments can be done with `fly deploy`.
+
+2. Note the URL of the app that gets printed out, which will be of the form
+   `https://<app-name>.fly.dev` (no trailing slash).
 
 In the fly.toml file, change the env variables `CONVEX_CLOUD_ORIGIN` and
 `CONVEX_SITE_ORIGIN` to:
@@ -105,41 +132,58 @@ fly deploy
 ```
 
 Copy and paste the fly url to set `NEXT_PUBLIC_DEPLOYMENT_URL` in the
-dashboard/fly.toml file.
+dashboard/fly.toml file. 3. Generate an admin key.
 
 ```sh
-cd dashboard
-fly launch
+fly ssh console --app self-hosted-backend --command "./generate_admin_key.sh"
 ```
 
-Visit the dashboard at the url output from the fly deploy command. Generate
-admin key to login to the dashboard.
+Unless you edited the app's `fly.toml`, the name is `self-hosted-backend`. If
+you specified a different name, replace `self-hosted-backend` with it.
 
-```sh
-fly ssh console --command "./generate_admin_key.sh"
-```
+This admin key will be used to authorize the CLI and access the dashboard.
 
-In your frontend app directory
+4. Inside your app, create a `.env.local` file with the following variables:
 
-```sh
-npm install convex@alpha
-```
+   ```sh
+   CONVEX_SELF_HOST_URL='<url-to-your-fly-backend>'
+   CONVEX_SELF_HOST_ADMIN_KEY='<your-admin-key>'
+   ```
 
-Write these environment variables to .env.local
+5. To deploy your Convex functions to the backend, you'll use the `convex` CLI.
 
-```sh
-CONVEX_SELF_HOST_URL='<NEXT_PUBLIC_DEPLOYMENT_URL>'
-CONVEX_SELF_HOST_ADMIN_KEY='<your-admin-key>'
-```
+   In your frontend app directory, install `convex`.
 
-Push your Convex functions
+   ```sh
+   npm install convex@alpha
+   ```
 
-```sh
-npx convex self-host dev
-```
+   To continuously deploy code for development:
+
+   ```sh
+   npx convex self-host dev
+   ```
+
+   This will continuously deploy your functions as you edit them. It will also
+   set environment variables for your frontend, like`VITE_CONVEX_URL`. If you
+   only want to deploy once, run `npx convex self-host dev --once`.
+
+   To deploy code once, e.g. for production:
 
-Visit the dashboard - you should see your functions and be able to edit data,
-run functions, etc.
+   ```sh
+   npx convex self-host deploy --env-file <path to env file>
+   ```
+
+   If you don't want to ues a path, call it with the env variables set. It will
+   not read any .env file by default.
+
+   **Note:** It's up to you whether a backend is for development or production.
+   There is no distinction within the instance. If you only have one backend,
+   you can run `npx convex self-host dev` or `npx convex self-host deploy`
+   depending on whether you want it to live-update or not.
+
+   An extension of this is that you can have many backends for staging or
+   previews. The difference will be in the environment variables.
 
 ### HTTP Actions
 
@@ -150,6 +194,34 @@ example:
 - And you have an HTTP action named `/sendEmail`
 - You would call it at `https://self-hosted-backend.fly.dev/http/sendEmail`
 
+## Deploying the dashboard to Fly.io
+
+The dashboard allows you to see logs, read/write data, run functions, and more.
+You can run the dashboard locally (see [SELFHOSTING.md](SELFHOSTING.md)), or
+also deploy it to Fly.io.
+
+1. Go into the dashboard directory where you copied the self-hosted files.
+
+   ```sh
+   cd self-hosted/dashboard
+   ```
+
+2. Update `NEXT_PUBLIC_DEPLOYMENT_URL` in the dashboard/fly.toml file to the url
+   of your fly-hosted backend, if you haven't already.
+
+3. Deploy the dashboard to Fly.io.
+
+   ```sh
+   fly launch
+   ```
+
+   You should now be able to visit the dashboard at the url output by fly.
+
+4. Visit the dashboard and enter the admin key. To log in, it will need the
+   admin key you generated earlier.
+
+   You should see your tables, see and run functions, etc.
+
 # Self Hosting on Postgres with [Neon](https://neon.tech)
 
 Create a project on Neon. Copy the connection string from the Neon dashboard.