Advanced Configuration

Use this page when your FiveNet setup goes beyond the basic installation and required configuration options.

Common Advanced Topics

The most common advanced configuration areas are:

• Trusted proxies when FiveNet runs behind NGINX, Traefik, Cloudflare, or another reverse proxy.
• Object storage when uploads should be stored in S3-compatible storage instead of the local filesystem.
• OAuth2 providers when users should be able to authenticate through external identity providers.
• Tracing and observability for debugging, performance analysis, and distributed request tracing.

For the most important option names and config paths, see the Config File Reference.

Tracing Notes

• Set enabled: true only after you have a working OTLP endpoint.
• Use a low ratio value in production unless you explicitly want to sample more traffic.
• Keep the environment value aligned with the environment where FiveNet runs, such as development, staging, or production.
• Use attributes to attach additional metadata that helps identify traces in your observability platform.

Reverse Proxy and Trusted Proxies

If FiveNet is deployed behind one or more reverse proxies, review the http.trustedProxies option in your config.yaml.

This is especially important when:

• client IP addresses should be preserved correctly
• FiveNet is running behind NGINX, Traefik, or Cloudflare
• you rely on forwarded headers from trusted infrastructure

See the Config File Reference for the http.trustedProxies setting.

Object Storage

By default, FiveNet stores uploads on the local filesystem. For more scalable or externally managed storage, you can switch to S3-compatible object storage through the storage configuration.

This is commonly useful when:

• running multiple instances
• using cloud infrastructure
• keeping uploaded files outside the application host

See the Config File Reference for the storage.type setting and related storage options.

OAuth2 Providers

FiveNet can be integrated with external authentication providers through the oauth2.providers configuration.

Use this when users should sign in through systems such as Discord or another OAuth2 or OpenID Connect provider instead of relying only on local authentication flows.

See the Config File Reference for the oauth2.providers setting.

Tracing

FiveNet supports OpenTelemetry-based tracing for the server and worker components. This can help you inspect request flow, background processing, and performance bottlenecks in more advanced environments.

Tracing is usually only needed when you already have an observability stack in place or when you are troubleshooting more complex issues.

Example Tracing Configuration

tracing:
  enabled: false
  # otlptracegrpc or otlptracehttp
  type: "otlptracegrpc"
  # OTLP tracing endpoint URL
  url: "https://example.com:4317"
  insecure: false
  timeout: 10s
  environment: "production"
  ratio: 0.1
  attributes:
    - service.name=fivenet-server