Fauna Dev

Fauna Dev is a Docker image that runs a single Fauna node, with GraphQL support, in your own environment for development and testing purposes.

We do not license or support use of Fauna Dev multi-node clusters.

Requirements

Fauna Dev has the following requirements:

  • Docker

  • CPU (minimum):

    • Dual-core

    • x86, AMD64, or ARM64

    • 2GHz clock speed

  • Memory: (minimum) 8GB RAM (physical).

  • Storage: Local, block-based storage device (SSD, hard disk, EBS, iSCSI).

    Network file systems, such as CIFS or NFS, are not supported.

Installation

  1. Pull the latest Docker container:

    docker pull fauna/faunadb:latest
  2. Verify that the container executes correctly:

    docker run fauna/faunadb --help
    FaunaDB Enterprise Docker Image
    
    Options:
     --help               Print this message and exit.
     --init               Initialize the node (default action).
     --no-init            Doesn't initialize the node.
     --join host[:port]   Join a cluster through an active node specified in host and port.
     --config <path>      Specify a custom config file. Should be accessible inside the docker image.

Ports

When you run Fauna Dev, you have to expose the ports for the services running inside the Docker container so that your system can access them.

The port most commonly used for the Fauna Dev database service, as used in examples on this page, is 8443.

The port most commonly used for the GraphQL API is 8084. This means that the GraphQL endpoints would be:

The Docker container’s database service and GraphQL endpoints are HTTP services that run without certificates installed; make sure that your client code uses the http scheme when making connections.

If you adjust the Docker invocations to use different ports, ensure that your client programs use the ports that you specify.

The docker command’s -p option lets you specify a mapping from your host computer’s to the container’s ports, using the syntax hostPort:containerPort. hostPort and containerPort can be a single port number, or a range expressed as low-high.

For example, to connect your host computer’s port 1234 to the container’s port 6789, you would use -p 1234:6789.

See the Docker docs for more information.

Run

There are several approaches to running Fauna Dev with Docker:

  1. As a single developer node, with ephemeral data:

    docker run --rm --name faunadb -p 8443:8443 -p 8084:8084 fauna/faunadb

    This command starts a Fauna Dev node and initializes the single-node cluster.

    Using this invocation, when the Docker container is stopped/killed, all of the data it contains is lost. This can be very useful for testing, where the database starts with a known state.
  2. As a single developer node, with persisted data:

    docker run --rm --name faunadb -p 8443:8443 -p 8084:8084 \
      -v <host-directory or named-volume>:/var/lib/faunadb \
      fauna/faunadb

    This command starts Fauna Dev with a specified folder or volume bound to the Docker container data folder. When the Docker container is stopped/killed, all of your data is maintained in the specified folder/volume.

  3. As a single developer node, with persisted data and logs:

    docker run --rm --name faunadb -p 8443:8443 -p 8084:8084 \
      -v <host-directory or named-volume>:/var/lib/faunadb \
      -v <host-directory>:/var/log/faunadb \
      fauna/faunadb

    This command starts Fauna Dev, binding a local folder/volume to the Docker container’s data folder, and another local folder/volume to the Docker container’s log folder. When the Docker container is stopped/killed, all of your data and logs are maintained in the specified folders/volumes.

  4. With managed configuration:

    docker run --rm --name faunadb -p 8443:8443 -p 8084:8084 \
      -v <host-directory or named-volume>:/var/lib/faunadb \
      -v <host-directory>:/var/log/faunadb \
      -v <path-to-config-file>:/etc/faunadb.yml \
      fauna/faunadb
      --config /etc/faunadb.yml

    This command starts Fauna Dev with path binds for the data, log, and configuration file, as well as specifying that the non-default configuration should be used.

    Here is an example configuration file. Adjust the configuration as appropriate:

    ---
    auth_root_key: secret
    cluster_name: fauna
    storage_data_path: /var/lib/faunadb
    log_path: /var/log/faunadb
    shutdown_grace_period_seconds: 0
    network_listen_address: 172.17.0.2
    network_broadcast_address: 172.17.0.2
    network_admin_http_address: 172.17.0.2
    network_coordinator_http_address: 172.17.0.2
We do not provide documentation for the configuration because we do not license Fauna for on-premise production use.

Connect

To connect to a Fauna Dev instance, using fauna-shell or a client application that uses one of our drivers, the options that need to be specified are:

Option Recommended value Description

secret

secret

The secret required to connect to a Fauna Dev instance. If you run Fauna Dev with your own faunadb.yml configuration, you can specify the secret to use.

domain

localhost

Only for fauna-shell, JavaScript driver, and Python driver

port

8443

Only for fauna-shell, JavaScript driver, and Python driver

scheme

http

Only for fauna-shell, JavaScript driver, and Python driver

endpoint

http://localhost:8443

Note that the recommended values are consistent with the Run section above. If you adjust the configuration, you need to use your changes to establish a connection.

For additional details on connecting to a Fauna instance, see Connections.

Is this article helpful? 

Tell Fauna how the article can be improved:
Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!