OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.
self-hosting: openpanel reload applies .env changes
Carl-Gerhard Lindesvärd0b8e8542c9a1
diff --git a/apps/public/content/docs/self-hosting/deploy-docker-compose.mdx b/apps/public/content/docs/self-hosting/deploy-docker-compose.mdxindex ab0dbf09f..6ec9a8a08 100644--- a/apps/public/content/docs/self-hosting/deploy-docker-compose.mdx+++ b/apps/public/content/docs/self-hosting/deploy-docker-compose.mdx@@ -94,7 +94,7 @@ Once all services are healthy, you can access OpenPanel at your configured domaiFor a complete reference of all available environment variables, see the [Environment Variables documentation](/docs/self-hosting/environment-variables).<Callout>-If you change the `.env` file, run `openpanel restart` for the changes to take effect. It recreates the containers, which a plain `docker compose restart` does not, so the new values are actually picked up.+Changed the `.env` file? run `openpanel reload`. It checks the file for mistakes first, then recreates only the services whose settings changed; your databases keep running. A plain `docker compose restart` is not enough: it restarts containers with their old environment.</Callout>The generated `.env` also contains commented-out blocks for optional features. Uncomment and fill them in to enable [social login with Google or GitHub](/docs/self-hosting/social-login) and the [Google Search Console integration](/docs/self-hosting/google-search-console).@@ -124,7 +124,8 @@ Run these anywhere: the CLI finds your install (the current directory, `./self-h```bashopenpanel up # Start all OpenPanel servicesopenpanel down # Stop all OpenPanel services (data is kept)-openpanel restart # Recreate services, picking up a changed .env+openpanel reload # Apply changes to .env or docker-compose.yml+openpanel restart # Recreate every container (a full restart)openpanel logs # Follow logs from all servicesopenpanel status # Show running services```diff --git a/apps/public/content/docs/self-hosting/environment-variables.mdx b/apps/public/content/docs/self-hosting/environment-variables.mdxindex 7bd88ea52..b8a98cbed 100644--- a/apps/public/content/docs/self-hosting/environment-variables.mdx+++ b/apps/public/content/docs/self-hosting/environment-variables.mdx@@ -11,6 +11,10 @@ This page documents all environment variables used by OpenPanel. Variables are oFor deployment-specific configuration, see the [deployment guides](/docs/self-hosting/deploy-docker-compose).</Callout>+<Callout type="info">+After editing `.env`, run `openpanel reload`. It checks the file for mistakes first, then recreates only the services whose settings changed; your databases keep running. A plain `docker compose restart` is not enough: it restarts containers with their old environment.+</Callout>+## Database & Storage### DATABASE_URLdiff --git a/apps/public/content/docs/self-hosting/google-search-console.mdx b/apps/public/content/docs/self-hosting/google-search-console.mdxindex 7193164c5..f53ab5849 100644--- a/apps/public/content/docs/self-hosting/google-search-console.mdx+++ b/apps/public/content/docs/self-hosting/google-search-console.mdx@@ -90,7 +90,7 @@ Which services need which variables:The dashboard needs none of these. It asks the API whether the integration is configured.-How you set them depends on how you deployed OpenPanel. With the Docker Compose setup, add them to `self-hosting/.env` (all services read it) and run `docker compose up -d --force-recreate op-api op-worker`. With Coolify, the bundled template exposes `OPENPANEL_GOOGLE_CLIENT_ID`, `OPENPANEL_GOOGLE_CLIENT_SECRET` and `OPENPANEL_GSC_GOOGLE_REDIRECT_URI`, and generates `ENCRYPTION_KEY` for you. For any other setup, add them to the API and worker environment and restart both.+How you set them depends on how you deployed OpenPanel. With the Docker Compose setup, add them to your install's `.env` (all services read it) and run `openpanel reload`. With Coolify, the bundled template exposes `OPENPANEL_GOOGLE_CLIENT_ID`, `OPENPANEL_GOOGLE_CLIENT_SECRET` and `OPENPANEL_GSC_GOOGLE_REDIRECT_URI`, and generates `ENCRYPTION_KEY` for you. For any other setup, add them to the API and worker environment and restart both.</Step><Step>diff --git a/apps/public/content/docs/self-hosting/self-hosting.mdx b/apps/public/content/docs/self-hosting/self-hosting.mdxindex a50ff1af7..6f23492bd 100644--- a/apps/public/content/docs/self-hosting/self-hosting.mdx+++ b/apps/public/content/docs/self-hosting/self-hosting.mdx@@ -151,7 +151,7 @@ OpenPanel includes an AI-powered analytics assistant that can help you analyze d#### Configuration-Add one or both of the following to your `.env` file in your install directory, then run `openpanel restart`:+Add one or both of the following to your `.env` file in your install directory, then run `openpanel reload`:```bash title=".env"# OpenAI — get a key at platform.openai.com/api-keys@@ -206,11 +206,20 @@ Run these anywhere: the CLI finds your install (the current directory, `./self-h```bashopenpanel up # Start all OpenPanel servicesopenpanel down # Stop all OpenPanel services-openpanel restart # Recreate services so a changed .env takes effect+openpanel reload # Apply changes to .env or docker-compose.yml+openpanel restart # Recreate every container (a full restart)openpanel logs # Follow logs (openpanel logs op-api for one service)openpanel status # Show running services```+### Changed your .env?++```bash+openpanel reload+```++This applies your changes: it checks `.env` for mistakes first, then recreates only the services whose settings changed, so your databases keep running. `docker compose restart` does **not** pick up `.env` changes; the containers keep their old values.+### Diagnose```bashdiff --git a/apps/public/content/docs/self-hosting/social-login.mdx b/apps/public/content/docs/self-hosting/social-login.mdxindex 52b86c721..2c4befebf 100644--- a/apps/public/content/docs/self-hosting/social-login.mdx+++ b/apps/public/content/docs/self-hosting/social-login.mdx@@ -133,10 +133,10 @@ OpenPanel requests the `user:email` and `user:read` scopes and uses the account'All six variables belong to the API service. The dashboard and worker do not use them; the dashboard asks the API which providers are configured and renders buttons accordingly. Giving every service the full set is harmless, which is what the Docker Compose setup does.-How you set them depends on how you deployed OpenPanel. With the Docker Compose setup, add them to `self-hosting/.env` (the generated file already contains a commented-out template) and recreate the API container:+How you set them depends on how you deployed OpenPanel. With the Docker Compose setup, add them to your install's `.env` (the generated file already contains a commented-out template) and apply them:```bash-docker compose up -d --force-recreate op-api+openpanel reload```With Coolify, the bundled template exposes them as `OPENPANEL_GOOGLE_CLIENT_ID`, `OPENPANEL_GOOGLE_CLIENT_SECRET`, `OPENPANEL_GOOGLE_REDIRECT_URI`, `OPENPANEL_GITHUB_CLIENT_ID`, `OPENPANEL_GITHUB_CLIENT_SECRET` and `OPENPANEL_GITHUB_REDIRECT_URI`. For any other setup, add them to the API's environment the same way you set `COOKIE_SECRET` and restart the API.@@ -156,7 +156,7 @@ OpenPanel remembers the last provider a browser signed in with (a one-year cooki| Symptom | Likely cause ||---|---|| Google shows `Error 400: redirect_uri_mismatch`; GitHub shows "The redirect_uri MUST match the registered callback URL" | `GOOGLE_REDIRECT_URI` / `GITHUB_REDIRECT_URI` differs from the URL registered at the provider. Check `http` vs `https`, the `/api` prefix and trailing slashes. |-| Google shows `Error 401: invalid_client`, or the authorization URL has an empty `client_id` | `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` is not set on the API service, or the API was not restarted after changing `.env`. |+| Google shows `Error 401: invalid_client`, or the authorization URL has an empty `client_id` | `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` is not set on the API service, or the changes to `.env` were not applied (`openpanel reload`). || Redirected to `/login?error=Missing oauth parameters` or `OAuth state mismatch` | The state cookie set before the redirect was not sent back to the API. Usually the API and dashboard are on different registrable domains, `DASHBOARD_URL` is wrong, or the browser blocks cookies. See the cookie callout above. || `/login?error=Registrations are not allowed` | New user and `ALLOW_REGISTRATION=false` with no valid invite. Send an invite from the organisation settings or set `ALLOW_REGISTRATION=true`. || `/login?error=Please sign in using your original authentication method` | An account with that email already exists via another method. Sign in with that method instead. |diff --git a/self-hosting/cli/src/commands/reload.ts b/self-hosting/cli/src/commands/reload.tsnew file mode 100644index 000000000..2ddd8cd85--- /dev/null+++ b/self-hosting/cli/src/commands/reload.ts@@ -0,0 +1,41 @@+import { log as clackLog } from '@clack/prompts';+import { type Finding, runDoctor } from '../doctor';+import type { Install } from '../doctor/types';+import { isInstallDir, loadInstall } from '../install';+import { SEVERITY_LABEL } from '../ui';+import { compose } from './compose';++const ENV_CHECK_PREFIX = 'env/';++// Problems in .env that would stop the api from booting. Checked before+// anything restarts, so a typo does not take a running install down.+export const envBlockers = (install: Install): Finding[] =>+ runDoctor(install).filter(+ (finding) =>+ finding.id.startsWith(ENV_CHECK_PREFIX) && finding.severity === 'error'+ );++// `docker compose restart` keeps a container's old environment; `up -d`+// recreates exactly the services whose configuration changed (a new .env+// value, an edited docker-compose.yml) and leaves the rest, databases+// included, running.+export const reload = async (dir: string): Promise<number> => {+ if (!isInstallDir(dir)) {+ clackLog.error(`${dir} is not an OpenPanel install.`);+ return 1;+ }+ const blockers = envBlockers(loadInstall(dir));+ if (blockers.length > 0) {+ for (const finding of blockers) {+ clackLog.message(`${SEVERITY_LABEL[finding.severity]} ${finding.title}`);+ }+ clackLog.error(+ 'Fix these in .env first (details: `openpanel doctor`). Nothing was restarted.'+ );+ return 1;+ }+ clackLog.info(+ 'Applying changes to .env and docker-compose.yml. Only services whose configuration changed are recreated.'+ );+ return compose('up', dir);+};diff --git a/self-hosting/cli/src/main.ts b/self-hosting/cli/src/main.tsindex 630027340..12f03ade9 100644--- a/self-hosting/cli/src/main.ts+++ b/self-hosting/cli/src/main.ts@@ -4,6 +4,7 @@ import { compose, isComposeCommand } from './commands/compose';import { doctor } from './commands/doctor';import { exportData } from './commands/export';import { init } from './commands/init';+import { reload } from './commands/reload';import { reset } from './commands/reset';import { upgrade } from './commands/upgrade';import {@@ -28,6 +29,7 @@ Commands:export [--out <dir>] Dump ClickHouse data as JSONL (e.g. to move to Cloud)reset [--yes] Delete this install's data volumes (asks first)doctor [--fix] [--check] Check the host and your install; --fix repairs it+ reload Apply changes to .env or docker-compose.ymlup | down | restart Start, stop, or recreate the stacklogs [service] Follow logsstatus Show running services@@ -202,6 +204,9 @@ const route = async (noSelfUpdate: values['no-self-update'],});}+ if (command === 'reload') {+ return reload(await requireInstall(values.dir));+ }if (command === 'reset') {return reset({ dir: await requireInstall(values.dir), yes: values.yes });}diff --git a/self-hosting/cli/test/reload.test.ts b/self-hosting/cli/test/reload.test.tsnew file mode 100644index 000000000..a48638b86--- /dev/null+++ b/self-hosting/cli/test/reload.test.ts@@ -0,0 +1,46 @@+import { describe, expect, test } from 'bun:test';+import { parseDocument } from 'yaml';+import { envBlockers } from '../src/commands/reload';+import type { Install } from '../src/doctor/types';+import { EnvFile } from '../src/env-file';+import { templates } from '../src/templates';++const VALID_ENV = [+ 'KAFKA_BROKERS="op-rp:9092"',+ 'KAFKA_EVENTS_TOPIC_PARTITIONS="24"',+ `ENCRYPTION_KEY="${'ab'.repeat(32)}"`,+ 'COOKIE_SECRET="secret"',+ 'DASHBOARD_URL="https://a.example.com"',+ 'API_URL="https://a.example.com/api"',+ 'SELF_HOSTED="true"',+].join('\n');++const installWithEnv = (env: string): Install => ({+ compose: parseDocument(templates.compose),+ env: new EnvFile(env),+ caddyfile: null,+ files: new Map(),+ fileKind: () => 'file',+});++describe('envBlockers', () => {+ test('a valid .env has nothing blocking a reload', () => {+ expect(envBlockers(installWithEnv(VALID_ENV))).toEqual([]);+ });++ test('a .env that would stop the api from booting blocks it', () => {+ const broken = VALID_ENV.replace(/^COOKIE_SECRET=.*$/m, '').concat(+ '\nADMIN_USERNAME="admin"'+ );+ const ids = envBlockers(installWithEnv(broken)).map(+ (finding) => finding.id+ );+ expect(ids).toContain('env/cookie-secret');+ expect(ids).toContain('env/admin-credentials');+ });++ test('warnings and compose findings do not block a reload', () => {+ const noSelfHosted = VALID_ENV.replace(/^SELF_HOSTED=.*$/m, '');+ expect(envBlockers(installWithEnv(noSelfHosted))).toEqual([]);+ });+});