What the installer creates
The fresh distribution, wbams-v1.13.8-fresh-install.zip, seeds a 166-table baseline captured at 1.1.1 and then applies every incremental migration in the same pass, so a completed installation lands on WBAMS 1.13.8 rather than on the version the captured dump was taken at. What else it writes depends on the answers at Shape your workspace: the tables of a declined module are not created, and the example content is written only when you ask for it. It never seeds customers, invoices, orders or tickets, and it creates the first administrator only after license activation succeeds.
The archive contains the install/ installer, both client themes and the seed data. It does not contain database credentials, a license key, customer records, compiled templates, logs or uploaded files. Verify it against SHA256SUMS.txt before you extract it.
1. Prepare the environment
- Create an empty MySQL or MariaDB database and a dedicated database user with all privileges on it, and on nothing else.
- Assign PHP 8.3 or newer to the domain (in cPanel, MultiPHP Manager), with cURL, JSON, PDO, PDO MySQL, GD, XML and Sodium enabled for the website's PHP, not only for command-line PHP, and the free ionCube Loader 15 or newer (15.5 or newer on PHP 8.5) switched on for it: the installer checks it first and says what is missing. See System requirements.
- Upload the archive to the document root and extract it there.
index.php,vendor/,themes/andinstall/must sit directly in the document root, not inside an extra package folder. - Use HTTPS on the final public hostname before you enter any credentials. The license is bound to that hostname.
You do not need to create settings.php by hand: the system check creates it if the web server may write to the document root, and asks you to copy settings.sample.php to settings.php only when it cannot.
The protective .htaccess that ships
The archive includes a .htaccess in the document root. Before 1.11.0 a fresh install had none until friendly addresses were switched on, and on a host with folder listing on — cPanel's default — every folder without an index file could be browsed. The shipped file:
- turns folder listing off for the whole tree;
- refuses the package's own files (
SHA256SUMS.txt,composer.jsonandcomposer.lock, the Markdown files), every file whose name starts with a dot, and database dumps, logs, backups and configuration files; - refuses page templates (
.tpl), which WBAMS only ever reads from disk; - refuses the folders that are never requested directly, such as
resources/andstorage/; - sends the usual security headers.
These rules sit outside the ### BEGIN - WBAMS managed rules ### and ### END - WBAMS managed rules ### markers, because the installer rewrites everything between the markers at setup and on every later rule regeneration. If you replace the file, keep them outside the markers. cPanel's MultiPHP Manager adds a PHP handler block of its own when a PHP version is set; that block may stay. The full list of what is refused is in Operations and security.
2. Web installation
Open https://example.org/install/ (since 1.12.0 the folder address opens the installer; install/install.php works as well). Setup has six steps, shown down the left of the screen. Nothing is written to the database, and no details go into settings.php, until you press Install on step 4.
- License.Read the End User License Agreement and choose Accept and continue. Acceptance is recorded against the administrator account you create at the end.
- System check.PHP 8.3 or newer, a memory limit of at least 64M, cURL, JSON, PDO, Sodium, PDO MySQL, GD and XML, and write access to
settings.php,storage/private-files/,storage/downloads/,storage/cache/andinstall/log/. Only the checks that fail are listed; fix them and choose Check again. On a server that already runs WBAMS this step offers to upgrade instead. - Shape your workspace.Which levels, modules and website sections this organization has, the website's look, and what the site opens with. See below.
- Connect the database.The license key (checked for format here and activated at the next step), and the database hostname (usually
localhost), an optional port, the database name, the username and the password. The database must already exist and must be empty. - Administrator.Pressing Install writes
settings.php, confirms the connection, creates the tables your shape asks for, brings the schema up to 1.12.0, saves the System URL and activates the license. Only when all of that has worked does the administrator form appear: first and last name, email address, username, and a password of at least five characters. - Finish.Finish setup creates the administrator and shows what to do next: give the admin area an address of its own if you want one, delete the installer directory, add the scheduled task with the exact command for this server, keep
storage/writable but not browsable, and — when setup could not confirm that rewritten addresses reach WBAMS — turn on readable addresses under Setup › General Settings › Friendly URLs.
If something fails at the last step, Try again brings back the administrator form with everything but the password, and setup finishes what is left rather than starting over. The full error is in install/log/.
Step 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. Every answer can be changed later under Setup › Management Levels.
The Galleries switch is off when the step opens, and none of the industry presets ticks it. Tick it if you will publish albums, or switch it on later under Setup › Management Levels; its two tables are created at that moment.
No tables, no menu, no settings page — not a feature that is present and switched off. Turning it on later is one switch under Setup › Management Levels, and its tables are created at that moment, at the shape the release in use defines. Turning something off later never deletes its records.
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 and everything can be deleted.
Nothing but the homepage is literal: one homepage with a welcome on it, and no other pages, no header or footer menus, 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.
The Privacy Policy and Terms of Use that come with the example content say so on their own face. Read them, make them true of your organization, and have somebody qualified check them before you rely on them. They exist because a site that goes live with no policy at all is the worse outcome.
What this means for upgrades
Nothing. An upgrade never reads these answers, never turns a module or section on or off, and never back-fills content that was declined. Migrations that touch an optional feature's tables check that 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, not only for command-line PHP.
- For a connection failure, confirm DNS, outbound HTTPS, and CA certificate validation without disabling TLS checks. Confirm that a proxy or CDN forwards the original scheme and host.
- 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
wbamsproduct. A correct key shape alone does not establish that assignment; do not alter the key by hand. - 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.organdexample.orgto 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. Shared-hosting and proxy egress addresses may differ from the browser-visible address.
- Never paste the license key into tickets, screenshots, logs or public diagnostics. Send only the support reference and the diagnostic category.
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 setup. Never paste the signed cache into a license-key field.
Pressing Install on step 4 writes settings.php, confirms the database connection, seeds the schema, persists the System URL, and then performs remote activation. The administrator form appears only after activation succeeds. A seeded database with version 0.0.0 after a license error is therefore an incomplete installation, not proof that the license was accepted, and can be retried with the complete 1.12.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 while its stored version remains 0.0.0. Activation derives the hostname from the System URL already persisted at that point instead of calling the normal application facade, which is unavailable during a fresh install.
After installation, remote validation follows a seven-day schedule anchored to the installation timestamp. Normal admin requests validate the signed cache locally and do not reset that schedule; if a scheduled remote check cannot be completed, the signed outage-grace deadline applies.
Step 6: an address of its own for the admin area
The admin area starts at /control/, where every WBAMS starts. A name only you know keeps sign-in attempts away from it, and setup's last page offers one, in a card just above the one that says to delete install/: type a name after the site's address and choose Change the address. Setup names it in settings.php as $customadminpath and shows the new address. From then on /control/ no longer answers. To keep /control/, go straight on to the next card.
- Bookmark the new address. Nothing on the website links to it, and the installer's own pages stop offering a way into the admin area once it has moved. If it is ever forgotten,
settings.phpkeeps it. - The name is three to sixty-four letters, numbers, hyphens or underscores, starting with a letter or a number, and is kept in lower case. Setup refuses a name already used at the top of the site, such as
coreorvendor, and one the website uses for its own pages, such asaccount,knowledgebase,productsorbook. - Only the browser that finished setup can move it, and only within an hour. After that, or from any other browser, the page says it has expired and names no address. The admin area can still be given one later, as Control area describes.
Nothing else needs changing: every admin page follows the address, and updates keep it.
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.
It installs the default shape: Clients only, with Donations, Updates, Knowledgebase, Events and Client registration on, Galleries off, and the example content. Change any of it afterwards under Setup › Management Levels. The admin area stays at /control/; to give it an address of its own, move it by hand as Control area describes.
4. After installation
- Sign in at
https://example.org/control/, or at the address you gave the admin area at step 6, and confirm the dashboard reports WBAMS 1.13.1. - Open the public homepage, the knowledgebase, and a page from the menu: the menu marks the page you are on. Check light and dark mode.
- Confirm that
https://example.org/SHA256SUMS.txtandhttps://example.org/storage/are refused. Most servers answer Forbidden (403); some show the site's own "page not found" page instead, which is a refusal too. If the list of files or a folder listing comes back, the shipped.htaccessis missing or not honored — see above. - Remove the complete
install/directory. Renaming it is not a substitute for deleting it: every file inside is still served,sql/install.sqlincluded. The directory ships an.htaccessthat denies everything except the scripts an installation runs, and setup refuses to run against a database that already has a version and an administrator, but deleting it is still the right answer. - Add the scheduler to cron with the command step 6 showed, using the same PHP version as the website. See Set up the scheduler.
- Set the canonical HTTPS System URL, and turn on readable addresses under General Settings › Friendly URLs if setup could not.
- Fill in Setup › Business profile (name, contact details, address, hours, logos, colour and social links) and choose the business's time zone under General Settings › Localization. Then change the placeholder department and invoice information, and make the example legal pages true of your organization.
- Configure outgoing email and send a test message.
- Review storage configuration and test uploads and downloads.
- Enable two-factor authentication for privileged users.
- Back up the application,
settings.php, the encryption hash, and the database, and keep the original archive outside the public document root.
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, system check, workspace shape, 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.
The fresh distribution installs WBAMS 1.13.8 directly. Do not run a fresh installation over an existing production database. A site on 1.11.0 or earlier is upgraded with the release's files and the installer's Upgrade this installation, as Upgrading to 1.12.0 describes; from 1.12.0 on, use the incremental updater, which preserves settings.php, .htaccess, storage/ and uploaded media, and applies every migration missed on the way. See Updates, backups, and recovery.