The Fauna service will be ending on May 30, 2025.

For more information on the service wind down, see our announcement and the Fauna Service End-of-Life FAQ.

Develop locally using Docker

Fauna Dev is a Docker image that runs a single Fauna node in your environment, which you can use for development and testing. Fauna Dev isn’t licensed or supported for a multinode cluster.

Requirements

  • Docker

  • CPU:

    • Dual-core

    • x86, AMD64, or ARM64

    • 2GHz clock speed

  • RAM: 8 GB

  • Storage: Local, block-based storage device:

    • SSD

    • hard disk

    • EBS

    • iSCSI

      Network file systems, such as CIFS and NFS, aren’t supported.

Installation

  1. Pull the latest Fauna Docker container:

    docker pull fauna/faunadb:latest

  2. Verify the installation:

    docker run fauna/faunadb --help

Port assignment

When you run Fauna Dev, you must expose the ports for the services running inside the Docker container so they’re accessible.

The most commonly used Fauna Dev database service port, which is used in the following examples, is port 8443.

If you change the Docker command to use a different port, ensure that your client programs use the same port.

The docker command -p option allows you to map your host computer port to the container port using the hostPort:containerPort syntax. hostPort and containerPort can be a single port number or a range expressed as low-high.

For example, to connect your host computer port 1234 to container port 6789, use -p 1234:6789.

See the Docker docs for more information.

Run Fauna Dev

The following describes several approaches to running Fauna Dev with Docker.

Note that configuration documentation isn’t provided because on-premise production use isn’t licensed.

Single developer node with ephemeral data

This command starts a Fauna Dev node and initializes a single-node cluster, which is useful for testing when the database starts in a known state.

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

Using this command when the Docker container is stopped or killed causes all the data to be lost.

Single developer node with persisted data

This command starts Fauna Dev with a folder or volume bound to the Docker container data folder.

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

When the Docker container is stopped or killed, all your data is persisted in the given folder or volume.

Single developer node with persisted data and logs

This command starts Fauna Dev, binding a local folder or volume to the Docker container data folder and another local folder or volume to the Docker container log folder.

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

When the Docker container is stopped or killed, all of your data and logs are maintained in the given folders or volumes.

Managed configuration

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

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

 

Example:

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

Connect

To connect to a Fauna Dev instance using the Fauna CLI or a Fauna driver, set the following options:

Option Recommended value Description

secret

Saved secret.

The secret required to connect to a Fauna Dev instance.

Fauna Dev instances include a top-level key with the admin role. By default, the key’s secret is secret. If you run Fauna Dev with your own faunadb.yml configuration, you can use auth_root_key to specify the secret to use.

You can use the top-level key as a scoped key to access all databases for the instance.

domain

localhost

fauna-shell, JavaScript, and Python only.

port

8443

fauna-shell, JavaScript, and Python only.

scheme

http

fauna-shell, JavaScript, and Python only.

endpoint

\reference:http///localhost:8443

Go only.

Note that the recommended values are consistent with the preceding Run Fauna Dev description. If you change the configuration, use settings in the configuration file to establish a connection.

For more information on configuring a connection to a Fauna instance, see the JavaScript driver Client Configuration README file.

\