First-run setup

Introduction

First-run setup initializes an installation exactly once. It creates the first community and its Owner and is intended for the person responsible for the deployment. It is not a recurring administrative form.

When setup is available

Setup is available only when the database contains no community and no active Owner or Admin membership. `/` routes to `/setup` while that state is true and resolves the current session after initialization.

The API checks the state again when the form is submitted. A repeated request, or an inconsistent database that is not empty but is also not fully initialized, is rejected rather than creating another first community.

Before you begin

• Prepare the community name and a stable, unique slug.
• Prepare the individual Owner’s full name, controlled email address, and unique password.
• Choose the community’s default language and IANA timezone.
• Have the setup token available if SETUP_TOKEN is configured.
• Confirm the application URL and that API setup-status checks succeed.
• Know whether email delivery is configured. SMTP is not required to complete setup and can be configured afterward.

Information required

Setup token protection

SETUP_TOKEN is optional in the API, but it is recommended whenever an uninitialized installation is reachable by another person or network. When configured, setup fails unless the submitted value matches.

The current setup interface reads the token from `/setup?token=...` and sends it in the request body. Because a query value can remain in browser history and intermediary records, use the link only in a controlled session and clear it after setup. The API also accepts `x-setup-token` for non-browser clients.

openssl rand -hex 32

Complete the setup form

Client-side checks cover slug format, password confirmation, and the 8-character minimum. Server errors are shown as a setup failure, token rejection, email conflict, or already-completed state. If the response is uncertain, inspect setup status and API logs before submitting again.

• 1. Open the configured application URL and confirm that `/setup` is displayed.
• 2. Use the token-bearing setup URL when SETUP_TOKEN is configured.
• 3. Enter and review the community name and normalized slug.
• 4. Enter the Owner name, email, password, and matching confirmation.
• 5. Choose the default language and timezone.
• 6. Submit once and wait while the interface reports that it is creating the workspace.
• 7. On success, continue to `/login?setup=complete` and sign in.

What the platform creates

• Community foundation: the initial organization, community, Member profile for the Owner, and community settings with language and timezone defaults.
• Identity and access: the Owner user and active membership, Owner/Admin/Member roles, the current permission catalog, and default role-permission assignments.
• Communication defaults: community reminder and email settings, the Owner’s initial notification preferences, community message templates, and automation notification templates.
• Audit record: an `installation.initialized` community audit event with the selected language and timezone metadata.

What setup does not create

Setup does not seed operational or demonstration content. The community starts clean so the Owner can add real information deliberately.

• No demo members or applications.
• No announcements, events, tasks, or Task Board content.
• No chat conversations, email campaigns, or sample uploaded media.

Language and timezone behavior

The selected values become community defaults and are returned with the authenticated identity after sign-in. The web interface applies the community timezone to supported date and schedule views.

The community language is applied unless the browser already records an explicit user language choice. Changing interface language changes presentation, not stored business data. The current interface does not expose a separate per-user timezone preference; supported scheduling uses the community timezone.

Validation and failure behavior

The API validates required names, the normalized slug, Owner email format and uniqueness, password length, EN/FR language, a supported timezone, the configured setup token, and the installation state.

Initialization writes the required records in one database transaction. If it fails before commit, the platform does not intentionally retain a partially initialized community. Unique-state conflicts are reported as setup already completed.

After setup

• Confirm `/setup` is no longer available and sign in through `/login` as the Owner.
• Review Getting started, community Configuration, and Notification settings.
• Configure and test email before using email-dependent communication.
• Review permissions before creating individual Admin accounts or delegating access.
• Begin member onboarding and establish database and upload backups after meaningful configuration starts.

Security guidance

• Use a unique Owner password and keep the Owner account individual rather than shared.
• Create separate Admin accounts and grant only the permissions each person needs.
• Protect SETUP_TOKEN and runtime secrets from commits, shell history, screenshots, tickets, and logs.
• Keep account credentials separate from encrypted-chat backup files and recovery passwords.
• Verify setup is unavailable after completion.

Troubleshooting

• Setup page does not appear: confirm the setup-status response and whether a community or active privileged membership already exists.
• Token is rejected: confirm the URL-safe value exactly matches SETUP_TOKEN and was not truncated or URL-decoded incorrectly.
• Slug, email, or password is rejected: correct the normalized slug, use a valid controlled email, and satisfy password and confirmation checks.
• Request fails while services start: wait for PostgreSQL and API health, then inspect API migration and startup logs before retrying.
• Language or timezone seems stale after sign-in: sign out and back in, then verify community settings and any explicit browser language choice.

Related documentation

Continue with Getting started, Administration, Configuration, Notifications, Security, and Backup and restore. Use Troubleshooting when setup status or service readiness is unclear.