Fauna GQL Upload is an npm package for managing FaunaDB resources inside your project, a sort of infrastructure as code (IaC) tool.

It is possible to use a local development instance of FaunaDB with Fauna GQL Upload using the Fauna Dev docker image.

This guide walks you through how to do that!

Before we start

Before you continue, you need to install Docker if you don't have it installed already.

You also need the FaunaDB CLI, which can be installed with the following command:

npm i -g fauna-shell

Now, we're ready to get started.

Install Fauna Dev

We can install Fauna Dev by pulling the docker image:

docker pull fauna/faunadb:latest

Now, let's run the container:

docker run --name faunadb -p 8443:8443 -p 8084:8084 -v /var/lib/faunadb fauna/faunadb

You should get some output and that eventually ends with FaunaDB is ready.

Create your database and keys

We now need to create a database and keys that point to that database. To do this, we need to set up fauna-shell to recognize the local FaunaDB instance.

First, add an endpoint that points to localhost:

fauna add-endpoint http://localhost:8443 --alias localhost --key secret

Then, we can create a database using that endpoint:

fauna create-database fauna-dev --endpoint=localhost

And then, we must create a key for that database:

fauna create-key fauna-dev --endpoint=localhost

A secret should be logged to the console, which we'll need in the next step.

Configure Fauna GQL Upload

We're getting to the endgame now. All that's left is to add the required environment variables to our .envfile, and scripts to start and stop our FaunaDB container.

In your project directory where you are using Fauna GQL Upload, open .env and add the following environment variable.

FGU_SECRET=[secret from the previous step]

Then open up your .fauna.json and add the following:

{
  "region": "local"
}

You can then start the FaunaDB instance by running:

docker start faunadb

And similarly, you can stop the instance by running:

docker stop faunadb

To see log output, simply append the -a flag: docker start faunadb -a. This will attach STDOUT/STDERR so you'll get the full terminal output.

🎉 And that's it! You should now be able to use Fauna GQL Upload with your local development installation of FaunaDB.

Final words

I hope this was helpful. If you have any questions, feel free to send me a DM on Twitter.

Also, don't forget to star Fauna GQL Upload on GitHub if you find it useful.