ngdpbase detects whether it has been configured on first access and shows a setup wizard if not. This page explains the full first-run process, what each step does, and how to handle edge cases.
The server checks for a .install-complete marker file at ${FAST_STORAGE}/.install-complete on every request. If the file does not exist, the setup wizard is shown instead of the platform.
Installation is considered required if any of the following are true:
.install-complete does not existNavigate to http://your-server:3000 in a browser. If installation is needed you will be redirected to /install.
| Field | Required | Description |
|---|---|---|
| Application Name | Yes | Display name shown in the browser tab and page headers |
| Base URL | Yes | Full URL users use to reach this instance (e.g. https://example.com) — used in links, RSS, and Schema.org metadata |
| Field | Required | Description |
|---|---|---|
| Admin Username | Yes | Username for the administrator account |
| Admin Password | Yes | Minimum 8 characters |
| Confirm Password | Yes | Must match Admin Password |
| Admin Email | Yes | Contact email for the admin — also used as the organization contact |
The admin username (admin) and email (admin@localhost) are fixed system values. The wizard sets the password only.
| Field | Required | Description |
|---|---|---|
| Organization Name | Yes | Short name — appears in page footers and Schema.org metadata |
| Legal Name | No | Full legal entity name |
| Description | Yes | Short description of the organization |
| Founding Date | No | ISO 8601 date (e.g. 2025-01-01) |
| Address Locality | No | City |
| Address Region | No | State or province |
| Address Country | No | Two-letter ISO country code (e.g. US) |
A checkbox lets you copy all required-pages/ content into your pages directory. This is checked by default and recommended — it populates the platform with documentation, help pages, and system pages needed for full functionality.
The wizard runs the following steps in order. Each is idempotent — if a step was already completed (e.g. from a previous partial run), it is skipped.
| Step | What it does |
|---|---|
| __writeConfig__ | Writes ${FAST_STORAGE}/config/app-custom-config.json with the application name, base URL, session secret, and organization details. A random 32-byte session secret is generated if not provided. |
| __writeOrganization__ | Creates ${FAST_STORAGE}/users/organizations.json with a Schema.org Organization object using the organization details from the form. |
| __updateAdminPassword__ | Sets the admin user's password to the value provided in the form. The admin user is created at startup using NGDPBASE_ADMIN_PASSWORD — this step replaces that bootstrap password. |
| __copyPages__ | Copies all .md files from required-pages/ to the pages directory. Existing pages are never overwritten. |
| __markComplete__ | Creates ${FAST_STORAGE}/.install-complete with a JSON marker containing the completion timestamp and version. |
If the wizard fails partway through (network error, disk full, etc.), the next visit to /install detects which steps already completed and skips them. Completed steps are shown on the form so you can see where to resume.
To reset a partial installation and start over from scratch, click the Reset Installation link on the install page. This:
app-custom-config.jsonorganizations.jsonusers.jsonBackups are created at the original path with a .backup-{timestamp} suffix.
For Docker, Kubernetes, or CI environments that cannot run the wizard, set HEADLESS_INSTALL=true in the environment. When the server starts and detects this variable with no .install-complete marker present, it:
config/*.example files to ${FAST_STORAGE}/config/ (skips files that already exist)required-pages/ to the pages directory (skips existing pages).install-complete markerThe admin account is created with the default password admin123. Change it immediately after first login — the startup banner warns for as long as the default is still in force. An operator who would rather it never held the default can point ngdpbase.user.security.defaultpassword at "$NGDPBASE_ADMIN_PASSWORD" and supply the value through the environment.
See Environment Configuration (.env) for details on the HEADLESS_INSTALL variable.
.install-complete MarkerLocation: ${FAST_STORAGE}/.install-complete
Format: JSON
{
"completedAt": "2026-01-15T10:30:00.000Z",
"version": "1.0.0"
}
Headless installations include an additional "headless": true field.
Do not delete this file on a running instance — the server will show the install wizard to all visitors and overwrite app-custom-config.json if the form is submitted again.
To force re-installation on purpose (e.g. to change the base URL or session secret), use the Reset Installation flow described above rather than deleting the marker directly.
After completing the wizard:
NGDPBASE_ADMIN_PASSWORD was set to)ngdpbase.base-url matches your actual server URL — incorrect values break links and RSSngdpbase.session.secret is a strong random value (auto-generated by wizard; only relevant if you edited the config manually)ngdpbase.session.secure: true if serving over HTTPS