Self-host OpenGMB with Docker Compose

How do I configure it?

Clone the repository from github.com/synectus/OpenGMB, then work in the folder below.

cd deploy/selfhost
cp .env.example .env

Generate the secrets and paste them into the file:

openssl rand -hex 24      # POSTGRES_PASSWORD
openssl rand -base64 32   # BETTER_AUTH_SECRET
openssl rand -base64 32   # ENCRYPTION_KEY
openssl rand -base64 32   # AUDIT_CHECKPOINT_KEY

The file is git-ignored. Never commit it. These are all the settings it holds:

Owner login

Required settings

Host ports

Google

AI, rank tracking and images

Email

Push alerts

How do I start it?

docker compose up -d --build
docker compose ps
docker compose logs migrate

The first command builds one image, runs the migrations, then starts the web app, the MCP server and the worker. After it, postgres, web, mcp and worker should report healthy, and migrate should have exited with code 0.

What do I do on the first run?

1. Open your web address and sign in with the owner email and password from your settings file. The first start created the organization and this owner. Change the password in the app. After that the password in the file is ignored.
2. Set up two-factor sign-in for the owner login when the app asks.
3. Open Settings, then Google connection, and connect Google. This needs the OAuth client from your Google Cloud project, with both redirect URIs added: your web address followed by /api/google/callback and your web address followed by /api/auth/callback/google.
4. Write the audit log checkpoint for the organization that now exists. It refuses to run on an empty database, so do it after the first start has created the owner.

docker compose run --rm --no-deps mcp pnpm audit:checkpoint-backfill

To connect an AI agent, create an API token in the app under Settings, then API tokens, or from the command line:

docker compose run --rm --no-deps mcp pnpm token:create you@example.com "my laptop"

The command prints a claude mcp add line that uses the container port. Replace the address with your public one, which is your web address followed by /mcp. The MCP guide has the rest.

How do I turn on instant review alerts?

Without this, new reviews arrive when someone presses Sync. With it, Google pushes each new or edited review to your web app at /webhooks/google-pubsub within seconds. It runs in your own Google Cloud project. Do these steps once:

1. In the Google Cloud console, enable the My Business Notifications API for the same project as your OAuth client (APIs and Services, Library). If it is off, registering a Google account fails with a message naming this API.
2. Create a Pub/Sub topic (Pub/Sub, Topics). Copy its full name, which looks like projects/my-project/topics/opengmb-reviews.
3. On that topic, add mybusiness-api-pubsub@system.gserviceaccount.com as a principal with the Pub/Sub Publisher role (roles/pubsub.publisher). This is Google's own account for Business Profile notifications. If your organization blocks outside accounts, an organization policy exception may be needed.
4. Create a service account for delivery, then a push subscription on the topic. Set the endpoint to your web address followed by /webhooks/google-pubsub, turn on authentication with that service account, and set the audience to the same endpoint URL.
5. Put the topic name, the audience and the service account email in the settings file as PUBSUB_TOPIC, PUBSUB_AUDIENCE and PUBSUB_SERVICE_ACCOUNT_EMAIL, then restart the stack.
6. Connect Google, or reconnect it. New Google connections are registered automatically, and a daily check repairs any account that drifted.

The status page shows Instant review alerts as Live once the three settings are saved, at least one account is registered and a notification has arrived in the last 30 days. Until the first one arrives it reads Waiting for first notification.

How do I back it up?

All state is in the Postgres volume, including the job queue. Dump it from cron and copy the dump off the machine.

docker compose exec -T postgres sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" --format=custom' > backup.dump

To restore, start only the database and load the dump into it:

docker compose up -d postgres
docker compose exec -T postgres sh -c 'pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" --clean --if-exists' < backup.dump

How do I upgrade?

Take a backup first. Migrations run when the stack starts and only move forward. To roll back, restore the dump and check out the older version.

git pull
docker compose up -d --build
docker compose logs migrate

What if something goes wrong?

• Run docker compose config to print the resolved configuration. A missing required value is reported by name.
• Run docker compose logs -f web mcp worker for application logs. The worker prints which Pub/Sub settings are missing.
• Sign-in sends you to the wrong host: the web address setting must be the exact public URL, including https://.
• Google says redirect_uri_mismatch: the OAuth client needs two authorized redirect URIs, each exactly your web address followed by /api/google/callback (connect Google Business Profile) and /api/auth/callback/google (Sign in with Google).

Where next?

• Self-hosting overviewWhat you run, what you need and how Google access works.
• Connect an AI agentCreate a token and add the MCP server to Claude or Cursor.