From e164e44bbdbb1da149b181d3e17b89d4d6904200 Mon Sep 17 00:00:00 2001 From: Raghd Hamzeh Date: Tue, 21 Jan 2025 00:12:41 -0500 Subject: [PATCH] feat: autogenerated configuration page --- .../setup-openfga/configuration.mdx | 218 ++++++++++++++++++ .../setup-openfga/configure-openfga.mdx | 56 +---- docs/sidebars.js | 5 + src/css/custom.css | 2 + 4 files changed, 236 insertions(+), 45 deletions(-) create mode 100644 docs/content/getting-started/setup-openfga/configuration.mdx diff --git a/docs/content/getting-started/setup-openfga/configuration.mdx b/docs/content/getting-started/setup-openfga/configuration.mdx new file mode 100644 index 000000000..1f79d9acc --- /dev/null +++ b/docs/content/getting-started/setup-openfga/configuration.mdx @@ -0,0 +1,218 @@ +--- +title: OpenFGA Configuration Options +description: Configuring Options for the OpenFGA Server +sidebar_position: 1 +slug: /getting-started/setup-openfga/configuration +--- +import { + RelatedSection, +} from "@components/Docs"; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# OpenFGA Configuration Options + +## Passing in the options + +You can configure the OpenFGA server in three ways: + +- Using a configuration file. +- Using environment variables. +- Using command line parameters. + +If the same option is configured in multiple ways the command line parameters will take precedence over environment variables, which will take precedence over the configuration file. + +The configuration options and their default values are listed in the table below based on the [config-schema.json](https://github.com/openfga/openfga/blob/main/.config-schema.json). + + + + +You can configure the OpenFGA server with a `config.yaml` file, which can be specified in either: +- `/etc/openfga` +- `$HOME/.openfga` +- `.` (i.e., the current working directory). + +The OpenFGA server will search for the configuration file in the above order. + +Here is a sample configuration to run OpenFGA with a Postgres database and using a preshared key for authentication: + +```yaml +datastore: + engine: postgres + uri: postgres://user:password@localhost:5432/mydatabase +authn: + method: preshared + preshared: + keys: ["key1", "key2"] +playground: + enabled: false +``` + + + + + +The OpenFGA server supports **environment variables** for configuration, and they will take priority over your configuration file. +Each variable must be prefixed with `OPENFGA_` and followed by your option in uppercase (`datastore.engine` becomes `OPENFGA_DATASTORE_ENGINE`), e.g. + +```shell +# Running as a binary +export OPENFGA_DATASTORE_ENGINE=postgres +export OPENFGA_DATASTORE_URI='postgres://postgres:password@postgres:5432/postgres?sslmode=disable' +export OPENFGA_AUTHN_METHOD=preshared +export OPENFGA_AUTHN_PRESHARED_KEYS='key1,key2' +export OPENFGA_PLAYGROUND_ENABLED=false +openfga run + +# Running in docker +docker run docker.io/openfga/openfga:latest \ + -e OPENFGA_DATASTORE_ENGINE=postgres \ + -e OPENFGA_DATASTORE_URI='postgres://postgres:password@postgres:5432/postgres?sslmode=disable' \ + -e OPENFGA_AUTHN_METHOD=preshared \ + -e OPENFGA_AUTHN_PRESHARED_KEYS='key1,key2' \ + -e OPENFGA_PLAYGROUND_ENABLED=false \ + run +``` + + + + + +Command line parameters take precedence over environment variables and options in the configuration file. They are prefixed with `--` (`OPENFGA_DATASTORE_ENGINE` becomes `--datastore-engine`), e.g. + +```shell +# Running as a binary +openfga run \ + --datastore-engine postgres \ + --datastore-uri 'postgres://postgres:password@postgres:5432/postgres?sslmode=disable' \ + --authn-method=preshared \ + --authn-preshared-keys='key1,key2' \ + --playground-enabled=false + +# Running in docker +docker run docker.io/openfga/openfga:latest run \ + --datastore-engine postgres \ + --datastore-uri 'postgres://postgres:password@postgres:5432/postgres?sslmode=disable' \ + --authn-method=preshared \ + --authn-preshared-keys='key1,key2' \ + --playground-enabled=false +``` + + + + +## List of options + +The following table lists the configuration options for the OpenFGA server, based on the [config-schema.json](https://github.com/openfga/openfga/blob/main/.config-schema.json). + +| Config File | Env Var | Flag Name | Type | Description | Default Value | +|-------------|---------|-----------|------|-------------|---------------| +| `maxTuplesPerWrite` |
OPENFGA_MAX_TUPLES_PER_WRITE
| `max-tuples-per-write` | integer | The maximum allowed number of tuples per Write transaction. | `100` | +| `maxTypesPerAuthorizationModel` |
OPENFGA_MAX_TYPES_PER_AUTHORIZATION_MODEL
| `max-types-per-authorization-model` | integer | The maximum allowed number of type definitions per authorization model. | `100` | +| `maxAuthorizationModelSizeInBytes` |
OPENFGA_MAX_AUTHORIZATION_MODEL_SIZE_IN_BYTES
| `max-authorization-model-size-in-bytes` | integer | The maximum size in bytes allowed for persisting an Authorization Model (default is 256KB). | `262144` | +| `maxConcurrentReadsForCheck` |
OPENFGA_MAX_CONCURRENT_READS_FOR_CHECK
| `max-concurrent-reads-for-check` | integer | The maximum allowed number of concurrent reads in a single Check query (default is MaxUint32). | `4294967295` | +| `maxConcurrentReadsForListObjects` |
OPENFGA_MAX_CONCURRENT_READS_FOR_LIST_OBJECTS
| `max-concurrent-reads-for-list-objects` | integer | The maximum allowed number of concurrent reads in a single ListObjects query (default is MaxUint32). | `4294967295` | +| `maxConcurrentReadsForListUsers` |
OPENFGA_MAX_CONCURRENT_READS_FOR_LIST_USERS
| `max-concurrent-reads-for-list-users` | integer | The maximum allowed number of concurrent reads in a single ListUsers query (default is MaxUint32). | `4294967295` | +| `maxConcurrentChecksPerBatchCheck` |
OPENFGA_MAX_CONCURRENT_CHECKS_PER_BATCH_CHECK
| `max-concurrent-checks-per-batch-check` | integer | The maximum number of checks that can be processed concurrently in a batch check request. | `50` | +| `maxChecksPerBatchCheck` |
OPENFGA_MAX_CHECKS_PER_BATCH_CHECK
| `max-checks-per-batch-check` | integer | The maximum number of tuples allowed in a BatchCheck request. | `50` | +| `maxConditionEvaluationCost` |
OPENFGA_MAX_CONDITION_EVALUATION_COST
| `max-condition-evaluation-cost` | integer | The maximum cost for CEL condition evaluation before a request returns an error (default is 100). | `100` | +| `changelogHorizonOffset` |
OPENFGA_CHANGELOG_HORIZON_OFFSET
| `changelog-horizon-offset` | integer | The offset (in minutes) from the current time. Changes that occur after this offset will not be included in the response of ReadChanges. | | +| `resolveNodeLimit` |
OPENFGA_RESOLVE_NODE_LIMIT
| `resolve-node-limit` | integer | Maximum resolution depth to attempt before throwing an error (defines how deeply nested an authorization model can be before a query errors out). | `25` | +| `resolveNodeBreadthLimit` |
OPENFGA_RESOLVE_NODE_BREADTH_LIMIT
| `resolve-node-breadth-limit` | integer | Defines how many nodes on a given level can be evaluated concurrently in a Check resolution tree. | `100` | +| `listObjectsDeadline` |
OPENFGA_LIST_OBJECTS_DEADLINE
| `list-objects-deadline` | string (duration) | The timeout deadline for serving ListObjects requests | `3s` | +| `listObjectsMaxResults` |
OPENFGA_LIST_OBJECTS_MAX_RESULTS
| `list-objects-max-results` | integer | The maximum results to return in the non-streaming ListObjects API response. If 0, all results can be returned | `1000` | +| `listUsersDeadline` |
OPENFGA_LIST_USERS_DEADLINE
| `list-users-deadline` | string (duration) | The timeout deadline for serving ListUsers requests. If 0s, there is no deadline | `3s` | +| `listUsersMaxResults` |
OPENFGA_LIST_USERS_MAX_RESULTS
| `list-users-max-results` | integer | The maximum results to return in ListUsers API response. If 0, all results can be returned | `1000` | +| `requestDurationDatastoreQueryCountBuckets` |
OPENFGA_REQUEST_DURATION_DATASTORE_QUERY_COUNT_BUCKETS
| `request-duration-datastore-query-count-buckets` | []integer | Datastore query count buckets used to label the histogram metric for measuring request duration. | `50,200` | +| `requestDurationDispatchCountBuckets` |
OPENFGA_REQUEST_DURATION_DISPATCH_COUNT_BUCKETS
| `request-duration-dispatch-count-buckets` | []integer | Dispatch count buckets used to label the histogram metric for measuring request duration. | `50,200` | +| `contextPropagationToDatastore` |
OPENFGA_CONTEXT_PROPAGATION_TO_DATASTORE
| `context-propagation-to-datastore` | boolean | Propagate a requests context to the datastore implementation. Settings this parameter can result in connection pool draining on request aborts and timeouts. | `false` | +| `experimentals` |
OPENFGA_EXPERIMENTALS
| `experimentals` | []string (enum=[`enable-check-optimizations`, `enable-access-control`]) | a list of experimental features to enable | `` | +| `accessControl.enabled` |
OPENFGA_ACCESS_CONTROL_ENABLED
| `access-control-enabled` | boolean | Enable/disable the access control store. | `false` | +| `accessControl.storeId` |
OPENFGA_ACCESS_CONTROL_STORE_ID
| `access-control-store-id` | string | The storeId to be used for the access control store. | | +| `accessControl.modelId` |
OPENFGA_ACCESS_CONTROL_MODEL_ID
| `access-control-model-id` | string | The modelId to be used for the access control store. | | +| `playground.enabled` |
OPENFGA_PLAYGROUND_ENABLED
| `playground-enabled` | boolean | Enable/disable the OpenFGA Playground. | `true` | +| `playground.port` |
OPENFGA_PLAYGROUND_PORT
| `playground-port` | integer | The port to serve the local OpenFGA Playground on. | `3000` | +| `profiler.enabled` |
OPENFGA_PROFILER_ENABLED
| `profiler-enabled` | boolean | Enabled/disable pprof profiling. | `false` | +| `profiler.addr` |
OPENFGA_PROFILER_ADDR
| `profiler-addr` | string | The host:port address to serve the pprof profiler server on. | `:3001` | +| `datastore.engine` |
OPENFGA_DATASTORE_ENGINE
| `datastore-engine` | string (enum=[`memory`, `postgres`, `mysql`, `sqlite`]) | The datastore engine that will be used for persistence. | `memory` | +| `datastore.uri` |
OPENFGA_DATASTORE_URI
| `datastore-uri` | string | The connection uri to use to connect to the datastore (for any engine other than 'memory'). | | +| `datastore.username` |
OPENFGA_DATASTORE_USERNAME
| `datastore-username` | string | The connection username to connect to the datastore (overwrites any username provided in the connection uri). | | +| `datastore.password` |
OPENFGA_DATASTORE_PASSWORD
| `datastore-password` | string | The connection password to connect to the datastore (overwrites any password provided in the connection uri). | | +| `datastore.maxCacheSize` |
OPENFGA_DATASTORE_MAX_CACHE_SIZE
| `datastore-max-cache-size` | integer | The maximum number of authorization models that will be cached in memory | `100000` | +| `datastore.maxOpenConns` |
OPENFGA_DATASTORE_MAX_OPEN_CONNS
| `datastore-max-open-conns` | integer | The maximum number of open connections to the datastore. | `30` | +| `datastore.maxIdleConns` |
OPENFGA_DATASTORE_MAX_IDLE_CONNS
| `datastore-max-idle-conns` | integer | the maximum number of connections to the datastore in the idle connection pool. | `10` | +| `datastore.connMaxIdleTime` |
OPENFGA_DATASTORE_CONN_MAX_IDLE_TIME
| `datastore-conn-max-idle-time` | string (duration) | the maximum amount of time a connection to the datastore may be idle | `connections are not closed due to idle time - database/sql default` | +| `datastore.connMaxLifetime` |
OPENFGA_DATASTORE_CONN_MAX_LIFETIME
| `datastore-conn-max-lifetime` | string (duration) | the maximum amount of time a connection to the datastore may be reused | `connections are not closed due to connection's age - database/sql default` | +| `datastore.metrics.enabled` |
OPENFGA_DATASTORE_METRICS_ENABLED
| `datastore-metrics-enabled` | boolean | enable/disable sql metrics for the datastore | `false` | +| `authn.method` |
OPENFGA_AUTHN_METHOD
| `authn-method` | string (enum=[`none`, `preshared`, `oidc`]) | The authentication method to use. | `none` | +| `authn.preshared.keys` |
OPENFGA_AUTHN_PRESHARED_KEYS
| `authn-preshared-keys` | []string | | | +| `authn.oidc.issuer` |
OPENFGA_AUTHN_OIDC_ISSUER
| `authn-oidc-issuer` | string | The OIDC issuer (authorization server) signing the tokens. | | +| `authn.oidc.audience` |
OPENFGA_AUTHN_OIDC_AUDIENCE
| `authn-oidc-audience` | string | The OIDC audience of the tokens being signed by the authorization server. | | +| `authn.oidc.issuerAliases` |
OPENFGA_AUTHN_OIDC_ISSUER_ALIASES
| `authn-oidc-issuer-aliases` | []string | the OIDC issuer DNS aliases that will be accepted as valid when verifying the `iss` field of the JWTs. | | +| `authn.oidc.subjects` |
OPENFGA_AUTHN_OIDC_SUBJECTS
| `authn-oidc-subjects` | []string | the OIDC subject names that will be accepted as valid when verifying the `sub` field of the JWTs. If empty, every `sub` will be allowed | | +| `authn.oidc.clientIdClaims` |
OPENFGA_AUTHN_OIDC_CLIENT_ID_CLAIMS
| `authn-oidc-client-id-claims` | []string | the OIDC client id claims that will be used to parse the clientID - configure in order of priority (first is highest). Defaults to [`azp`, `client_id`] | | +| `grpc.addr` |
OPENFGA_GRPC_ADDR
| `grpc-addr` | string | The host:port address to serve the grpc server on. | `0.0.0.0:8081` | +| `grpc.tls.enabled` |
OPENFGA_GRPC_TLS_ENABLED
| `grpc-tls-enabled` | boolean | Enables or disables transport layer security (TLS). | `false` | +| `grpc.tls.cert` |
OPENFGA_GRPC_TLS_CERT
| `grpc-tls-cert` | string | The (absolute) file path of the certificate to use for the TLS connection. | | +| `grpc.tls.key` |
OPENFGA_GRPC_TLS_KEY
| `grpc-tls-key` | | The (absolute) file path of the TLS key that should be used for the TLS connection. | | +| `http.enabled` |
OPENFGA_HTTP_ENABLED
| `http-enabled` | boolean | Enables or disables the OpenFGA HTTP server. If this is set to true then 'grpc.enabled' must be set to true. | `true` | +| `http.addr` |
OPENFGA_HTTP_ADDR
| `http-addr` | string | The host:port address to serve the HTTP server on. | `0.0.0.0:8080` | +| `http.tls.enabled` |
OPENFGA_HTTP_TLS_ENABLED
| `http-tls-enabled` | boolean | Enables or disables transport layer security (TLS). | `false` | +| `http.tls.cert` |
OPENFGA_HTTP_TLS_CERT
| `http-tls-cert` | string | The (absolute) file path of the certificate to use for the TLS connection. | | +| `http.tls.key` |
OPENFGA_HTTP_TLS_KEY
| `http-tls-key` | | The (absolute) file path of the TLS key that should be used for the TLS connection. | | +| `http.upstreamTimeout` |
OPENFGA_HTTP_UPSTREAM_TIMEOUT
| `http-upstream-timeout` | string | The timeout duration for proxying HTTP requests upstream to the grpc endpoint. | `3s` | +| `http.corsAllowedOrigins` |
OPENFGA_HTTP_CORS_ALLOWED_ORIGINS
| `http-cors-allowed-origins` | []string | | `*` | +| `http.corsAllowedHeaders` |
OPENFGA_HTTP_CORS_ALLOWED_HEADERS
| `http-cors-allowed-headers` | []string | | `*` | +| `log.format` |
OPENFGA_LOG_FORMAT
| `log-format` | string (enum=[`text`, `json`]) | The log format to output logs in. For production we recommend 'json' format. | `text` | +| `log.level` |
OPENFGA_LOG_LEVEL
| `log-level` | string (enum=[`none`, `debug`, `info`, `warn`, `error`, `panic`, `fatal`]) | The log level to set. For production we recommend 'info' format. | `info` | +| `log.timestampFormat` |
OPENFGA_LOG_TIMESTAMP_FORMAT
| `log-timestamp-format` | string (enum=[`Unix`, `ISO8601`]) | The timestamp format to use for the log output. | `Unix` | +| `trace.enabled` |
OPENFGA_TRACE_ENABLED
| `trace-enabled` | boolean | Enable tracing. | `false` | +| `trace.otlp.endpoint` |
OPENFGA_TRACE_OTLP_ENDPOINT
| `trace-otlp-endpoint` | string | The grpc endpoint of the trace collector | `0.0.0.0:4317` | +| `trace.otlp.tls.enabled` |
OPENFGA_TRACE_OTLP_TLS_ENABLED
| `trace-otlp-tls-enabled` | boolean | Whether to use TLS connection for the trace collector | `false` | +| `trace.sampleRatio` |
OPENFGA_TRACE_SAMPLE_RATIO
| `trace-sample-ratio` | number | The fraction of traces to sample. 1 means all, 0 means none. | `0.2` | +| `trace.serviceName` |
OPENFGA_TRACE_SERVICE_NAME
| `trace-service-name` | string | The service name included in sampled traces. | `openfga` | +| `metrics.enabled` |
OPENFGA_METRICS_ENABLED
| `metrics-enabled` | boolean | enable/disable prometheus metrics on the '/metrics' endpoint | `true` | +| `metrics.addr` |
OPENFGA_METRICS_ADDR
| `metrics-addr` | string | the host:port address to serve the prometheus metrics server on | `0.0.0.0:2112` | +| `metrics.enableRPCHistograms` |
OPENFGA_METRICS_ENABLE_RPC_HISTOGRAMS
| `metrics-enable-rpc-histograms` | boolean | enables prometheus histogram metrics for RPC latency distributions | `false` | +| `checkCache.limit` |
OPENFGA_CHECK_CACHE_LIMIT
| `check-cache-limit` | integer | the size limit (in items) of the cache for Check (queries and iterators) | `10000` | +| `checkIteratorCache.enabled` |
OPENFGA_CHECK_ITERATOR_CACHE_ENABLED
| `check-iterator-cache-enabled` | boolean | enable caching of datastore iterators. The key is a string representing a database query, and the value is a list of tuples. Each iterator is the result of a database query, for example usersets related to a specific object, or objects related to a specific user, up to a certain number of tuples per iterator. If the request's consistency is HIGHER_CONSISTENCY, this cache is not used. | `false` | +| `checkIteratorCache.maxResults` |
OPENFGA_CHECK_ITERATOR_CACHE_MAX_RESULTS
| `check-iterator-cache-max-results` | integer | if caching of datastore iterators of Check requests is enabled, this is the limit of tuples to cache per key | `10000` | +| `checkIteratorCache.ttl` |
OPENFGA_CHECK_ITERATOR_CACHE_TTL
| `check-iterator-cache-ttl` | string (duration) | if caching of datastore iterators of Check requests is enabled, this is the TTL of each value | `10s` | +| `checkQueryCache.enabled` |
OPENFGA_CHECK_QUERY_CACHE_ENABLED
| `check-query-cache-enabled` | boolean | enable caching of Check requests. The key is a string representing a query, and the value is a boolean. For example, if you have a relation `define viewer: owner or editor`, and the query is Check(user:anne, viewer, doc:1), we'll evaluate the `owner` relation and the `editor` relation and cache both results: (user:anne, viewer, doc:1) -> allowed=true and (user:anne, owner, doc:1) -> allowed=true. The cache is stored in-memory; the cached values are overwritten on every change in the result, and cleared after the configured TTL. This flag improves latency, but turns Check and ListObjects into eventually consistent APIs. If the request's consistency is HIGHER_CONSISTENCY, this cache is not used. | `false` | +| `checkQueryCache.limit` |
OPENFGA_CHECK_QUERY_CACHE_LIMIT
| `check-query-cache-limit` | integer | DEPRECATED use OPENFGA_CHECK_CACHE_LIMIT. If caching of Check and ListObjects calls is enabled, this is the size limit (in items) of the cache | `10000` | +| `checkQueryCache.ttl` |
OPENFGA_CHECK_QUERY_CACHE_TTL
| `check-query-cache-ttl` | string (duration) | if caching of Check and ListObjects is enabled, this is the TTL of each value | `10s` | +| `cacheController.enabled` |
OPENFGA_CACHE_CONTROLLER_ENABLED
| `cache-controller-enabled` | boolean | enabling dynamic invalidation of check query cache and check iterator cache based on whether there are recent tuple writes. If enabled, cache will be invalidated when either 1) there are tuples written to the store OR 2) the check query cache or check iterator cache TTL has expired. | `false` | +| `cacheController.ttl` |
OPENFGA_CACHE_CONTROLLER_TTL
| `cache-controller-ttl` | string (duration) | if cache controller is enabled, control how frequent read changes are invoked internally to query for recent tuple writes to the store. | `10s` | +| `checkDispatchThrottling.enabled` |
OPENFGA_CHECK_DISPATCH_THROTTLING_ENABLED
| `check-dispatch-throttling-enabled` | boolean | enable throttling when check request's number of dispatches is high | `false` | +| `checkDispatchThrottling.frequency` |
OPENFGA_CHECK_DISPATCH_THROTTLING_FREQUENCY
| `check-dispatch-throttling-frequency` | string (duration) | the frequency period that the deprioritized throttling queue is evaluated for a check request. A higher value will result in more aggressive throttling | `10µs` | +| `checkDispatchThrottling.threshold` |
OPENFGA_CHECK_DISPATCH_THROTTLING_THRESHOLD
| `check-dispatch-throttling-threshold` | integer | define the number of recursive operations to occur before getting throttled for a check request | `100` | +| `checkDispatchThrottling.maxThreshold` |
OPENFGA_CHECK_DISPATCH_THROTTLING_MAX_THRESHOLD
| `check-dispatch-throttling-max-threshold` | integer | define the maximum dispatch threshold beyond above which requests will be throttled. 0 will use the 'dispatchThrottling.threshold' value as maximum | `0` | +| `listObjectsDispatchThrottling.enabled` |
OPENFGA_LIST_OBJECTS_DISPATCH_THROTTLING_ENABLED
| `list-objects-dispatch-throttling-enabled` | boolean | enable throttling when list objects request's number of dispatches is high | `false` | +| `listObjectsDispatchThrottling.frequency` |
OPENFGA_LIST_OBJECTS_DISPATCH_THROTTLING_FREQUENCY
| `list-objects-dispatch-throttling-frequency` | string (duration) | the frequency period that the deprioritized throttling queue is evaluated for a list objects request. A higher value will result in more aggressive throttling | `10µs` | +| `listObjectsDispatchThrottling.threshold` |
OPENFGA_LIST_OBJECTS_DISPATCH_THROTTLING_THRESHOLD
| `list-objects-dispatch-throttling-threshold` | integer | define the number of recursive operations to occur before getting throttled for a list objects request | `100` | +| `listObjectsDispatchThrottling.maxThreshold` |
OPENFGA_LIST_OBJECTS_DISPATCH_THROTTLING_MAX_THRESHOLD
| `list-objects-dispatch-throttling-max-threshold` | integer | define the maximum dispatch threshold beyond above which requests will be throttled for a list objects request. 0 will use the 'dispatchThrottling.threshold' value as maximum | `0` | +| `listUsersDispatchThrottling.enabled` |
OPENFGA_LIST_USERS_DISPATCH_THROTTLING_ENABLED
| `list-users-dispatch-throttling-enabled` | boolean | enable throttling when list users request's number of dispatches is high | `false` | +| `listUsersDispatchThrottling.frequency` |
OPENFGA_LIST_USERS_DISPATCH_THROTTLING_FREQUENCY
| `list-users-dispatch-throttling-frequency` | string (duration) | the frequency period that the deprioritized throttling queue is evaluated for a list users request. A higher value will result in more aggressive throttling | `10µs` | +| `listUsersDispatchThrottling.threshold` |
OPENFGA_LIST_USERS_DISPATCH_THROTTLING_THRESHOLD
| `list-users-dispatch-throttling-threshold` | integer | define the number of recursive operations to occur before getting throttled for a list users request | `100` | +| `listUsersDispatchThrottling.maxThreshold` |
OPENFGA_LIST_USERS_DISPATCH_THROTTLING_MAX_THRESHOLD
| `list-users-dispatch-throttling-max-threshold` | integer | define the maximum dispatch threshold beyond above which requests will be throttled for a list users request. 0 will use the 'dispatchThrottling.threshold' value as maximum | `0` | +| `requestTimeout` |
OPENFGA_REQUEST_TIMEOUT
| `request-timeout` | string (duration) | The timeout duration for a request. | `3s` | + +## Related Sections + + \ No newline at end of file diff --git a/docs/content/getting-started/setup-openfga/configure-openfga.mdx b/docs/content/getting-started/setup-openfga/configure-openfga.mdx index 3b4495819..eddb4231c 100644 --- a/docs/content/getting-started/setup-openfga/configure-openfga.mdx +++ b/docs/content/getting-started/setup-openfga/configure-openfga.mdx @@ -17,51 +17,11 @@ Refer to the [OpenFGA Getting Started](https://github.com/openfga/openfga?tab=re The instructions below assume OpenFGA is installed and that you have the `openfga` binary in your PATH. If you have built `openfga` as a binary, but not in your path, you can refer to it directly (e.g. replace `openfga` in the instructions below with `./openfga` or `/path/to/openfga`). -You can configure the OpenFGA server in three ways: +For a list of all the configuration options that the latest release of OpenFGA supports, see [Configuration Options](./configuration), or you can run `openfga --help` to see the ones specific to your version. -- Using a configuration file. -- Using environment variables. -- Using command line parameters. - -If the same option is configured in multiple ways the command line parameters will take precedence over environment variables, which will take precedence over the configuration file. - -The configuration options and their default values are defined in [config-schema.json](https://github.com/openfga/openfga/blob/main/.config-schema.json). - -## Using a configuration file - -You can configure the OpenFGA server with a `config.yaml` file, which can be specified in either: -- `/etc/openfga` -- `$HOME/.openfga` -- `.` (i.e., the current working directory). - -The OpenFGA server will search for the configuration file in the above order. - -Here is a sample configuration to run OpenFGA with a Postgres database and using a preshared key for authentication: - -```yaml -datastore: - engine: postgres - uri: postgres://user:password@localhost:5432/mydatabase -authn: - method: preshared - preshared: - keys: ["key1", "key2"] -``` - -## Using environment variables - -The OpenFGA server supports **environment variables** for configuration, and they will take priority over your configuration file. -Each variable must be prefixed with `OPENFGA_` and followed by your option in uppercase (e.g. `--grpc-tls-key` becomes `OPENFGA_GRPC_TLS_KEY`). - -## Using command line variables - -Command line parameters take precedence over environment variables and options in the configuration file. They are prefixed with `--` , e.g. - -```shell -openfga run \ - --datastore-engine postgres \ - --datastore-uri 'postgres://postgres:password@postgres:5432/postgres?sslmode=disable' -``` +:::note +The instructions below are for configuring the standalone OpenFGA server. If you are using OpenFGA as a library, you can refer to the [GoDoc](https://pkg.go.dev/github.com/openfga/openfga) for more information. +::: ## Configuring data storage @@ -274,7 +234,7 @@ grpcurl -plaintext $FGA_API_URL grpc.health.v1.Health/Check ## Experimental features -Various releases of OpenFGA may have experimental features that can be enabled by providing the `--experimentals` flag or the `experimentals` config. +Various releases of OpenFGA may have experimental features that can be enabled by providing the [`--experimentals`](./configuration#OPENFGA_EXPERIMENTALS) flag or the `experimentals` config. ``` openfga run --experimentals="feature1, feature2" @@ -356,6 +316,12 @@ It is highly recommended to enable logging in production environments. Disabling