Skip to main content

Application Configuration Options

This document outlines various environment variables and options that can be configured to customize the behavior of the application. Setting these variables correctly is crucial for the application to function as intended.

Usage​

In Docker Compose​

To use these environment variables in a Docker Compose setup, define them in your docker-compose.yml file under the environment section for the relevant service. For example:

services:
  ztnet:
    environment:
      NEXTAUTH_URL: http://your_server_ip:3000
      # ... other environment variables ...

In a Standalone Environment​

Edit the .env file in /opt/ztnet to set the environment variables. For example:

DATABASE_URL=postgresql://postgres:postgres@postgres:5432/ztnet?schema=public
NEXTAUTH_URL=http://your_server_ip:3000

Available Environment options​

Configure the application using the following environment variables:

ZTNET Configuration​

  • HOSTNAME
    • Description: Hostname of the server. Only available in standalone mode.
    • Default: 0.0.0.0.
  • PORT
    • Description: Port on which the application will run. Only available in standalone mode.
    • Default: 3000.

ZeroTier Controller Configuration​

  • ZT_ADDR

    • Description: ZeroTier controller address. Use these settings if you wish to configure a custom ZeroTier controller instead of the default one.
    • Default: http://zerotier:9993 for Docker environment, and http://127.0.0.1:9993 for standalone.

  • ZT_SECRET

    • Description: ZeroTier controller secret. Necessary for custom controller configuration.
    • Default: Contents of /var/lib/zerotier-one/authtoken.secret.

Database Configuration​

  • POSTGRES_HOST

    • Default: postgres.

  • POSTGRES_PORT

    • Default: 5432.

  • POSTGRES_USER

    • Default: postgres.

  • POSTGRES_PASSWORD

    • Default: postgres.

  • POSTGRES_DB

    • Default: ztnet.

OAuth Configuration​

See OAuth for more information.

  • OAUTH_ALLOW_DANGEROUS_EMAIL_LINKING

    • Description: Allows linking of user accounts registered with email credentials to OAuth accounts. This should be enabled if a user has initially registered using email and password and later chooses to log in via OAuth, facilitating account merging.
    • Default: false

  • OAUTH_WELLKNOWN

    • Description: URL to the OAuth server's well-known configuration.
    • Examples:
      • For Google: https://accounts.google.com/.well-known/openid-configuration
      • For Keycloak: http://{KEYCLOAK_SERVER_URL}/auth/realms/{REALM}/.well-known/openid-configuration
    • Default: None. Must be set.

  • OAUTH_ID

    • Description: Client ID for OAuth authentication.
    • Default: None. Must be set.

  • OAUTH_SECRET

    • Description: Client secret for OAuth authentication.
    • Default: None. Must be set.

  • OAUTH_ACCESS_TOKEN_URL

    • Description: URL to obtain the access token in OAuth 2.0 flow. Used by OAuth providers to exchange authorization code for an access token.
    • Example: "https://github.com/login/oauth/access_token" for GitHub.
    • Default: None. Must be set according to the OAuth provider.

  • OAUTH_AUTHORIZATION_URL

    • Description: URL where the application redirects users for authentication and authorization. Initiates the OAuth 2.0 authorization flow.
    • Example: "https://github.com/login/oauth/authorize" for GitHub.
    • Default: None. Must be set according to the OAuth provider.

  • OAUTH_USER_INFO

    • Description: URL to fetch the user's profile information after successful authentication in OAuth 2.0 flow. Used to retrieve details about the authenticated user.
    • Example: "https://api.github.com/user" for GitHub.
    • Default: None. Must be set according to the OAuth provider.

  • OAUTH_SCOPE

    • Description: Specifies the scope of access requests in the OAuth 2.0 flow. This defines the level of access that the application is requesting from the user's account. Varies depending on the OAuth provider and the information the application needs.
    • Example: "read:user user:email" for GitHub, to request basic user information and email.
    • Default: "openid profile email".

  • OAUTH_EXCLUSIVE_LOGIN

    • Description: If set to true, users can only log in using OAuth. If set to false, users can log in using either OAuth or email credentials. When enabled, the signup form will be hidden to prevent unauthorized registrations.
    • Default: false.

  • OAUTH_ALLOW_NEW_USERS

    • Description: If set to true, new users can register via OAuth. If set to false, only existing users can log in via OAuth. This setting works independently of the general registration setting and is particularly useful when OAUTH_EXCLUSIVE_LOGIN is enabled.
    • Default: true.

NEXTAUTH Configuration​

For more information on NEXTAUTH environment variables, see NEXTAUTH Environment Variables.

  • NEXTAUTH_URL

    • Description: Canonical URL of your site.
    • Default: http://localhost:3000.

  • NEXTAUTH_URL_INTERNAL

    • Description: Server-side URL for NEXTAUTH. Used when the server doesn't have access to the canonical URL of your site.
    • Default: Value of NEXTAUTH_URL.

  • NEXTAUTH_SECRET

    • Description: Signs sessions and tokens and encrypts stored secrets such as two factor keys, API tokens and the SMTP password. It must be a unique random value for each install, for example the output of openssl rand -hex 32. Keep it stable. Changing it on an existing install signs every user out and invalidates two factor authentication and API tokens.
    • Default: none, required.

  • NEXTAUTH_SESSION_MAX_AGE

    • Description: Duration (in seconds) before the user is logged out due to inactivity.
    • Default: 2592000 (30 Days).

Rate Limiting Configuration​

Rate limiting helps protect against brute force attacks and abuse. There are separate configurations for authentication endpoints and REST API endpoints.

Authentication Endpoints​

These settings control rate limiting for authentication operations (registration, password reset, email verification, MFA).

  • RATE_LIMIT_WINDOW

    • Description: Time window in minutes for rate limit calculation. Requests are counted within this sliding window.
    • Default: 10 (10 minutes).

  • RATE_LIMIT_MAX_REQUESTS

    • Description: Maximum number of requests allowed within the rate limit window for general operations (e.g., registration, token validation).
    • Default: 60.

  • RATE_LIMIT_MAX_REQUESTS_SHORT

    • Description: Maximum number of requests allowed within the rate limit window for sensitive operations (e.g., password reset requests, password changes, email verification).
    • Default: 10.

REST API Endpoints​

These settings control rate limiting for all REST API endpoints under /api/v1/*.

  • RATE_LIMIT_API_WINDOW

    • Description: Time window in minutes for REST API rate limit calculation.
    • Default: 1 (1 minute).

  • RATE_LIMIT_API_MAX_REQUESTS

    • Description: Maximum number of requests allowed within the rate limit window for REST API endpoints.
    • Default: 50.

Webhook Configuration​

Organization webhooks are delivered over HTTPS only. Before every delivery ZTNET resolves the receiver and checks the address. By default every address that is not publicly routable is refused, so a webhook URL cannot be used to reach the ZeroTier controller, a cloud metadata endpoint or other services next to ZTNET. The option below relaxes this for private networks, while reserved addresses stay blocked.

  • WEBHOOK_ALLOW_PRIVATE_TARGETS
    • Description: Set to true to also deliver webhooks to receivers on private networks: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10 and IPv6 fc00::/7. Use this when the receiver is a service on your LAN, in the same Docker Compose project, or on a ZeroTier or Tailscale address. Loopback, link local, cloud metadata endpoints (169.254.169.254 and 100.100.100.200), multicast and other reserved addresses stay blocked, and the URL must still use HTTPS with a valid certificate. Applies at delivery time, so a restart is enough to change it.
    • Default: false.