Skip to content

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.mdx
index 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 domai
For 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
```bash
openpanel up # Start all OpenPanel services
openpanel 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 services
openpanel 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.mdx
index 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 o
For 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_URL
diff --git a/apps/public/content/docs/self-hosting/google-search-console.mdx b/apps/public/content/docs/self-hosting/google-search-console.mdx
index 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.mdx
index 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
```bash
openpanel up # Start all OpenPanel services
openpanel 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
```bash
diff --git a/apps/public/content/docs/self-hosting/social-login.mdx b/apps/public/content/docs/self-hosting/social-login.mdx
index 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.ts
new file mode 100644
index 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.ts
index 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.yml
up | down | restart Start, stop, or recreate the stack
logs [service] Follow logs
status 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.ts
new file mode 100644
index 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([]);
+ });
+});