First Owner Setup

Updated: 2026-09-03

The first-owner setup page creates the initial Owner account after a successful fresh product installation.

Purpose

A fresh install does not require manual SQL edits to create the first usable administrator account. The supported installer prepares the database and application first; the operator then creates the initial Owner through the application.

The setup flow is intentionally narrow:

works only when there is no active Owner account;
creates the first Owner account;
stores the password with password_hash();
requires the established user-selected password minimum of 12 characters;
assigns the Owner role;
logs the new Owner in;
locks itself automatically once an active Owner exists;
fails closed if it cannot safely determine whether an Owner already exists.

URL

/setup-owner.php

On a local install using the default web port:

http://127.0.0.1:8080/setup-owner.php

If WEB_PORT was changed in .env, use that localhost port instead.

Before using the page

For a fresh product installation, first complete:

bash tools/recipe-site-install.sh

The installer must end with:

INSTALL=PASS

That means the clean v1 database baseline has been loaded, any explicitly classified post-baseline migrations have been applied, containers are running, and product health checks passed.

Also make sure you use HTTPS if accessing the page over a network.

Expected behavior

Fresh install with no Owner

The page shows the first-owner setup form. After a valid submission it creates the Owner account and logs the new Owner in.

Existing install with active Owner

The page refuses setup and indicates that first-owner setup is already complete. It must not allow another Owner to be created through this bootstrap route.

Database/schema uncertainty

If the application cannot safely check whether an active Owner exists, setup fails closed rather than assuming it is safe to create one.

After creating the Owner

Reload /setup-owner.php and confirm it refuses another first-owner setup.
Open the account menu.
Confirm Owner/admin pages are available.
Review Admin -> Site Settings and replace generic branding/contact defaults where appropriate.
Create or approve additional users through the normal account/admin flow.
Configure HTTPS/public routing if the site has not yet been exposed through its production reverse proxy/tunnel.

Existing-site check

With the default local port:

curl -s http://127.0.0.1:8080/setup-owner.php | grep -Ei 'complete|already|owner|setup' | head

An established site should indicate that first-owner setup is already complete.

Notes

The setup page is not a general user-management tool. After the first Owner exists, user creation and role management belong in the normal account request/admin flows.

Do not keep one-off owner-creation helper scripts in www/.