Want to run OpenSEO locally on your Windows PC with Docker? This guide walks you through the entire installation process, from installing Docker Desktop and downloading OpenSEO to adding your DataForSEO API key and opening the local OpenSEO dashboard.

I’ll also show you how to enable OpenSEO’s AI features with OpenRouter and connect Google Search Console.

OpenSEO’s official Docker documentation recommends Docker for running the application locally, and the default setup uses a published Docker image from GitHub Container Registry.

What You Need Before Installing OpenSEO

Before you start, make sure you have:

A Windows PC
Docker Desktop installed and running
Git installed
A DataForSEO account and API key
An OpenRouter API key if you want to use OpenSEO’s AI features
A Google account with a verified Search Console property if you want to connect Google Search Console

OpenSEO requires a DataForSEO API key for its SEO data features. DataForSEO currently provides new accounts with $1 in free credit for testing.

OpenSEO Docker Commands

Here are the commands you’ll use throughout this guide.

Clone OpenSEO

git clone https://github.com/every-app/open-seo.git

Open the project folder

cd open-seo

Copy the environment file in PowerShell

Copy-Item .env.example .env

Copy the environment file in Command Prompt

copy .env.example .env

Generate a Better Auth secret

openssl rand -base64 32

Start OpenSEO

docker compose up -d

Recreate OpenSEO after editing `.env`

docker compose up -d --force-recreate

The current OpenSEO documentation uses the same basic Docker workflow and notes that changing environment variables requires recreating the container so Compose applies them.

Step 1: Install Docker Desktop

The first thing you need is Docker Desktop.

Go to the Docker website and download Docker Desktop for Windows.

When choosing the installer, select the version appropriate for your processor. On most modern Windows PCs, this will be the AMD64 version.

Install Docker Desktop and launch it.

Once Docker Desktop is running, make sure its status shows that Docker is running before moving on.

Docker Desktop is the main requirement for the local Docker installation. OpenSEO also supports Docker Engine with Docker Compose, but Docker Desktop is the simplest option on Windows.

Step 2: Create a Folder for OpenSEO

Next, create an empty folder somewhere on your PC where you want to keep the OpenSEO files.

For example, you could create:

C:\OpenSEO

You can use another drive or folder if you prefer.

Open the folder in Windows File Explorer.

Step 3: Open Command Prompt as Administrator

Open the Windows Start menu and search for:

cmd

Right-click Command Prompt and select Run as administrator.

You’ll now have an elevated Command Prompt window where you can run the Docker and Git commands.

Your terminal needs to be pointed at the folder where you want to download OpenSEO.

For example:

cd C:\OpenSEO

The exact path depends on where you created your folder.

Step 4: Clone the OpenSEO Repository

With Command Prompt pointed at your OpenSEO folder, clone the official GitHub repository:

git clone https://github.com/every-app/open-seo.git

Press Enter and Git will download the OpenSEO repository to your computer.

Once the command finishes, open the folder in File Explorer and you should see a new open-seo directory containing the project’s files. The official repository is maintained at every-app/open-seo.

Step 5: Enter the OpenSEO Folder

Now move into the newly created project directory:

cd open-seo

From this point onward, the Docker commands should be run from inside the OpenSEO project folder.

Step 6: Create the `.env` File

OpenSEO uses an environment file to store configuration values such as your DataForSEO API key.

The repository includes a template called:

.env.example

You need to create your own .env file from that template.

PowerShell

If you’re using PowerShell:

Copy-Item .env.example .env

Command Prompt

If you’re using Command Prompt:

copy .env.example .env

After running the command, refresh the folder in File Explorer. You should now see a .env file.

Do not upload or publicly share this file. It can contain API keys and other secrets.

Step 7: Add Your DataForSEO API Key

Open the new .env file in Notepad.

Look for the DataForSEO API key setting.

OpenSEO uses DataForSEO to fetch SEO data, and the current self-hosting documentation expects the DATAFORSEO_API_KEY value in .env. DataForSEO provides a Base64-encoded credential that represents your API login and API password in login:password form.

To get your credentials, log in to DataForSEO and open the API access section.

Copy the Base64 credential provided by DataForSEO.

Then return to your .env file.

You should have a line similar to:

DATAFORSEO_API_KEY=YOUR_BASE64_KEY

If the setting is commented out with a #, remove the # first.

Then paste your key after the = sign.

Save the file.

Keep Your API Key Private

Do not paste your real DataForSEO, OpenRouter, or Google credentials into a public GitHub repository or screenshot.

Your .env file is meant for your local configuration.

Step 8: Start OpenSEO with Docker

Now return to Command Prompt and make sure you’re still inside the open-seo folder.

Run:

docker compose up -d

Docker Compose will download the OpenSEO image and start the application.

The first startup can take a little while because Docker needs to pull the published image and initialize the application. The official documentation says the first start may take around one to two minutes.

You’ll see Docker create the required network, volume, and container.

Once the command finishes, OpenSEO should be running locally.

Step 9: Open OpenSEO in Your Browser

Open Docker Desktop and go to the Containers section.

You should see the OpenSEO container running.

Expand the container and look for the local application link.

With the default configuration, OpenSEO runs on:

http://localhost:3001

Open that address in your browser.

The current OpenSEO Docker configuration uses port 3001 by default, although you can change it through the PORT environment variable.

You should now see the OpenSEO dashboard.

Step 10: Test Keyword Research

Once OpenSEO is running, you can test whether the DataForSEO connection is working.

Open Keyword Research from the left-hand menu.

Enter a keyword or topic you want to research.

For example:

Canva howto*

You can then select the country you want to research and choose how many results you want to retrieve.

Depending on the options shown in your OpenSEO version, you may also be able to use filters for search intent, search volume, difficulty, and other metrics.

OpenSEO can return keyword ideas along with metrics such as search volume, competition, CPC, and intent. Your saved keywords can also be exported to CSV or Google Sheets.

In my test, I used keyword research for Canva-related searches and was able to see related terms, intent, volume, competition, and SERP information.

Keep in mind that DataForSEO usage can consume your account balance because it is a paid third-party service.

How to Enable OpenSEO AI Features

OpenSEO also includes AI features that can use an OpenRouter API key.

This lets you use the AI functionality inside OpenSEO for things such as brainstorming and working with SEO data.

Step 11: Create an OpenRouter API Key

Go to OpenRouter and sign in to your account.

If you don’t already have an account, create one and verify it through email.

Open the API Keys page and create a new key.

Give the key a name, such as:

OpenSEO

Set a spending or credit limit if you want to control how much the key can use.

Copy the API key once it has been created.

In the video setup, this was done by creating an OpenRouter key and adding it to the OpenSEO environment file.

Step 12: Add the OpenRouter Key to `.env`

Open your OpenSEO .env file again.

Find:

OPENROUTER_API_KEY=

Remove the # if the setting is commented out and add your OpenRouter key:

OPENROUTER_API_KEY=YOUR_OPENROUTER_API_KEY

Save the file.

Important: You Don’t Need to Edit `compose.yaml` Anymore

Older OpenSEO setups required manually changing compose.yaml so the OpenRouter key would be passed into the container.

The current OpenSEO compose.yaml already reads .env and forwards OPENROUTER_API_KEY into the container.

So with the current repository, do not add the old manual OPENROUTER_API_KEY environment mapping from the video unless your particular checkout is missing it.

This is one of the differences between the current OpenSEO Docker setup and older versions of the setup.

Step 13: Recreate the Docker Container

Saving .env isn’t enough by itself. Docker needs to recreate the container so it picks up the new environment variables.

Run:

docker compose up -d --force-recreate

Wait for the container to start again.

You can also verify the environment configuration with:

docker compose config

The official OpenSEO documentation specifically recommends docker compose up -d --force-recreate after changing environment variables.

Once OpenSEO is running again, open:

http://localhost:3001

Then open the AI/chat area and test it.

You should now be able to start a new chat and send a message.

How to Connect Google Search Console to OpenSEO

Google Search Console is optional. OpenSEO works without it, but connecting GSC lets the application access first-party performance information from your Search Console property.

You’ll need:

A Google Cloud project
Google Search Console API enabled
A Google OAuth client
A verified Search Console property
GOOGLE_CLIENT_ID
GOOGLE_CLIENT_SECRET
BETTER_AUTH_SECRET

Step 14: Create a Google Cloud Project

Go to:

https://console.cloud.google.com

Create a new Google Cloud project or select an existing one.

You can give it a name such as:

OpenSEO

Next, open APIs & Services.

Step 15: Configure the OAuth Consent Screen

Open OAuth consent screen.

For a personal setup, use External unless your use case is restricted to a Google Workspace organization.

Enter the requested application information, including:

App name
Support email
Developer contact email

If the OAuth application remains in testing mode, add the Google account you plan to use as a test user.

This is important because otherwise Google can return an access_denied or blocked-access message during sign-in.

Step 16: Enable Google Search Console API

This is an easy step to miss.

In Google Cloud Console, go to:

APIs & Services → Library

Search for:

Google Search Console API

Open it and click Enable.

Without enabling this API, the Search Console connection may fail even if your OAuth credentials are configured correctly.

Step 17: Create an OAuth Client ID

Go to:

APIs & Services → Credentials

Click:

Create Credentials → OAuth client ID

Set the application type to:

Web application

Then add this authorized redirect URI for a standard local Docker installation:

http://localhost:3001/api/gsc/oauth/callback

The redirect URI must match the address you actually use to access OpenSEO. The current OpenSEO documentation specifically gives the localhost:3001 callback for local Docker installations, and the scheme, hostname, and port need to match exactly.

Create the client.

Copy both:

Client ID
Client Secret

You’ll need both in the next step.

Step 18: Add Google Credentials to `.env`

Open your OpenSEO .env file.

Find these variables:

GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
BETTER_AUTH_SECRET=

Remove the # from each line if they are commented out.

Then add your Google Client ID and Client Secret.

For example:

GOOGLE_CLIENT_ID=YOUR_GOOGLE_CLIENT_ID
GOOGLE_CLIENT_SECRET=YOUR_GOOGLE_CLIENT_SECRET
BETTER_AUTH_SECRET=YOUR_RANDOM_SECRET

For BETTER_AUTH_SECRET, generate a random value with:

openssl rand -base64 32

The current OpenSEO Google Search Console documentation requires a random BETTER_AUTH_SECRET of at least 32 characters because it is used to protect stored OAuth credentials.

Copy the generated value into:

BETTER_AUTH_SECRET=

Then save the .env file.

Step 19: Recreate OpenSEO Again

Because you changed the environment file, recreate the container:

docker compose up -d --force-recreate

Wait for OpenSEO to start.

Then open:

http://localhost:3001

Step 20: Connect Google Search Console

Inside OpenSEO, open the Google Search Console setup or integration area.

Choose Connect with Google.

You may see Google’s OAuth warning or testing screen during the process. Continue through the authorization prompts.

After authorization, OpenSEO should allow you to select the Search Console property you want to connect.

Your Google account needs access to a verified Search Console property for a property to appear.

OpenSEO Docker Troubleshooting

OpenSEO won’t open at localhost:3001

First, check Docker Desktop.

Make sure the OpenSEO container is running.

You can also check the container directly from Command Prompt:

docker compose ps

If the container has stopped or failed during startup, check its logs:

docker compose logs -f

The official Docker documentation recommends checking the logs during startup if the application does not become available.

I changed `.env`, but OpenSEO doesn’t see the new value

Simply editing .env does not necessarily update an already-running container.

Run:

docker compose up -d --force-recreate

This recreates the container with the updated environment configuration.

My OpenRouter key isn’t working

First check that you have:

OPENROUTER_API_KEY=YOUR_KEY

in .env.

Then recreate the container:

docker compose up -d --force-recreate

You can also check the resolved Compose configuration:

docker compose config

The current OpenSEO Compose file explicitly forwards OPENROUTER_API_KEY, so you shouldn’t normally need to modify compose.yaml.

Google says access is blocked

If Google blocks the OAuth login while your app is in testing mode, go back to:

Google Cloud Console → OAuth consent screen → Test users

Add the Google account you’re using to connect OpenSEO.

Then try the connection again.

Google says the connection expired or the Search Console connection fails

Check that the following three variables are present:

GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
BETTER_AUTH_SECRET=

Then recreate the container:

docker compose up -d --force-recreate

Also make sure the Google Search Console API is enabled in your Google Cloud project.

No Search Console property appears

The Google account you’re using must have access to a verified Search Console property.

Verify the site in Google Search Console first, then reconnect OpenSEO.

How to Update OpenSEO

The Docker installation uses a published OpenSEO image from GitHub Container Registry.

To pull the newest published image and restart OpenSEO, use:

docker compose pull
docker compose up -d

You can also use:

docker compose up -d --pull always

The official repository documents both approaches for updating the Docker installation.

Is OpenSEO Free?

OpenSEO itself is open source and can be self-hosted, but its SEO data features rely on DataForSEO, which is a separate paid service. You pay DataForSEO directly based on usage when self-hosting.

The Docker setup is intended primarily for local use and testing. The current OpenSEO documentation warns that local Docker mode runs without normal application authentication, so you should not expose it directly to the public internet.

For an internet-facing installation, OpenSEO currently recommends its Cloudflare self-hosting approach instead.

Final OpenSEO Docker Setup

Once everything is configured, your local OpenSEO installation should look roughly like this:

Windows PC
   ↓
Docker Desktop
   ↓
OpenSEO container
   ↓
http://localhost:3001
   ↓
DataForSEO → SEO data
OpenRouter → AI features
Google Search Console → Search performance data

You can then use OpenSEO locally for keyword research, SERP analysis, domain research, saved keywords, and its AI features. The application also exposes an MCP server that can be connected to compatible AI clients.

Quick Command Reference

For convenience, here are the commands again:

git clone https://github.com/every-app/open-seo.git
cd open-seo

PowerShell:

Copy-Item .env.example .env

Command Prompt:

copy .env.example .env

Generate a Better Auth secret:

openssl rand -base64 32

Start OpenSEO:

docker compose up -d

Recreate it after changing .env:

docker compose up -d --force-recreate

Check the Compose configuration:

docker compose config

Check running containers:

docker compose ps

View logs:

docker compose logs -f

Update the Docker image:

docker compose pull
docker compose up -d

Once http://localhost:3001 loads successfully, your OpenSEO Docker installation is up and running.

What You Need Before Installing OpenSEO

OpenSEO Docker Commands

Clone OpenSEO

Open the project folder

Copy the environment file in PowerShell

Copy the environment file in Command Prompt

Generate a Better Auth secret

Start OpenSEO

Recreate OpenSEO after editing .env

Step 1: Install Docker Desktop

Step 2: Create a Folder for OpenSEO

Step 3: Open Command Prompt as Administrator

Step 4: Clone the OpenSEO Repository

Step 5: Enter the OpenSEO Folder

Step 6: Create the .env File

PowerShell

Command Prompt

Step 7: Add Your DataForSEO API Key

Keep Your API Key Private

Step 8: Start OpenSEO with Docker

Step 9: Open OpenSEO in Your Browser

Step 10: Test Keyword Research

How to Enable OpenSEO AI Features

Step 11: Create an OpenRouter API Key

Step 12: Add the OpenRouter Key to .env

Important: You Don’t Need to Edit compose.yaml Anymore

Step 13: Recreate the Docker Container

How to Connect Google Search Console to OpenSEO

Step 14: Create a Google Cloud Project

Step 15: Configure the OAuth Consent Screen

Step 16: Enable Google Search Console API

Step 17: Create an OAuth Client ID

Step 18: Add Google Credentials to .env

Step 19: Recreate OpenSEO Again

Step 20: Connect Google Search Console

OpenSEO Docker Troubleshooting

OpenSEO won’t open at localhost:3001

I changed .env, but OpenSEO doesn’t see the new value

My OpenRouter key isn’t working

Google says access is blocked

Google says the connection expired or the Search Console connection fails

No Search Console property appears

How to Update OpenSEO

Is OpenSEO Free?

Final OpenSEO Docker Setup

Quick Command Reference

Leave a Reply Cancel reply

Recreate OpenSEO after editing `.env`

Step 6: Create the `.env` File

Step 12: Add the OpenRouter Key to `.env`

Important: You Don’t Need to Edit `compose.yaml` Anymore

Step 18: Add Google Credentials to `.env`

I changed `.env`, but OpenSEO doesn’t see the new value