SMF: a PHP forum with a BSD licence, two release branches and a container dev stack

What the repository is, and the two branches it maintains

Simple Machines Forum is free and open source community forum software. The project describes itself as delivering professional grade features in a package that lets you set up your own online community within minutes, and the site is at simplemachines.org.

The repository layout tells you this is a development repository rather than a release dump, and the branch organisation is the first thing to understand. The release-3.0 branch is where updates for version 3.0 are applied, and the release-2.1 branch is where updates for version 2.1 are applied. The default branch is release-3.0, and the pull request instructions say that a bug fix for version 3.0 goes to that branch, which means the 2.1 line is still being fixed rather than frozen.

The release history is consistent with that. The listed versions are 2.1.8 from 2026-10-11, 2.1.7 from 2026-03-08 and 2.1.6 from 2025-06-26, so the public releases are on the 2.1 line while the 3.0 work happens on the branch.

The tree itself is a complete forum application. Sources/ holds the PHP, Themes/ the presentation layer, Languages/ the translations, Packages/ the bundled libraries, attachments/ and avatars/ and Smileys/ the uploaded and static content, plus cache/ for generated files. There are also the entry points you would expect, index.php, cron.php, proxy.php, subscriptions.php and SSI.php for server side includes, with ssi_examples.php showing how that is used.

Installing from a release is a no-setup path, installing from source is not

There are two installation paths and the difference is large.

Using the official releases from the downloads website requires no additional setup, and the project points to a wiki guide for installing. That is the path most administrators take, and it is the reason the software can be set up within minutes.

Installing from the GitHub source requires Composer v2 or higher, and the dependencies are installed with a composer install.

    composer install

If you are doing development work you want the developer dependencies as well, and the documented way to get them is to prepend COMPOSER_NO_DEV=0 to the command.

    COMPOSER_NO_DEV=0 composer install

The same applies when updating after a git pull, where the project warns you may run into issues if you do not update Composer, and the developer form of the command is used.

    COMPOSER_NO_DEV=0 composer update

That last point is a genuine footgun rather than a formality. The environment variable defaults to a mode that skips development packages, so an update without it can quietly remove the tooling you need, and a pull followed by an update done the wrong way is exactly how that happens.

The compose file runs both database engines so the choice stays a setting

The repository ships a development environment in compose.yaml, and its header explains the intent. Both database engines SMF supports are running, MySQL is what the forum is pointed at by default, and setting SMF_DB_TYPE=postgresql in .env switches to the other. Everything has a working default, so no .env file is required, and you copy .docker/env.example to .env if you want to change ports or credentials.

The service is called web and builds from .docker/php/Dockerfile with a PHP_VERSION argument that defaults to 8.4. The checkout is bind mounted into the container, so edits on the host are live immediately, and the service waits for both databases to report healthy before it starts.

The per-engine settings are what make the switch a single change.

      SMF_DB_TYPE: ${SMF_DB_TYPE:-mysql}
      SMF_DB_NAME: ${DB_NAME:-smf}
      SMF_DB_USER: ${DB_USER:-smf}
      SMF_DB_PASSWD: ${DB_PASSWORD:-smf}
      SMF_MYSQL_SERVER: mysql
      SMF_MYSQL_PORT: "3306"
      SMF_POSTGRES_SERVER: postgres
      SMF_POSTGRES_PORT: "5432"

The MySQL container is published on host port 3307 by default, specifically so it cannot collide with a local MySQL, which is a small sign that the authors have run this on real machines. The generated Settings.php points at whichever engine is selected, so a developer can check the same change against both backends without touching the code.

Contributing means sign-off, and a rule about the vendor directory

The contribution rules are specific and are the clearest part of the project's conventions.

Fork the repository, branch it, and sign off your commits. The project explains why in the note about the Developer's Certificate of Origin in the repository: by signing off your contributions, you acknowledge that you can and do license your submissions under the licence of the project. A sign-off line is enough, either written as Signed-off by: followed by your name and email, or by defining a git alias that adds the -s switch to your commit command, so this is a habit rather than a chore if you set the alias up front. Then you send a pull request.

There is one rule that catches contributors out. Do not modify the vendor directory. Instead, update the appropriate dependency in composer.json, run composer update, and then commit both composer.json and composer.lock. That is the convention that keeps the lock file honest across the whole project.

The tree also shows the tooling the project uses on itself, with a GitHub Actions workflow for PHP and a separate one for Crowdin, which is the translation platform, a .php-cs-fixer.dist.php configuration for code style, a .scrutinizer.yml for static analysis, a phpunit configuration and a tests/ directory. There are also AGENTS.md and CLAUDE.md files at the root, which are instructions aimed at coding agents working in the repository, and a .dev/ directory for local tooling.

Licensing is BSD for the software and CC-by-SA for the documentation

The licence story has three parts and they are worth separating before you fork anything.

The software itself is under the BSD 3-clause licence, which the README links directly to the Open Source Initiative text. The repository topics also carry the bsd-3-clause tag. The project's metadata classifies the licence in the repository as a custom one that GitHub cannot classify, and there is a LICENSE file at the root, so read that file if you need the exact terms rather than assuming the three clause text is verbatim what ships.

Documentation contributions are under CC-by-SA 3, which is a share-alike licence with a different character from the software licence, and third party libraries or image sets are under their own licences. That third clause is the one that bites in practice, because the bundled code in Packages/ and the images in Smileys/ are not covered by the project licence, and a redistribution has to carry their terms too.

The fork invitation in the README is unconditional. You are free to fork the repository and make your desired changes, which is the simplest possible answer to the question of whether you may run your own version of this forum.

Security reports go to a dedicated channel, not to the issue tracker

The security process is separated from ordinary bug reporting, and the README is explicit about it. If you have a security issue to notify about SMF for any version, the project asks you to file a security report on its own website rather than opening a public issue, and it points to SECURITY.md for the fuller policy.

That is the standard arrangement and it is the right one, since a public issue gives an attacker a head start. The detail worth noting is the scope, which says for any version, so the reporting channel covers older branches as well as the current one. For a project with a 2.1 line and a 3.0 line in parallel, that matters.

The normal support route is the issue tracker, and the general contribution guidance asks people to file issues and pull requests rather than to email the maintainers, on the grounds that questions and solutions stay visible and searchable for the whole community. The badges at the top of the README show a PHP build workflow and a Crowdin workflow, which tells you the continuous integration runs on pull requests and that translations are pulled from a translation platform rather than edited by hand in the repository.

Where SMF is the wrong choice

The first case is a new community that wants a modern application stack. SMF is a classic PHP forum with a long history and its own conventions, and the 3.0 line is a rewrite in progress rather than a settled modern architecture. If your requirement list includes things like a typed backend, an API first design or a deployment model built around containers, the mismatch is not a configuration detail.

The second case is a team that does not want to run Composer at all. Installing from a release is genuinely quick, but from source the dependency step is manual, and the update path has a documented sharp edge where a wrong Composer invocation leaves you without developer dependencies. That is a manageable amount of friction, and it is friction nonetheless.

The third case is expecting the 3.0 branch to be a finished product. The public releases are on 2.1, the 3.0 work sits on a branch, and the project is explicit that bug fixes for 3.0 go to release-3.0. If you need a version with a predictable upgrade path and published release notes, 2.1.8 is the one to run, and 3.0 is what you watch.

Editorial conclusion

Adopt SMF if you want a self hosted forum that you can install in minutes from a release package and still have a source repository with an active security and documentation process behind it. Do not adopt it if you need a modern stack, because the 2.x and 3.x lines carry their own conventions and the composer workflow is a manual step rather than a build pipeline. Before you deploy, read SECURITY.md and file security reports through the project's own reporting page rather than the tracker, decide which branch you are on, and keep the developer dependencies out of production by running composer install without COMPOSER_NO_DEV=0.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. SimpleMachines/SMF on GitHub