Designing MyBB 1.9’s Installer

One key to keeping software projects and the surrounding communities healthy is keeping friction for all audiences to a minimum.

In MyBB, this friction is derivative of user experience and developer experience. Our largest audience is formed by the end users — people browsing online forums, not expected to know what MyBB is, yet benefitting from fine-tuned visuals, phrases, and flows that come out-of-the-box. At the same time, we target two groups further down the forum assembly line, for whom both UX and DX apply.

For site owners and community leaders, the software needs to be approachable and intuitive — without requiring particular knowledge of languages and technologies — but also allow tweaking its look and functionality by maintainers with technical experience.

For developers, in addition to a useful extension system, APIs, and documentation, the software needs to expose the appropriate tools to allow speedy development and testing — without assuming one’s familiarity with it.

These factors are crucial in the world of free and open-source software, where the development relies on external contributors and their ease of work.

A setup mechanism is where their paths cross: it has to break down unavoidable complexity, without getting in expert users’ way. Besides having to meet best UX and DX practices, it also carries the weight of defining the first impression of the product for everyone.

The Need for Speed

kawaii — 2:56 PM

I wonder how many of the PostgreSQL installs are me with my Docker stack

People who work with, and on MyBB, install it a lot. To comfortably test new code and eliminate bugs in the core and extensions, their setup should require minimal time and attention better spent on the task at hand.

The existing installation experience left much to be desired — among others, the old installer:

A screenshot of the Table Creation page displayed during the installation of MyBB 1.8, with an unnecessarily long list of names of created tables.
              • is strictly synchronous and static, making users alternate between waiting and filling out forms,
              • asks for information that’s either nonessential (e.g. a website URL for the optionally displayed link), or derived (e.g. cookie settings that can be deduced from the forum URL),
              • contains technical details of little to no relevance, which also makes it more difficult to navigate,
              • loads pages only for the user to press Next, instead of proceeding automatically,
              • offers no shortcuts for quick setup for testing or development, and
              • can’t be scripted or automated.

The special part of the application accessed through install/ was largely self-contained and separate from the rest, offering a good target for improvements parallel to other work on the 1.9 series.

In this post, we share how the system was disassembled, redesigned, and rebuilt.

Key Changes

A snippet of new code for the installation "process" with individual operations defined as function callbacks; and a snippet demonstrating its usage, involving passing the parameters as a PHP array and calling a "run" method, which doesn't produce side effects.

The new implementation was expected not only to address the web GUI problems, but also to introduce a mirror interface for the command line, as well as a PHP API for direct execution.

Rather than tailoring the interfaces to any specific business logic, the GUI and CLI were generally prepared for miscellaneous future usage (i.a. by the Merge System, which currently has to carry its own UI).

Correspondingly, the existing activities — installation and upgrade — were rewritten as universal processes with controlled input, output, and better-isolated logic, while the miscellaneous, reusable code was refactored into functions.



The best kind of code improvement is its deletion. With MyBB 1.9 switching to file-based themes, the most time-consuming operation of inserting the templates into the database was safely removed. In the same spirit, the GNU GPL license agreement was left out, given that it relates to distribution, rather than usage of software. The installation’s final page was scrapped, and the summary information was moved to a Welcome to MyBB thread, which additionally serves as dummy content for new users to play with after being redirected there from the installer.

Process operations are executed automatically until user input is needed, without unnecessary confirmation or technical output. For example, the installer skips the full list of requirements — available on Download and Docs pages — and only produces relevant details when problems are found.

Input for settings related to HTTP cookies (responsible for the Domain and Path attributes) — effectively derivative of the Board URL — was removed, and the values are determined automatically instead. Similarly, the setting for the Secure flag will now be immediately enabled for HTTPS-based URLs.

The reorganization reduced the number of steps (and displayed screens) to four, grouping all related operations according to the types of data they depend upon (gathered using forms in the browser, or series of prompts in the CLI).

Ctrl V

Both processes were supplemented with a mechanism previously exclusive to the Admin Control Panel: checksum verification. Given the potential for various problems to occur during upload, MyBB will run an integrity check of its files during installation and upgrade.

Another feature brought in line with the core was language support: although a .lang.php phrases file was utilized, applying non-English languages required overwriting it, which was a pain point when distributing translations. In 1.9, the file was moved to the inc/languages/ structure, meaning that it can be supplied within ordinary language packs. When non-English packs are detected, a selection is displayed, and if just one extra language is present, it becomes the default option. This choice also changes the board’s Default Language, and that of the new administrator account.

Finally, the version check functionality was replicated in the GUI, allowing webmasters to easily confirm they are about to install, or update to, the application’s latest available version.


To help prevent accidental overwriting of data, signs of an existing instance will result in alternative headings and descriptions, indicating a reinstallation. As forgotten forums may appear broken for numerous reasons (e.g. failed database connection, or missing content), a more precise status is attached to the first step.

Lowering the bar for new forum owners, we made two improvements to the database credentials form — likely to be the most difficult one. First, the process now provides instant feedback for parameters at multiple stages (server connection, authentication, database access, and existence of old tables). Second, while the default database engine selection was already filtered according to enabled PHP extensions, the new process will also perform a number of educated guesses to pre-fill the rest of the form. This behavior may be especially beneficial to testers and developers who use standardized credential sets.

User Interfaces

Web UI

A screenshot of the Database page displayed during the installation of MyBB using the new system, with some fields filled out and annotated with "Discovered running server" and "Discovered accepted credentials" labels.

The new web-based interface uses a single index.php entry point, which contains fallback code to provide friendly error messages when PHP cannot be executed, or its version is not supported.

In MyBB 1.8 and before, when accessing the directory with a functional forum, administrators would be presented with an upgrade/install choice screen — this was simplified by opening the upgrade screen by default, with a link to force reinstallation for local network requests that indicate a non-production board.

The flow in the browser-based GUI is managed by a client-side controller, capable of handling input and output asynchronously, letting users fill out and submit subsequent forms as the attached operations execute in the background. A server-side controller provides fallback support for no-JavaScript clients.

More form fields take advantage of input verification and autocomplete features supported by browsers and password managers. Password fields were enriched with reveal toggles (in browsers other than Microsoft Edge, which provides the feature natively) — balancing the UX with the removal of redundant retype password input — and then placed at the end of forms to detect usage of other entered data (like site details, username, or email) for score calculation, powered by the zxcvbn library.

The auto-login feature was extended to likewise initialize a session for the Admin CP, enabling administrators to instantly explore it and finish configuring their forums.


The processes support flags that can be provided as URL parameters.

Developers can use the dev flag to skip File Verification and pre-fill administrator account details for quicker setup.

With the fast flag, the application will attempt a zero-click installation, proceeding automatically with provided data and defaults suitable for development.

When installing in development mode, an additional post is created in the welcome thread with convenient links to launch the process again and reset MyBB to its default state.

Over six years ago, we pointed out the tip-over in observed web traffic into the majority using HTTPS — today’s data shows that secure transmission for publicly-available sites is a universal standard. Although administrators of new forums should be well-aware of this, and have HTTPS already set up, some may delay this step until after the installation. This, of course, is dangerous, given that passwords and login keys already start being transmitted. Therefore, the installer warns about an unsafe connection for public network requests (limiting warning fatigue during non-production usage).

Consistent with our long-term development plans, the new setup system has no inline styles nor scripts, which allowed us to add a restrictive Content Security Policy by default.

The web implementation tracks the time of each operation using the Performance API, and the custom measurements can be observed using developer tools built into some web browsers.


The installer has been equipped with additional checks to prevent misuse. Previously, authentication was only required to access the upgrade script, but not installation, which may have allowed third parties to access it when the complete directory was uploaded and the lock file was deleted for upgrading.

The new system will check for additional, process-specific lock files, with lock_install created automatically. To reinstall the board, administrators will be also required to delete or empty the configuration file, which will provide another cue that existing data will be overwritten. These constraints don’t apply in a development environment, in which case a detailed installation status is simply shown on the first screen.

Authentication-related logic tied to the upgrade script was reworked by removing assumptions about the stability of initialization and credential handling, which may become temporarily broken during the upgrade process (e.g. after uploading new files, but before applying database changes). Instead, the upgrade process validates administrators’ sessions carried over from the forum front-end opportunistically, and otherwise relies on an ad-hoc proof by prompting them to create a temporary file with the name cryptographically tied to a cookie value.


A screenshot of a command line window with sections "Re-install Board" and "Connect to a Database" printed to the output, containing annotations about automatically matched credentials, and an input prompt with a default value.

The new bin/cli command line-executable PHP script, built with Symfony’s Console component, comes with commands for each maintenance process, walking users through steps in a fashion similar to the web GUI. It can also execute any of the processes non-interactively, allowing integration into various automated scripts.

When using this interface, the input can be:

  • provided interactively:

    Board URL:
  • passed as direct parameters with the command:

    $ bin/cli install --param bburl=
  • picked up from environment variables:

  • skipped entirely — by accepting defaults:

    $ bin/cli install --fast

    (here, we rely on database discovery and an existing installation, where the URL — unavailable in CLI mode — can be retrieved from old settings)

Similarly to the web mode, the commands support i.a. --dev and --fast flags, in addition to Symfony’s built-in usability and debugging options.

Maintenance Pages

The installer’s new look belongs to the new family of maintenance pages — used during special conditions of MyBB’s operation, and inspired by the design of the 1.9 front-end and the Project’s website.

Each condition was assigned a distinct color, and the pages differ in what elements are displayed according the subject in a given context: the board, or its underlying software.

MyBB’s own branding is toned down on the error and board closed pages — which usually depend on the individual environment and administrator’s activity — and appropriately displayed in full during installation and subsequent upgrades.

By handling thousands of support cases, we see how the subtle changes in error message phrasing reflect in future help requests, and have a general idea of how people — both the administrators and the users of their forums — respond to them. The error pages address both groups with specific (but still concise) suggestions for reaching out for technical assistance, depending on the circumstances and configured contact settings.

Data Reorganization

Data previously distributed — and uploaded — with the installation directory was absorbed into the core.

The permanent availability of the database schemas, initial data seeds, and upgrades — moved from install/resources/ to respective subdirectories under inc/ — will enable the core to i.a. extend its self-verification features to cover the database structure, and allow resetting settings to default values. This effort included a refactoring of some data from individual SQL queries to arrays, and increasing the usage of multi-row insert queries, yielding improved performance.

Given that static assets tied to the GUI were also extracted, any upgrade packages (Changed Files) involving the upgrade process for MyBB 1.9 will only contain: the entry point file, and truly new or modified resources — compared to the growing set of 80+ install/ files to upload (and remove shortly after) on MyBB ≤ 1.8.

Another kind of relocation was made to the file containing the application’s checksums: the once-online feature of File Verification, which would download it from the server before comparing it against the filesystem, was modified to include it in the package for offline verification, improving reliability and privacy.

Flattening Workflows

If you manage MyBB forums or develop extensions, you have likely encountered more broad friction: to run MyBB locally, a complete web stack has to be installed — including the HTTP server, PHP interpreter, and a database system. This can quickly become overwhelming if you need to test against various versions and systems to mimic your live forum’s setup, or investigate reported problems.

Our Docker Compose configuration — which already took care of setting up the web stack components — was recently updated to also install Composer dependencies for MyBB 1.9, and now, with the MyBB CLI, to install the application itself. This means that after the initial Docker installation, you can get MyBB up and running from the source (in any branch or Pull Request), without the overhead of setting up the underlying software on your host system, or manually handling the intermediate steps of installing dependencies — or MyBB — using a single command.

Similarly, the scriptable installer was used to create a default configuration for GitHub Codespaces — an additional layer that provides an instant web-based IDE to run, debug, and modify MyBB and its source code.

Go to the MyBB 1.9 development branch to preview the recent updates, try Codespaces with your free quota on GitHub, and help track down any problems in the new series of our forum software.

View on GitHub

If you like working on improvements — that are sometimes measured by how well they blend into the background — Get Involved.