Essential OpenSEO Environment Variables for Self-Hosted Deployment

The only strictly required environment variable for any self-hosted OpenSEO deployment is DATAFORSEO_API_KEY, while AUTH_MODE determines which authentication strategy your instance uses.

OpenSEO is an open-source SEO analytics platform that supports multiple self-hosting modes including Docker and Cloudflare Workers. Properly configuring your OpenSEO environment variables ensures the application can authenticate with DataForSEO APIs and handle user access control according to your infrastructure requirements.

Core Required Variables

Every self-hosted OpenSEO instance requires two primary environment variables to function: one for external API access and one to set the authentication strategy.

DATAFORSEO_API_KEY

The DATAFORSEO_API_KEY is the single essential credential without which OpenSEO cannot fetch any SEO data. This variable must contain a base64-encoded string of your DataForSEO email and password separated by a colon.

In the repository's .env.example file at line 5, this is documented as the core credential for rank tracking, keyword research, and backlink data. The value format is:

DATAFORSEO_API_KEY=base64(YOUR_EMAIL:YOUR_PASSWORD)

AUTH_MODE

The AUTH_MODE variable determines which authentication strategy your deployment uses. As defined in .env.example at line 24, the available options include:

• cloudflare_access (default): For Cloudflare Workers deployments using Cloudflare Access for authentication
• local_noauth: For Docker self-hosting without external authentication
• hosted: For deployments using the Better Auth server

If you are running OpenSEO in Docker, you must set AUTH_MODE=local_noauth to bypass external auth requirements.

Optional Docker Configuration

When self-hosting via Docker, several optional environment variables control networking and deployment specifics.

PORT and ALLOWED_HOST

The PORT variable defines which port the server listens on, defaulting to 3001 if omitted. The ALLOWED_HOST variable specifies the hostname that Vite's preview server accepts when running behind a reverse proxy, as documented in .env.example at lines 8 and 11.

OPEN_SEO_IMAGE

This optional variable allows you to pin a specific Docker image tag rather than using the latest published version, defined at line 14 of .env.example.

Authentication-Specific Variables

Depending on your chosen AUTH_MODE, additional OpenSEO environment variables are required to secure your instance.

Cloudflare Access Mode

When AUTH_MODE=cloudflare_access, you must provide:

• TEAM_DOMAIN: Your Cloudflare Access team URL (e.g., https://myteam.cloudflareaccess.com)
• POLICY_AUD: The audience tag of your Cloudflare Access policy that the worker validates against

These variables enable JWT validation for the Cloudflare Workers deployment model.

Hosted Better Auth Mode

For AUTH_MODE=hosted, the following are required:

• BETTER_AUTH_SECRET: A secret used to sign JWTs for the Better Auth server and encrypt stored OAuth tokens (also required for Google Search Console integration)
• BETTER_AUTH_URL: The base URL of your Better Auth server (e.g., http://localhost:3001)

Google Search Console Integration

To enable Google Search Console connectivity regardless of authentication mode, set:

• GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET: OAuth client credentials for Google's OAuth flow

These work alongside BETTER_AUTH_SECRET to handle token encryption.

Optional Integrations

OpenSEO supports additional optional services through environment variables:

• PostHog Analytics: POSTHOG_PUBLIC_KEY and POSTHOG_HOST enable event tracking
• Loops.io Email: LOOPS_API_KEY, LOOPS_TRANSACTIONAL_VERIFY_EMAIL_ID, and LOOPS_TRANSACTIONAL_RESET_PASSWORD_ID enable verification and password-reset emails

Where Variables Are Consumed

Understanding how OpenSEO reads environment variables helps with troubleshooting configuration issues.

Docker Compose Injection

The compose.yaml file (lines 5-16) injects environment variables into the container:

environment:
  - CLOUDFLARE_INCLUDE_PROCESS_ENV=true
  - PORT=${PORT:-3001}
  - ALLOWED_HOST=${ALLOWED_HOST:-}
  - AUTH_MODE=local_noauth
  - DATAFORSEO_API_KEY=${DATAFORSEO_API_KEY}
  - GOOGLE_CLIENT_ID=${GOOGLE_CLIENT_ID:-}
  - GOOGLE_CLIENT_SECRET=${GOOGLE_CLIENT_SECRET:-}
  - BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET:-}

Runtime Access

The file src/server/lib/runtime-env.ts provides a centralized helper to read environment variables at runtime, ensuring consistent access patterns across the application.

Cloudflare Workers Configuration

For Cloudflare deployments, drizzle-prod.config.ts (lines 9-11) reads Cloudflare-specific secrets including CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_DATABASE_ID, and CLOUDFLARE_API_TOKEN. These are distinct from the Docker environment variables and are managed through the Cloudflare dashboard or Wrangler CLI.

Configuration Examples

Minimal Docker Deployment

Create a .env file with only the essential variable:

# .env

DATAFORSEO_API_KEY=base64(YOUR_EMAIL:YOUR_PASSWORD)
AUTH_MODE=local_noauth

Start the application:

cp .env.example .env
docker compose up -d

Cloudflare Workers with Access

For Cloudflare deployments requiring authentication:

AUTH_MODE=cloudflare_access
TEAM_DOMAIN=https://myteam.cloudflareaccess.com
POLICY_AUD=xxxxxxxxxxxxxxxxxxxx
DATAFORSEO_API_KEY=base64(YOUR_EMAIL:YOUR_PASSWORD)

Deploy using the "Deploy to Cloudflare" button; the worker validates JWTs against your specified domain and policy audience.

Enabling Google Search Console

Add these variables to any authentication mode:

GOOGLE_CLIENT_ID=your-goauth-client-id
GOOGLE_CLIENT_SECRET=your-goauth-client-secret
BETTER_AUTH_SECRET=super-random-32-char-string

After configuration, the Google Search Console integration page becomes functional for linking your GSC properties.

Summary

• DATAFORSEO_API_KEY is the only strictly required OpenSEO environment variable for all self-hosted deployments, requiring base64-encoded DataForSEO credentials
• AUTH_MODE determines your authentication strategy: use local_noauth for Docker, cloudflare_access for Workers, or hosted for Better Auth
• Docker-specific options include PORT (defaults to 3001), ALLOWED_HOST, and OPEN_SEO_IMAGE
• Cloudflare Access requires TEAM_DOMAIN and POLICY_AUD for JWT validation
• Google Search Console integration requires GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and BETTER_AUTH_SECRET
• Optional integrations support PostHog analytics and Loops.io transactional emails
• Configuration is defined in .env.example and injected via compose.yaml or Cloudflare secrets management

Frequently Asked Questions

What happens if I don't set DATAFORSEO_API_KEY?

Without DATAFORSEO_API_KEY, OpenSEO cannot fetch any SEO data including rank tracking, keyword research, or backlink information. The application will start but all data-dependent features will fail because this credential is required to authenticate with the DataForSEO API.

Can I run OpenSEO without any authentication?

Yes, but only in Docker self-hosting mode. Set AUTH_MODE=local_noauth to disable external authentication. This is not recommended for production deployments exposed to the internet, but is suitable for internal or development environments.

How do I format the DATAFORSEO_API_KEY correctly?

The DATAFORSEO_API_KEY must be a base64-encoded string of your DataForSEO email address and password separated by a colon. For example, if your email is user@example.com and password is secret123, encode user@example.com:secret123 in base64 to generate the value for this variable.

Are Cloudflare-specific variables required for Docker deployments?

No. Variables like CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_DATABASE_ID, and CLOUDFLARE_API_TOKEN are only required when deploying to Cloudflare Workers, as referenced in drizzle-prod.config.ts. Docker deployments use local SQLite or other configured databases and do not need these Cloudflare-specific secrets.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}