Installation and First-Run Setup
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.
How Installation Is Triggered
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-completedoes not exist- No admin user exists
- The pages directory is empty
Setup Wizard Walkthrough
Navigate to http://your-server:3000 in a browser. If installation is needed you will be redirected to /install.
Step 1 — Application Settings
| 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 |
Step 2 — Admin Account
| 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.
Step 3 — Organization
| 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) |
Step 4 — Startup Pages
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.
What Happens During Installation
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 default admin user (admin / admin123) is always created by the system at startup — this step replaces the default 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. |
Partial Installation Recovery
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:
- Backs up and removes
app-custom-config.json - Backs up and removes
organizations.json - Backs up and removes the admin user from
users.json - Backs up and removes copied pages from the pages directory
- Reloads the user cache
Backups are created at the original path with a .backup-{timestamp} suffix.
Headless / Automated Installation
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:
- Copies
config/*.examplefiles to${FAST_STORAGE}/config/(skips files that already exist) - Copies
required-pages/to the pages directory (skips existing pages) - Creates the
.install-completemarker
The default admin credentials remain admin / admin123. Change the password immediately after first login, or pre-configure a custom password by editing the instance config before starting the server.
See Environment Configuration (.env) for details on the HEADLESS_INSTALL variable.
The .install-complete Marker
Location: ${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.
Post-Installation Checklist
After completing the wizard:
- Change the admin password if using a headless install (default:
admin123) - Verify
ngdpbase.base-urlmatches your actual server URL — incorrect values break links and RSS - Verify
ngdpbase.session.secretis a strong random value (auto-generated by wizard; only relevant if you edited the config manually) - For production: set
ngdpbase.session.secure: trueif serving over HTTPS - Review Configuration Properties Reference for any additional settings to tune
No comments yet.