Running a SurrealDB Instance on Fly.io

Tutorial by Mark Lussier.
Edit this tutorial on GitHub.

These are the steps for getting a surrealdb instance running on fly.io and connecting to it. This is heavily based off of steps posted in the surrealdb discord by rvdende. View Original Post.

These steps work just fine for the hobby (pay as you go) plan.

HEADS UP By default this will create an instance on a single shared cpu with 256m memory. This is pretty darn small to do anything but experiment, but its free. You can scale your instance to something more useable by visiting the https://fly.io/apps/<appname>/scale. Obviously scaling to larger instances will incur higher costs, please refer to fly.io pricing

Installing fly.io client

source: fly.io docs

brew install flyctl

Optionally create a free account if needed

source: fly.io docs

flyctl auth signup

source: fly.io docs

flyctl auth login

Create a Dockerfile to run SurrealDB

Create a directory locally, cd into it and create a new Dockerfile. Note we aren't providing a root user username/password to the start command, we will be providing those as environment variables.

FROM surrealdb/surrealdb:latest
EXPOSE 8080
CMD ["start", "--bind", "0.0.0.0:8080", "file://data/srdb.db"]

Launch your Instance.. sort of :)

fly launch

You will be prompted with various questions. Give your app a memorable name since it will be used in the URL. Pick a region close to you and most importantly, answer NO when prompted if you wish to deploy immediately.

Create a volume

We need to create a volume for surreal to write the database to. Lets create a small 1g volume. Right now you can not scale a volume (you need to create a new one), but fly.io is working on supporting this. You can get up a total of 3g of persistent volume storage (total) for free.

fly volumes create data --region <region> --size 1

Now lets edit the fly.toml file that was created by fly launch. Put this at the end, no indentations or spaces.

[mounts]
source="data"
destination="/data"

Secrets

Now lets add our username and password as secrets. You can see the environment variables surrealdb supports by running surreal start -h

fly secrets set USER=root
fly secrets set PASS=<passwordhere>

Let's Deploy

fly deploy

Connecting

Now that your surrealdb instance is up and running, you need to be able to connect to it. Even though we exposed port 8080 in the Dockerfile, fly will map that appropriatly to port 80/443.

If you're connecting via a websocket client library, surrealdb-go in my case, you would connect with the following. Note the use of wss://

db, err := surrealdb.New("wss://<appname>.fly.dev/rpc")
if err != nil {
	fmt.Printf("error creating socket: %s", err)
	os.Exit(2)
}

Surreal sql Command

If you're connecting via the surreal cli, use a connection string with --conn https://<appname>.fly.dev. Please don't forget to pass --user/--pass with the values you used when creating secrets.

Third Party tools such as rvdende's surrealreact

When creating a connection, specify the host as https://<appname>.fly.dev/rpc