Set up Fauna GQL Upload with Fauna Dev

Subscribe to my newsletter and never miss my upcoming articles

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

The new version added the possibility of setting custom endpoints for the FaunaDB driver and GraphQL import. That means, it is now possible to run a local FaunaDB instance, using Fauna Dev, a docker image containing a single database node, together with Fauna GQL Upload.

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 variables.

FGU_SECRET=[secret from the previous step]

Notice how we don't append /import or /graphql to the GraphQL endpoint. This is because Fauna GQL Upload appends these paths automatically when uploading the schema and running code generation.

You also have the option of changing the name of the environment variables if you don't like the defaults. Just add the apiEndpointEnv and/or graphqlEndpointEnv properties in .fauna.json.

Then, open up your package.json and add a script for starting and stopping your FaunaDB instance, like so:

"scripts": {
  "fauna-dev:start": "docker start faunadb",
  "fauna-dev:stop": "docker stop faunadb"

And then, whenever you need to start your development database, you can just run yarn fauna-dev:start to, well, start your container. Similarly, you can run yarn fauna-dev:stop to stop your container.

The start script will start your container as a background process, meaning you won't get any output in the terminal. This can be preferable since it eliminates a lot of clutter. But it can also be useful to know what's going on with the database. So to enable logging, simply replace the start script with: docker start faunadb -a. This will attach STDOUT/STDERR so you'll get the full terminal output.

Adding the start and stop scripts are completely optional but can be nice to have. It is of course possible to simply run docker start faunadb or docker stop faunadb directly in your terminal.

🎉 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.

No Comments Yet