Local Development

When developing with FGA, you can either connect to a managed WorkOS FGA instance or run a local FGA instance using the fga-dev Docker image. Each option has its own advantages depending on your workflow. This guide will help you choose the best approach and walk you through setting up a local instance if that fits your needs.

Best for testing against production-like infrastructure and when you need persistent, shared data.

Best for isolated development and testing especially when you want to avoid using operation credits or need a clean environment for each run (such as in CI).

The fga-dev Docker image provides a fully self-contained FGA environment using SQLite and local caching. This setup is not intended for production but is fine for local development, CI, and integration testing. It is less scalable than the managed instance because it cannot handle high concurrency, complex models, or large datasets.

This guide will show you how to use the fga-dev Docker image to spin up an isolated FGA instance on your machine.

To start this guide, you’ll need:

• Docker installed on your machine
• A WorkOS account (for API keys)
• Your WorkOS API Key

Create a docker-compose.yaml:

version: '3.8'

services:
  fga-dev:
    image: public.ecr.aws/workos/fga-dev:latest-arm64
    user: root # Run as root to avoid permission issues with mounted volumes (non-production only)
    volumes:
      - fga-dev-volume:/data:rw,cached # Persist data between runs
    ports:
      - '8001:8001'
    environment:
      FGA_DEV_PORT: 8001
      FGA_DEV_AUTH_API_KEY: <your_workos_api_key> # Your staging WorkOS API key to authenticate the dev image
      FGA_DEV_TEST_API_KEY: test_key # A mock API key to authenticate FGA requests from your application

volumes:
  fga-dev-volume:

Usage

1. Start the server:

   docker compose up -d
   

2. Configure your app:

   • Point your application’s WorkOS SDK or CLI to the proper host.

   • Use test_key as the API key for FGA requests from your app.

     Environment	API Host
     Local machine	http://localhost:8001
     Separate Docker container	http://host.docker.internal:8001
     Same Docker Compose network	http://fga-dev:8001

3. Develop:

   Apply schemas, create warrants, and test locally. All data persists in the Docker volume.

   See Schema Management for how to apply a schema to your local instance and test authorization checks.

4. Shut down:

   docker compose down
   

5. Clear all data (optional):

   docker volume rm fga-dev-volume
   

You can also run the fga-dev image directly using docker run if you prefer not to use Docker Compose.

docker run -d \
  --name fga-dev \
  -p 8001:8001 \
  -e FGA_DEV_PORT=8001 \
  -e FGA_DEV_AUTH_API_KEY=<your_workos_api_key> \
  -e FGA_DEV_TEST_API_KEY=test_key \
  -v fga-dev-volume:/data:rw \
  --user root \
  public.ecr.aws/workos/fga-dev:latest-arm64

To stop and remove the container:

docker stop fga-dev && docker rm fga-dev

To remove the volume and reset all data:

docker volume rm fga-dev-volume

Consider the following best practices to ensure a smooth local development experience with FGA:

• Isolate test data: Use unique resource IDs to avoid collisions which is especially critical when working with shared or managed instances.
• Automate environment setup: Script the schema and warrant creation on first startup. This makes your development and CI pipelines more reliable and repeatable.
• Clean up regularly: Tear down and reset your environment when needed to avoid stale data and hidden state, which can lead to confusing behavior.
• Choose the right environment: Use a managed instance for shared, persistent testing; use the local fga-dev container for isolated development or CI.