Install WBAMS 1.7.1

What the installer creates

The distribution seeds a 166-table baseline captured at 1.1.1—the CMS baseline with one published index.php homepage, a Support department, storage defaults, and file-asset settings—and then applies every incremental migration in the same pass, so a completed installation lands on WBAMS 1.6.0 rather than on the version the captured dump was taken at. It does not seed an administrator, customers, invoices, orders, tickets, Updates, knowledgebase articles, or migrated release history. The installer creates the first administrator only after license activation succeeds.

1. Prepare the environment

1. Create an empty database using a Unicode-compatible character set.
2. Create a database user limited to that database.
3. Copy settings.sample.php to settings.php and supply database credentials, the encryption hash, and writable storage paths.
4. Point the virtual host at the WBAMS root and enable rewrite rules.
5. Confirm PHP 8.1+ and the required extensions.

2. Web installation

Open /install/install.php. Six steps: the license, a check of the server, the shape of the workspace, the database connection, your administrator account, and what to do next. Nothing is written until step 5. After it finishes, sign in at /control/ and delete the setup directory.

3. Shape your workspace

The one step that is about the organization rather than the server, and the reason it comes before the database details: what you answer here decides which tables are created and what content is written.

Example content gives you a homepage, an About Us, a Privacy Policy and Terms of Use, the header and footer menus that reach them, seven updates and twenty-one knowledgebase articles. Everything is editable in the page builder and everything can be deleted.

Nothing but the homepage is literal: one homepage with a welcome on it, and no other pages, no menus at all, no updates and no articles. Of the choices on this screen it is the one that is awkward to reverse — content is quick to delete and slow to write — so it is the one worth a moment's thought.

What this means for upgrades

Nothing. An upgrade never reads these answers, never turns a module on or off, and never back-fills content that was declined. Migrations that touch an optional feature's tables are written to check the table exists first, so a clients-only installation and a church installation take the same upgrade path — the only difference is which guarded blocks do anything.

License verification and safe retry

The installer reports a safe diagnostic category when authorization cannot be completed: runtime capability, outbound HTTPS/TLS, license state, or installation binding. It may also provide a non-secret support reference. The browser and installer logs must never display or record the license key or the signed authorization payload.

• For a runtime failure, confirm Sodium and cURL are enabled in the website's PHP runtime.
• For a connection failure, confirm DNS, outbound HTTPS, and CA certificate validation without disabling TLS checks.
• For a license-state failure, verify that the license is active and permitted for this installation.
• For a product-assignment failure, confirm the license-server or WHMCS mapping uses the wbams product. A correct key shape alone does not establish that assignment.
• For a domain-authorization failure, correct the existing license's allow-list before retrying. Store the canonical public hostname only, without a scheme, path, or port. WBAMS normalizes www.example.org and example.org to the same hostname.
• If WHMCS owns the license, update the service's Licensed Domain Name and run Sync License Now. If the standalone licensing console owns it, edit the existing license and save its Allowed Domains. Reset activation seats only after the allow-list is correct and only when a stale installation already consumed a seat.
• For another binding failure, verify the exact public hostname, proxy/CDN scheme forwarding, installation path, and the server identity expected by the license record.

WBAMS keeps two values separate: the raw configured license key identifies the installation, while a signed local authorization is an opaque reusable cache. Signed-authorization persistence, revocation, and hostname detection do not depend on the normal global App facade, so they work during installer Step 4. Never paste the signed cache into a license-key field.

Step 4 writes settings.php, confirms the database connection, seeds the schema, persists the System URL, and then performs remote activation. Step 5 creates the administrator only after activation succeeds. A seeded database with version 0.0.0 after a license error is therefore an incomplete installation and can be retried with the complete 1.6.0 files on that same dedicated database. Use a new empty database if another application or abandoned installation has written to it.

Emptying the WBAMS database cannot repair an incorrect allowed-domain assignment, and resetting activation seats does not change that allow-list. Correct the license record first, then retry Step 4 against the same dedicated incomplete-install database.

The control_user_invites seed is idempotent, so repeating Step 4 can safely reuse that dedicated incomplete-install database. WBAMS 1.7.1 retains the installer-safe hostname behavior introduced in 1.0.3: activation derives the hostname from the System URL already persisted by Step 4 instead of calling the normal application facade, which is unavailable during a fresh install.

3. Command-line installation

php -d opcache.enable_cli=0 install/bin/installer.php --status
php -d opcache.enable_cli=0 install/bin/installer.php --install

Use --non-interactive only in controlled automation. The optional --config flag reads a JSON configuration object from standard input and must be combined with non-interactive mode.

4. After installation

• Confirm the dashboard reports WBAMS 1.7.1.
• Set the canonical HTTPS System URL.
• Change placeholder company, email, department, and invoice information.
• Configure scheduler execution and verify a completed daily run.
• Configure outgoing email and send a test message.
• Review storage configuration and test uploads/downloads.
• Enable multifactor authentication for privileged users.
• Back up the application, settings file, encryption hash, and database.
• Remove the complete install/ directory after the installation has been verified. The directory is always called install, and renaming it is not a substitute for deleting it: every file inside is still served, sql/install.sql included, and update.php only removes itself from a directory by that name. Since 1.3.2 the directory ships an .htaccess that denies everything except the scripts an installation actually runs, and since 1.3.3 the installer refuses to run against a database that already reports a version and an administrator. Deleting it outright is still the right answer.

5. Release qualification

A live package is not qualified by importing its schema or running seed checks alone. Release QA must drive the complete browser installer over HTTP against a disposable database and test license: license acceptance, preflight, configuration, administrator creation, finish, first sign-in, and installer-removal protection.

The same QA run must create a controlled license failure, verify the safe diagnostic category and absence of secrets, correct the cause, and complete the retry. Test through the same hostname, HTTPS termination, proxy/CDN path, and PHP runtime class used by the intended deployment.