Environment Variables

OpnForm uses two .env files for configuration: one for the Laravel backend located in the api directory, and one for the Nuxt front-end located in the client directory.

Public instance URL (self-hosted)

Set these variables before exposing a self-hosted instance publicly or configuring OIDC, OAuth, emails, or any feature that generates links back to your OpnForm instance. They must use the real public URL, never localhost in production. For a standard Docker deployment available at https://forms.example.com:

./scripts/docker-setup.sh --public-url https://forms.example.com

The setup command creates or updates the following values while preserving existing application keys and secrets:

File	Variable	Value
`api/.env`	`APP_URL`	`https://forms.example.com`
`api/.env`	`FRONT_URL`	`https://forms.example.com`
`client/.env`	`NUXT_PUBLIC_APP_URL`	`https://forms.example.com`
`client/.env`	`NUXT_PUBLIC_API_BASE`	`https://forms.example.com/api`

APP_URL, FRONT_URL, and NUXT_PUBLIC_APP_URL normally have the same public origin. In the standard Docker setup, the API is served through that same origin under /api, which is why NUXT_PUBLIC_API_BASE ends in /api. If your API is exposed on a separate public origin, use that browser-accessible API URL instead. If you configure these values manually, recreate the affected containers. docker compose restart does not reload environment values. See Updating Environment Variables. For the deployment workflow, see Docker Deployment. For the OIDC-specific checklist, see OIDC SSO Configuration.

Backend Environment Variables

The following environment variables are used to configure the Laravel application (OpnForm’s API).

Dedicated guides

There are dedicated configuration pages available for more detailed setup instructions on specific topics:

Configuration Environment Variables

Variable Name	Description
`H_CAPTCHA_SITE_KEY`	Site key for hCaptcha integration.
`H_CAPTCHA_SECRET_KEY`	Secret key for hCaptcha integration.
`RE_CAPTCHA_SITE_KEY`	Site key for reCAPTCHA integration.
`RE_CAPTCHA_SECRET_KEY`	Secret key for reCAPTCHA integration.
`OPEN_AI_API_KEY`	API key for accessing OpenAI services.
`UNSPLASH_ACCESS_KEY`	Access key for Unsplash API.
`UNSPLASH_SECRET_KEY`	Secret key for Unsplash API.
`APP_URL`	Public URL of the Laravel application. For a standard self-hosted deployment, set it to the public OpnForm URL.
`FRONT_URL`	Public facing URL of the front-end.
`FRONT_API_SECRET`	Shared secret with the front-end.
`JWT_TTL`	Time to live for JSON Web Tokens (JWT).
`JWT_SECRET`	Secret key used to sign JWTs.
`JWT_SKIP_IP_UA_VALIDATION`	Set to `true` to disable JWT User Agent validation (defaults to `false`). Keep this disabled in production and Docker deployments. For local Docker development, `docker-compose.dev.yml` sets this to `true` automatically.
`OAUTH_ENABLED`	Enables the delegated OAuth 2.1 infrastructure. Defaults to `true`; set it to `false` only when you need to disable OAuth routes independently of the MCP setting.
`OAUTH_ACCESS_TOKEN_TTL`	Passport access token lifetime in minutes. Defaults to `10080` (7 days) and does not change the first-party JWT lifetime.
`OAUTH_REFRESH_TOKEN_TTL_DAYS`	Passport refresh token lifetime in days. Defaults to `30`.
`PUBLIC_UPLOADS_MAX_FILE_SIZE`	Maximum temporary file size in bytes for local uploads through `/upload-file`. Defaults to `50000000` (50 MB). Workspace and field limits still apply when submitting a response.
`PUBLIC_UPLOADS_RATE_LIMIT_PER_MINUTE`	Maximum public upload requests allowed per client IP or authenticated user per route each minute. Defaults to `30`.
`PUBLIC_UPLOADS_RATE_LIMIT_PER_HOUR`	Maximum public upload requests allowed per client IP or authenticated user per route each hour. Defaults to `300`.
`OIDC_FORCE_LOGIN`	When set to `true`, password-based authentication is disabled and users must authenticate via OIDC SSO. See Force Login Mode for details.
`OIDC_RATE_LIMIT_PER_MINUTE`	Maximum OIDC sign-in initiations allowed per client IP and OIDC connection each minute. Defaults to `100`. OIDC callbacks use the normal API limit and are protected by their single-use state verifier.
`TRUSTED_PROXIES`	Comma-separated IP addresses or CIDR ranges of reverse proxies allowed to provide `X-Forwarded-` headers. Leave empty for a direct Docker deployment. Never use ``; it would allow a direct client to spoof its IP.
`CUSTOM_CODE_ENABLE_SELF_HOSTED`	Enables execution of user-provided custom code on self-hosted deployments. Defaults to `false` for safety reasons (XSS etc.).
`LICENSE_API_ENDPOINT`	Cloud API endpoint used by self-hosted instances for Enterprise license validation. Defaults to `https://api.opnform.com`.
`LICENSE_CHECKOUT_SUCCESS_URL`	Cloud checkout success URL used when creating self-hosted Enterprise license Stripe sessions.
`LICENSE_CHECKOUT_CANCEL_URL`	Cloud checkout cancellation URL used when creating self-hosted Enterprise license Stripe sessions.
`LICENSE_PORTAL_RETURN_URL`	Return URL used by the Stripe billing portal for self-hosted Enterprise licenses.

Self-hosted Enterprise licensing

Self-hosted Enterprise features are unlocked by activating a license key in the OpnForm UI. Most installations can use the default license API endpoint. Use the LICENSE_* variables only when you need to override checkout, billing portal, or license API URLs for your deployment. For activation steps and troubleshooting, see License Activation.

OAuth Integration Environment Variables

OAuth integrations enable user authentication and third-party service connections. OpnForm automatically handles OAuth redirect URLs - you don’t need to manually configure redirect URIs in your OAuth applications.

For detailed setup instructions for each OAuth provider, see the OAuth Integration Setup guide.

Variable Name	Description
`GOOGLE_CLIENT_ID`	Client ID for Google OAuth authentication and Google Sheets integration.
`GOOGLE_CLIENT_SECRET`	Client secret for Google OAuth authentication and Google Sheets integration.
`GOOGLE_FONTS_API_KEY`	API key for accessing Google Fonts (optional).
`STRIPE_CLIENT_ID`	Client ID for Stripe Connect OAuth integration for payment processing.
`STRIPE_CLIENT_SECRET`	Client secret for Stripe Connect OAuth integration.
`TELEGRAM_BOT_TOKEN`	Authentication token for your Telegram bot notifications (bot ID is extracted automatically).

User Options Environment Variables

Variable Name	Description
`ADMIN_EMAILS`	Comma-separated list of admin email addresses.
`TEMPLATE_EDITOR_EMAILS`	Comma-separated list of template editor emails.
`EXTRA_PRO_USERS_EMAILS`	Comma-separated list of extra pro user emails.
`MODERATOR_EMAILS`	Comma-separated list of moderator email addresses.
`SHOW_OFFICIAL_TEMPLATES`	Set to `false` to hide official templates from OpnForm’s template gallery (defaults to `true`).

PHP Configuration Environment Variables

Variable Name	Description
`PHP_MEMORY_LIMIT`	Maximum amount of memory a script may consume.
`PHP_MAX_EXECUTION_TIME`	Maximum time in seconds a script is allowed to run.
`PHP_UPLOAD_MAX_FILESIZE`	Maximum size of an uploaded file.
`PHP_POST_MAX_SIZE`	Maximum size of POST data that PHP will accept.

These PHP configuration variables are particularly important when handling file uploads and processing large amounts of data. If any of these variables are not set, PHP will use its default values from the php.ini configuration. When using Docker, these values are set in the docker-compose.yml file. For non-Docker installations, you’ll need to configure these values in your PHP configuration (php.ini) file. For local file storage, /upload-file accepts temporary uploads up to PUBLIC_UPLOADS_MAX_FILE_SIZE (50 MB by default). If your workspace allows larger attachments, increase this value and ensure PHP and your reverse proxy accept the larger request, including multipart overhead. This setting does not change direct S3 uploads. Form assets, such as logos and cover images, retain their separate 5 MB limit.

Database Configuration Environment Variables

These variables are essential for connecting the Laravel backend to your database.

Variable Name	Description
`DB_CONNECTION`	The database driver (e.g., `mysql`, `pgsql`).
`DB_HOST`	The database server host (e.g., `127.0.0.1`).
`DB_PORT`	The database server port (e.g., `3306`).
`DB_DATABASE`	The name of the database.
`DB_USERNAME`	The username for connecting to the database.
`DB_PASSWORD`	The password for the database user.

Instance Telemetry

OpnForm tracks usage of its products which helps the team to improve and deliver better software. You can opt-out of this telemetry at any time. What data is collected? The telemetry includes instance metadata and usage statistics:

Basic usage metrics (form creation, submissions, workspace creation, user additions)
Generated instance identifier (UUID), application version, and license status
Configured instance hostname, extracted from FRONT_URL with a fallback to APP_URL. URL paths, query parameters, ports, and credentials are excluded. Configured URLs using IP addresses or common local/internal hostnames are not reported.
No form content, submission data, or user emails

How is the data used? This data will only be used by OpnForm team for:

Directly improving the product and identifying the parts of product which are popular
Identifying areas with limited usage or where our users get stuck
Prioritizing the next set of features to be developed
Identifying installations when investigating usage and potential Enterprise licensing issues

The hostname can identify your installation, so instance telemetry is not anonymous. When is telemetry active?

Production environments (APP_ENV=production)
Self-hosted deployments (SELF_HOSTED=true)
Disabled in local/development environments

How to opt-out: Set OPNFORM_TELEMETRY_DISABLED=true in your environment variables to disable data collection, then restart the application and workers. If you cache Laravel configuration, rebuild the configuration cache as well.

Variable	Default	Description
`OPNFORM_TELEMETRY_DISABLED`	`false`	Disable instance telemetry when `true`. Takes precedence over the legacy variable when set.
`OPNFORM_ANONYMOUS_TELEMETRY_DISABLED`	`false`	Deprecated name, still supported. Used only when `OPNFORM_TELEMETRY_DISABLED` is absent.

Existing installations using only the deprecated variable do not need to change their configuration. When migrating, replace the old variable with the new name and retain its value. If both are set, the new variable wins, including when it is explicitly false.

MCP and AI agents

MCP is disabled by default on self-hosted instances. Enable it from Settings → MCP & AI agents after configuring public HTTPS origins and Laravel Passport. Form and submission tools require OAuth. See the MCP integration guide for the complete setup.

Variable Name	Default	Description
`MCP_ENABLED`	`false`	Default MCP state for self-hosted instances. Set it in `api/.env`, the API service `environment` block in Docker Compose, or the API container environment. A value saved in Settings → MCP & AI agents overrides it.
`MCP_OBSERVABILITY_ENABLED`	`true`	Records metadata-only MCP usage events and structured logs. No arguments, tokens, form content, or submission values are recorded.
`MCP_RATE_LIMIT_PER_MINUTE`	`120`	MCP requests allowed per minute per OAuth user or unauthenticated client IP.
`MCP_RATE_LIMIT_PER_HOUR`	`3000`	MCP requests allowed per hour per OAuth user or unauthenticated client IP.
`MCP_SUBMISSION_EXPORTS_PER_MINUTE`	`5`	Submission exports allowed per minute per user and form.
`MCP_SUBMISSION_EXPORTS_PER_HOUR`	`30`	Submission exports allowed per hour per user and form.
`FORM_SUMMARY_RATE_LIMIT_PER_MINUTE`	`30`	REST and MCP submission summary requests allowed per minute in one shared per-user bucket.
`MCP_OAUTH_REDIRECT_DOMAINS`	See `.env.example`	Comma-separated HTTPS or loopback callback origins accepted during dynamic client registration.
`MCP_OAUTH_CUSTOM_SCHEMES`	`chatgpt,claude,cursor,vscode`	Comma-separated callback URI schemes accepted for trusted native clients.
`MCP_AUTHORIZATION_SERVER`	Application URL	Optional external OAuth authorization-server URL advertised by MCP discovery.

Front-end Environment Variables

Variable Name	Description
`NUXT_PUBLIC_APP_URL`	Public facing URL of the Nuxt application.
`NUXT_PUBLIC_API_BASE`	Base URL for the Laravel API.
`NUXT_PUBLIC_LICENSE_API_ENDPOINT`	Cloud API endpoint used by the self-hosted client to start Enterprise license checkout. Defaults to `https://api.opnform.com`.
`NUXT_PUBLIC_H_CAPTCHA_SITE_KEY`	Site key for hCaptcha integration on the front-end.
`NUXT_PUBLIC_RE_CAPTCHA_SITE_KEY`	Site key for reCAPTCHA integration on the front-end.
`NUXT_API_SECRET`	Shared secret key between Nuxt and Laravel backend.
`NUXT_PUBLIC_ROOT_REDIRECT_URL`	Redirects the self-hosted welcome page and unknown pages (HTTP 301), plus marketing pages (HTTP 302), to your website. Forms and application pages remain accessible. See Subdomain Redirect Configuration.
`NUXT_PUBLIC_SELF_HOSTED_NAME`	Name displayed on the self-hosted welcome page and navigation; defaults to `OpnForm`.
`NUXT_PUBLIC_SELF_HOSTED_LOGO_URL`	Absolute HTTP(S) URL for the self-hosted instance logo.
`NUXT_PUBLIC_SELF_HOSTED_PRIVACY_POLICY_URL`	Organization privacy policy URL for self-hosted visitors.
`NUXT_PUBLIC_SELF_HOSTED_TERMS_URL`	Organization terms URL for self-hosted visitors.

The easiest way to get started with OpnForm is through our official managed service in the Cloud. It takes just 1 minute to start building forms with the free plan, with high availability, backups, security, and maintenance all managed for you.

Docker Environment Variables

When running OpnForm with Docker, there are some important considerations for handling environment variables:

Docker Compose uses shell variables, a root .env file next to docker-compose.yml, or a file passed with --env-file when it resolves ${...} values in the Compose file. The service-level env_file entries such as ./api/.env and ./client/.env only pass variables into the containers after the Compose file has already been resolved.

Updating Environment Variables

When changing environment variables in your .env files, you need to recreate the containers for the changes to take effect. Simply restarting the containers is not sufficient as Docker only loads environment variables when containers are created. To apply new environment variable changes:

# For a specific service (e.g., ui)
docker compose down ui
docker compose up -d ui

# For all services
docker compose down
docker compose up -d

A simple docker compose restart will not reload environment variables from your .env files. You must use down and up commands to recreate the containers.

Get Started

Features

Deployment

Self-hosted Enterprise

Configuration

Embedding

Integrations

Public instance URL (self-hosted)

Backend Environment Variables

Dedicated guides

Configuration Environment Variables

Self-hosted Enterprise licensing

OAuth Integration Environment Variables

User Options Environment Variables

PHP Configuration Environment Variables

Database Configuration Environment Variables

Instance Telemetry

MCP and AI agents

Front-end Environment Variables

Docker Environment Variables

Updating Environment Variables

​Public instance URL (self-hosted)

​Backend Environment Variables

​Dedicated guides

​Configuration Environment Variables

​Self-hosted Enterprise licensing

​OAuth Integration Environment Variables

​User Options Environment Variables

​PHP Configuration Environment Variables

​Database Configuration Environment Variables

​Instance Telemetry

​MCP and AI agents

​Front-end Environment Variables

​Docker Environment Variables

​Updating Environment Variables

Public instance URL (self-hosted)

Backend Environment Variables

Dedicated guides

Configuration Environment Variables

Self-hosted Enterprise licensing

OAuth Integration Environment Variables

User Options Environment Variables

PHP Configuration Environment Variables

Database Configuration Environment Variables

Instance Telemetry

MCP and AI agents

Front-end Environment Variables

Docker Environment Variables

Updating Environment Variables