Light
Dark
System

Deploying EdgeDB to Fly.io

In this guide we show how to deploy EdgeDB using a Fly.io PostgreSQL cluster as the backend. The deployment consists of two apps: one running Postgres and the other running EdgeDB.

At the moment, it isn’t possible to expose Fly-hosted EdgeDB instances to the public internet, only internally to other Fly projects. As such your application must also be hosted on Fly.

  • Fly.io account

  • flyctl CLI (install)

Every Fly.io app must have a globally unique name, including service VMs like Postgres and EdgeDB. Pick a name and assign it to a local environment variable called EDB_APP. In the command below, replace myorg-edgedb with a name of your choosing.

Copy
$ 
EDB_APP=myorg-edgedb
Copy
$ 
flyctl apps create --name $EDB_APP
New app created: myorg-edgedb

Now let’s use the read command to securely assign a value to the PASSWORD environment variable.

Copy
$ 
echo -n "> " && read -s PASSWORD

Now let’s assign this password to a Fly secret, plus a few other secrets that we’ll need. There are a couple more environment variables we need to set:

Copy
$ 
  
  
  
  
  
flyctl secrets set \
  EDGEDB_PASSWORD="$PASSWORD" \
  EDGEDB_SERVER_BACKEND_DSN_ENV=DATABASE_URL \
  EDGEDB_SERVER_TLS_CERT_MODE=generate_self_signed \
  EDGEDB_SERVER_PORT=8080 \
  --app $EDB_APP
Secrets are staged for the first deployment

Let’s discuss what’s going on with all these secrets.

  • The EDGEDB_SERVER_BACKEND_DSN_ENV tells the EdgeDB container where to look for the PostgreSQL connection string (more on that below)

  • The EDGEDB_SERVER_TLS_CERT_MODE tells EdgeDB to auto-generate a self-signed TLS certificate.

    You may instead choose to provision a custom TLS certificate. In this case, you should instead create two other secrets: assign your certificate to EDGEDB_SERVER_TLS_CERT and your private key to EDGEDB_SERVER_TLS_KEY.

  • Lastly, EDGEDB_SERVER_PORT tells EdgeDB to listen on port 8080 instead of the default 5656, because Fly.io prefers 8080 for its default health checks.

Finally, let’s scale the VM as EdgeDB requires a little bit more than the default Fly.io VM side provides:

Copy
$ 
flyctl scale vm shared-cpu-1x --memory=1024 --app $EDB_APP
Scaled VM Type to
 shared-cpu-1x
      CPU Cores: 1
         Memory: 1 GB

Now we need to provision a PostgreSQL cluster and attach it to the EdgeDB app.

If you have an existing PostgreSQL cluster in your Fly.io organization, you can skip to the attachment step.

Then create a new PostgreSQL cluster. This may take a few minutes to complete.

Copy
$ 
PG_APP=myorg-postgres
Copy
$ 
flyctl pg create --name $PG_APP --vm-size dedicated-cpu-1x
? Select region: sea (Seattle, Washington (US))
? Specify the initial cluster size: 1
? Volume size (GB): 10
Creating postgres cluster myorg-postgres in organization personal
Postgres cluster myorg-postgres created
    Username:    postgres
    Password:    <random password>
    Hostname:    myorg-postgres.internal
    Proxy Port:  5432
    PG Port: 5433
Save your credentials in a secure place, you won't be able to see them
again!
Monitoring Deployment
...
--> v0 deployed successfully

Attach the PostgreSQL cluster to the EdgeDB app:

Copy
$ 
PG_ROLE=myorg_edgedb
Copy
$ 
  
  
flyctl pg attach "$PG_APP" \
  --database-user "$PG_ROLE" \
  --app $EDB_APP
Postgres cluster myorg-postgres is now attached to myorg-edgedb
The following secret was added to myorg-edgedb:
  DATABASE_URL=postgres://...

Lastly, EdgeDB needs the ability to create Postgres databases and roles, so let’s adjust the permissions on the role that EdgeDB will use to connect to Postgres:

Copy
$ 
  
echo "alter role \"$PG_ROLE\" createrole createdb; \quit" \
  | flyctl pg connect --app $PG_APP
...
ALTER ROLE

Everything is set! Time to start EdgeDB.

Copy
$ 
  
flyctl deploy --image=edgedb/edgedb \
  --remote-only --app $EDB_APP
...
1 desired, 1 placed, 1 healthy, 0 unhealthy
--> v0 deployed successfully

That’s it! You can now start using the EdgeDB instance located at edgedb://myorg-edgedb.internal in your Fly.io apps.

If deploy did not succeed:

  1. make sure you’ve scaled the EdgeDB VM

  2. re-run the deploy command

  3. check the logs for more information: flyctl logs --app $EDB_APP

Now we need to persist the auto-generated TLS certificate to make sure it survives EdgeDB app restarts. (If you’ve provided your own certificate, skip this step).

Copy
$ 
EDB_SECRETS="EDGEDB_SERVER_TLS_KEY EDGEDB_SERVER_TLS_CERT"
Copy
$ 
  
  
flyctl ssh console --app $EDB_APP -C \
  "edgedb-show-secrets.sh --format=toml $EDB_SECRETS" \
| tr -d '\r' | flyctl secrets import --app $EDB_APP

Let’s construct the DSN (AKA “connection string”) for our instance. DSNs have the following format: edgedb://<username>:<password>@<hostname>:<port>. We can construct the DSN with the following components:

  • <username>: the default value — edgedb

  • <password>: the value we assigned to $PASSWORD

  • <hostname>: the name of your EdgeDB app (stored in the $EDB_APP environment variable) suffixed with .internal. Fly uses this synthetic TLD to simplify inter-app communication. Ex: myorg-edgedb.internal.

  • <port>: 8080, which we configured earlier

We can construct this value and assign it to a new environment variable called DSN.

Copy
$ 
DSN=edgedb://edgedb:$PASSWORD@$EDB_APP.internal:8080

Consider writing it to a file to ensure the DSN looks correct. Remember to delete the file after you’re done. (Printing this value to the terminal with echo is insecure and can leak your password into shell logs.)

Copy
$ 
echo $DSN > dsn.txt
Copy
$ 
open dsn.txt
Copy
$ 
rm dsn.txt

To connect to this instance from another Fly app (say, an app that runs your API server) set the value of the EDGEDB_DSN secret inside that app.

Copy
$ 
  
  
flyctl secrets set \
  EDGEDB_DSN=$DSN \
  --app my-other-fly-app

We’ll also set another variable that will disable EdgeDB’s TLS checks. Inter-application communication is secured by Fly so TLS isn’t vital in this case; configuring TLS certificates is also beyond the scope of this guide.

Copy
$ 
  
flyctl secrets set EDGEDB_CLIENT_TLS_SECURITY=insecure \
  --app my-other-fly-app

You can also set these values as environment variables inside your fly.toml file, but using Fly’s built-in secrets functionality is recommended.

If you need to access EdgeDB from outside the Fly.io network, you’ll need to configure the Fly.io proxy to let external connections in.

First, save the EdgeDB app config in an empty directory:

Copy
$ 
flyctl config save -a $EDB_APP

A fly.toml file will be created upon result. Let’s make sure our [[services]] section looks something like this:

Copy
[[services]]
    http_checks = []
    internal_port = 8080
    processes = ["app"]
    protocol = "tcp"
    script_checks = []
    [services.concurrency]
        hard_limit = 25
        soft_limit = 20
        type = "connections"

    [[services.ports]]
        port = 5656

    [[services.tcp_checks]]
        grace_period = "1s"
        interval = "15s"
        restart_limit = 0
        timeout = "2s"

In the same directory, redeploy the EdgeDB app. This makes the EdgeDB port available to the outside world. You can now access the instance from any host via the following public DSN: edgedb://edgedb:$PASSWORD@$EDB_APP.fly.dev.

To secure communication between the server and the client, you will also need to set the EDGEDB_TLS_CA environment secret in your application. You can securely obtain the certificate content by running:

Copy
$ 
  
flyctl ssh console -a $EDB_APP \
  -C "edgedb-show-secrets.sh --format=raw EDGEDB_SERVER_TLS_CERT"

To access the EdgeDB instance from local development machine/laptop, install the Wireguard VPN and create a tunnel, as described on Fly’s Private Networking docs.

Once it’s up and running, use edgedb instance link to create a local alias to the remote instance.

Copy
$ 
  
  
  
  
edgedb instance link \
  --trust-tls-cert \
  --dsn $DSN \
  --non-interactive \
  fly
Authenticating to edgedb://edgedb@myorg-edgedb.internal:5656/edgedb
Successfully linked to remote instance. To connect run:
  edgedb -I fly

You can now run CLI commands against this instance by specifying it by name with -I fly; for example, to apply migrations:

Copy
$ 
edgedb -I fly migrate
Light
Dark
System