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

  1. Create an empty MySQL or MariaDB database and a dedicated database user with all privileges on it, and on nothing else.
  2. 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.
  3. Upload the archive to the document root and extract it there. index.php, vendor/, themes/ and install/ must sit directly in the document root, not inside an extra package folder.
  4. 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.json and composer.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/ and storage/;
  • 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.

  1. License.Read the End User License Agreement and choose Accept and continue. Acceptance is recorded against the administrator account you create at the end.
  2. 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/ and install/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.
  3. Shape your workspace.Which levels, modules and website sections this organization has, the website's look, and what the site opens with. See below.
  4. 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.
  5. 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.
  6. 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.

Start from an industry
Company, Agency, Church, Nonprofit, Association or club, or Freelancer. A preset is a shortcut that ticks the switches below, not a separate mode — touch any switch afterwards and the preset simply stops being highlighted. While a card stays chosen, the new site's homepage, About Us, Privacy Policy and Terms of Use open with illustration scenes drawn for that industry. See Industry presets.
Your website's look
Since 1.13.8, Choose your website's look shows a picture card for each theme that comes with WBAMS, Serepok and Draisap: the theme visitors see on the public website and in their account, each in light and dark and fitting phones. An industry picks the theme suggested for it (Draisap for an agency or a freelancer, Serepok for the others) until you pick one yourself; without an industry, Serepok is picked. The theme can be switched at any time under Setup › Website themes, and the pages stay as they are.
The people you keep records about
Clients is always installed, because WBAMS bills and billing needs somebody to bill. Members and Staff are yours to choose. A chosen level's tables are created during setup, so its screens work on day one. See Management levels.
Modules
Whole parts of WBAMS some organizations run and others have no use for. Donations — gifts, donor history, receipts and recurring giving — is the module this release offers.
Website sections
Parts of the public website some organizations never publish: Updates, Knowledgebase, Galleries, Events and Client registration. A section that is off leaves no page, link or menu entry behind, and its records are kept either way.
What the site opens with
Example content, or Nothing but the homepage.
Galleries starts unticked.

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.

Declining something installs none of it.

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 legal pages are a draft, not legal advice.

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 wbams product. 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.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. 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.php keeps 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 core or vendor, and one the website uses for its own pages, such as account, knowledgebase, products or book.
  • 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.

The command line does not ask the workspace questions.

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.txt and https://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 .htaccess is 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.sql included. The directory ships an .htaccess that 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.

Fresh install versus update

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.