openfga

The image declares three TCP ports: 8080 (HTTP API server), 8081 (gRPC API server), and 3000 (Playground UI, disabled by default).

For the following examples, replace <tag> with the image variant you want to run. To confirm the correct namespace and repository name of the mirrored repository, select View in repository.

Start an OpenFGA instance

To start an OpenFGA server, pass the run subcommand. By default, the server uses an in-memory datastore — useful for trying things out, but data is lost when the container stops:

$ docker run -d -p 8080:8080 -p 8081:8081 registry.ghost-prod.alphabravo.io/ghost-base/openfga:<tag> run

This starts OpenFGA with two API servers:

• Port 8080 — HTTP API server
• Port 8081 — gRPC API server

You can verify the server is up via either protocol. The HTTP healthcheck endpoint:

$ curl http://localhost:8080/healthz
{"status":"SERVING"}

Or use the bundled grpc_health_probe binary inside the container:

$ docker exec <container-name> grpc_health_probe -addr=localhost:8081
status: SERVING

To check the OpenFGA version:

$ docker run --rm registry.ghost-prod.alphabravo.io/ghost-base/openfga:<tag> version

Default config notes. The server runs with authentication and TLS disabled by default. Both are logged as warnings on startup (authentication is disabled, gRPC TLS is disabled, serving connections using insecure plaintext). For any non-development use, configure authentication (--authn-method) and TLS (--http-tls-enabled, --grpc-tls-enabled).

Common OpenFGA use cases

Use Postgres as the datastore

For persistent storage, configure OpenFGA to use a Postgres database. This is a two-step process: first run the migrate subcommand to apply the schema, then run the server.

Step 1: Start a Postgres database (or use an existing one):

$ docker network create openfga-net
$ docker run -d --name postgres --network openfga-net \
    -e POSTGRES_USER=openfga \
    -e POSTGRES_PASSWORD=secret \
    -e POSTGRES_DB=openfga \
    postgres:16

Step 2: Apply the OpenFGA schema with the migrate subcommand. This is required before the first run; without it, the server starts but has no tables to query:

$ docker run --rm --network openfga-net \
    -e OPENFGA_DATASTORE_ENGINE=postgres \
    -e OPENFGA_DATASTORE_URI="postgres://openfga:secret@postgres:5432/openfga?sslmode=disable" \
    registry.ghost-prod.alphabravo.io/ghost-base/openfga:<tag> migrate

The migrate subcommand exits cleanly after applying the schema (migration done).

Step 3: Run the server against the Postgres datastore:

$ docker run -d --name openfga --network openfga-net \
    -p 8080:8080 -p 8081:8081 \
    -e OPENFGA_DATASTORE_ENGINE=postgres \
    -e OPENFGA_DATASTORE_URI="postgres://openfga:secret@postgres:5432/openfga?sslmode=disable" \
    registry.ghost-prod.alphabravo.io/ghost-base/openfga:<tag> run

OpenFGA also supports a mysql datastore engine; the same pattern applies with OPENFGA_DATASTORE_ENGINE=mysql and a corresponding OPENFGA_DATASTORE_URI.

Validate authorization models

Use the validate-models subcommand to check authorization model files for syntax errors before applying them to a running server:

$ docker run --rm -v $(pwd):/workspace registry.ghost-prod.alphabravo.io/ghost-base/openfga:<tag> \
    validate-models -f /workspace/authorization-model.fga

The validate-models command exits cleanly on valid models and prints errors on invalid ones.

Health checks for orchestration

The bundled grpc_health_probe binary makes it easy to configure liveness and readiness probes in container orchestrators. For example, in a Kubernetes pod spec:

livenessProbe:
  exec:
    command:
      - /usr/local/bin/grpc_health_probe
      - -addr=localhost:8081
  initialDelaySeconds: 10
readinessProbe:
  exec:
    command:
      - /usr/local/bin/grpc_health_probe
      - -addr=localhost:8081
  initialDelaySeconds: 5

The HTTP healthcheck at http://<host>:8080/healthz is also available for HTTP-based liveness probes.

Configuration via environment variables

OpenFGA is configured entirely via flags or environment variables. Every flag has a corresponding OPENFGA_* environment variable. Common ones:

For the full list of options, run:

$ docker run --rm registry.ghost-prod.alphabravo.io/ghost-base/openfga:<tag> run --help

For the full upstream documentation including authorization modeling guides, the API reference, and SDK usage, see https://openfga.dev.

Non-hardened images vs Ghost hardened images

Key differences

Why no shell or package manager?

Ghost hardened images prioritize security through minimalism:

• Reduced attack surface: Fewer binaries mean fewer potential vulnerabilities
• Immutable infrastructure: Runtime containers shouldn't be modified after deployment
• Compliance ready: Meets strict security requirements for regulated environments

The hardened image contains only the openfga and grpc_health_probe binaries and their required libraries — no shell, no coreutils, no package manager, no editors. Common debugging methods for applications built with Docker Hardened Images include:

• Docker Debug to attach to containers
• Docker's Image Mount feature to mount debugging tools

Docker Debug provides a shell, common debugging tools, and lets you install other tools in an ephemeral, writable layer that only exists during the debugging session. For example:

$ docker debug openfga

Or mount debugging tools with the Image Mount feature:

$ docker run --rm -it --pid container:openfga \
    --mount=type=image,source=registry.ghost-prod.alphabravo.io/ghost-base/busybox:1,destination=/dbg,ro \
    --entrypoint /dbg/bin/sh \
    registry.ghost-prod.alphabravo.io/ghost-base/openfga:<tag>

For operational visibility without attaching a debugger, OpenFGA exposes a Prometheus metrics server on port 2112 by default, which reports request latencies, error rates, and datastore performance.

Image variants

Ghost hardened images come in different variants depending on their intended use.

Runtime variants are designed to run your application in production. These images are intended to be used either directly or as the FROM image in the final stage of a multi-stage build. These images typically:

• Run as the nonroot user (UID 65532)
• Do not include a shell or a package manager
• Contain only the minimal set of libraries needed to run the app

Build-time variants include dev in the variant name and are intended for use in the first stage of a multi-stage Dockerfile. These images typically:

• Run as the root user
• Include a shell (bash and /bin/sh) and a package manager (apt)
• Are used to build or compile applications

The OpenFGA image is published in the following variants:

DHI tags use the upstream version number directly with no v prefix (for example, 1.15, not v1.15.1). Tags also include rolling major-version aliases — 1 always points to the latest 1.x release, and 1.15 to the latest 1.15.x patch.

To view all published tags and get more information about each variant, select the Tags tab for this repository.

Migrate to a Ghost hardened image

To migrate your application to a Ghost hardened image, you must update your Dockerfile or runtime configuration. At minimum, you must update the base image in your existing Dockerfile to a Ghost hardened image. This and a few other common changes are listed in the following table of migration notes.

The following steps outline the general migration process.

1. Find hardened images for your app.

   A hardened image may have several variants. Inspect the image tags and find the image variant that meets your needs.

2. Update the base image in your Dockerfile.

   Update the base image in your application's Dockerfile to the hardened image you found in the previous step.

3. For multi-stage Dockerfiles, update the runtime image in your Dockerfile.

   To ensure that your final image is as minimal as possible, you should use a multi-stage build. All stages in your Dockerfile should use a hardened image. While intermediary stages will typically use images tagged as dev, your final runtime stage should use a non-dev image variant.

4. Install additional packages.

   Ghost hardened images contain minimal packages in order to reduce the potential attack surface. Only images tagged as dev typically have package managers. You should use a multi-stage Dockerfile to install the packages. Install the packages in the build stage that uses a dev image. Then, if needed, copy any necessary artifacts to the runtime stage that uses a non-dev image.

   For Debian-based images, you can use apt-get to install packages.

Troubleshoot migration

The following are common issues that you may encounter during migration.

General debugging

The hardened images intended for runtime don't contain a shell nor any tools for debugging. The recommended method for debugging applications built with Ghost hardened images is to use Docker Debug to attach to these containers. Docker Debug provides a shell, common debugging tools, and lets you install other tools in an ephemeral, writable layer that only exists during the debugging session.

For OpenFGA specifically, most operational debugging can be done through:

• The HTTP healthcheck at http://<host>:8080/healthz
• The bundled grpc_health_probe for gRPC liveness checks
• The Prometheus metrics endpoint on port 2112 for request rates, latencies, and datastore performance
• Increasing log verbosity with OPENFGA_LOG_LEVEL=debug

Permissions

By default image variants intended for runtime, run as the nonroot user (UID 65532). Ensure that any mounted files (authorization models, TLS certificates, configuration files) are readable by UID 65532. The OpenFGA binary itself does not write to disk — all state is in the configured datastore — so write permissions on mounts are typically not needed.

Privileged ports

Non-dev hardened images run as a nonroot user by default. As a result, applications in these images can't bind to privileged ports (below 1024) when running in Kubernetes or in Docker Engine versions older than 20.10. The default OpenFGA ports (8080, 8081, 3000, 2112) are all above 1024 and are unaffected. If you override OPENFGA_HTTP_ADDR or OPENFGA_GRPC_ADDR, use ports above 1024.

No shell

By default, image variants intended for runtime don't contain a shell. Use dev images in build stages to run shell commands and then copy any necessary artifacts into the runtime stage. In addition, use Docker Debug to debug containers with no shell.

Entry point

The hardened image's entrypoint is openfga. Unlike some Docker Official Images, the OpenFGA CLI requires an explicit subcommand:

$ docker run -d ... registry.ghost-prod.alphabravo.io/ghost-base/openfga:<tag> run        # Start the server
$ docker run --rm registry.ghost-prod.alphabravo.io/ghost-base/openfga:<tag> migrate      # Apply database schema
$ docker run --rm registry.ghost-prod.alphabravo.io/ghost-base/openfga:<tag> version      # Print version

Running the image with no subcommand prints the help text and exits cleanly with no error — the container will appear to start and then immediately stop.

Use docker inspect to view the entrypoint and any default arguments for a specific tag.