# Essential OpenSEO Environment Variables for Self-Hosted Deployment

> Discover essential OpenSEO environment variables for self-hosted deployment. Learn about DATAFORSEO_API_KEY and AUTH_MODE for secure setup. Optimize your instance now.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: how-to-guide
- Published: 2026-06-26

---

**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:

```text
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`](https://github.com/every-app/open-seo/blob/main/compose.yaml) file (lines 5-16) injects environment variables into the container:

```yaml
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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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:

```text

# .env

DATAFORSEO_API_KEY=base64(YOUR_EMAIL:YOUR_PASSWORD)
AUTH_MODE=local_noauth

```

Start the application:

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

```

### Cloudflare Workers with Access

For Cloudflare deployments requiring authentication:

```text
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:

```text
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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/drizzle-prod.config.ts). Docker deployments use local SQLite or other configured databases and do not need these Cloudflare-specific secrets.