Skip to content

Administrator Requirements

Jump to bottom
github-actions[bot] edited this page Nov 13, 2026 · 7 revisions

Administrator Guide: Requirements

Prepare and verify the application host before installing Stream Engine. This chapter distinguishes the production application requirements from the development-oriented Docker Compose environment included in the repository.

Supported application stack

Component Requirement
Stream Engine Use a tagged release. This guide currently describes the 0.7 release series.
PHP PHP 8.3 or newer, using PHP-FPM or another supported web-server integration. The command-line PHP used for installation, migrations, and scheduled tasks must load the same required extensions.
PHP extensions curl, dom, fileinfo, gd, intl, libxml, mbstring, memcached, pdo, pdo_mysql, simplexml, xmlreader, and zip.
Dependency manager Composer 2. A release archive may already contain vendor/, but Composer is required by the installation and migration commands documented here.
Database MariaDB 10.10 or newer, or MySQL 8.4 LTS or newer, with InnoDB. Continuous integration tests MariaDB 12 and MySQL 8.4; the included development environment uses MariaDB 12. See Database server for the differences between the two.
Cache A reachable Memcached service. Use a unique cache prefix when several sites share one service.
Web server Nginx is the documented production example. The public document root must be the application's public/ directory, never the application root. Equivalent servers must provide front-controller routing to public/index.php.
Scheduler A mechanism that runs php bin/cron.php once per minute in production, such as cron, a systemd timer, or a container scheduler.
Storage Persistent storage for .env, storage/, and local uploads. The current runtime upload service uses the local filesystem.
TLS HTTPS for every public production site. TLS normally terminates at Nginx, a load balancer, or a trusted reverse proxy.

The installer performs its own PHP, extension, release-file, filesystem, and database checks before changing installation state. Meeting this table does not bypass those checks.

PHP configuration

PHP must be able to:

  • create and update .env during installation;
  • read the application and Composer dependencies;
  • write installation state, task locks, error logs, Twig cache files, and local uploads to their configured locations;
  • connect to the database and Memcached; and
  • accept uploads large enough for the limits configured for the site and web server.

Check the CLI runtime before installation:

php -v
php -m
composer check-platform-reqs

composer check-platform-reqs is useful after dependencies have been installed. The web runtime can still differ from the CLI runtime, so confirm the PHP-FPM version and loaded extensions through service configuration or logs as well.

The optional Imagick extension with SVG support improves administrator-uploaded site-icon conversion. Without it, raster icons still work, but the application cannot publish an SVG version from an uploaded raster image.

Database server

Stream Engine supports two database servers. Choose one before installation and keep it for the life of the site.

Server Supported versions Table collation
MariaDB 10.10 or newer (needed for utf8mb4_uca1400_ai_ci) utf8mb4_uca1400_ai_ci
MySQL 8.4 LTS or newer utf8mb4_0900_ai_ci

The installer and the migration command detect the server from its version string and adapt the schema automatically; no setting is needed. On MySQL they also apply three other adjustments that do not change application behavior: column defaults such as unix_timestamp() are written as MySQL default expressions; the generated feeds.slug_parent_key column is virtual instead of stored, because MySQL does not allow a cascading foreign key on a base column of a stored generated column; and the mentions_exactly_one_target check constraint is omitted because MySQL does not allow a check constraint on a column whose foreign key cascades. The application always writes exactly one mention target itself.

Both collations are case- and accent-insensitive Unicode collations. MySQL's utf8mb4_0900_ai_ci is a NO PAD collation, so on MySQL 'abc' and 'abc ' are different values in comparisons and unique keys, while MariaDB treats them as equal.

Moving an existing site between MariaDB and MySQL is not supported: a logical dump from one server contains collations and syntax that the other rejects. Restore a backup onto the same server family it was taken from.

MySQL 5.7 and 8.0 are not supported. Versions of MariaDB before 10.10 lack the required collation.

Database preparation

Create an empty database and a dedicated application account. The application account must be able to create and alter the Stream Engine schema during installation and future migrations. It should not receive global database administration privileges.

For example, run the following as a database administrator after replacing the database name, account, host, and password. On MariaDB:

CREATE DATABASE stream_engine
    CHARACTER SET utf8mb4
    COLLATE utf8mb4_uca1400_ai_ci;

CREATE USER 'stream_engine'@'127.0.0.1'
    IDENTIFIED BY 'replace-with-a-random-database-password';

GRANT ALL PRIVILEGES ON stream_engine.*
    TO 'stream_engine'@'127.0.0.1';

On MySQL, use the same statements with COLLATE utf8mb4_0900_ai_ci.

MySQL and MariaDB treat accounts from localhost and 127.0.0.1 separately on many installations. Create the account for the actual connection host. For a remote database, restrict inbound network access to the application hosts and require transport encryption according to the database provider's instructions.

The installer accepts an empty database. It can also adopt an exact Stream Engine schema prepared by the migration command when the migration state is complete. It refuses unrelated or partially compatible databases.

Filesystem layout and ownership

A typical production layout is:

/srv/stream-engine/
├── .env
├── bin/
├── public/              web document root
├── storage/             writable persistent state
├── vendor/
└── ...                  read-only application release files

Before installation, the account running the installer needs to create or replace .env and write storage/. After installation:

  • .env must remain readable by PHP-FPM and CLI maintenance commands but must never be served by the web server;
  • storage/ and the configured upload, temporary, and Twig-cache directories must be writable by PHP-FPM;
  • the scheduler must run as an account with the same effective access to .env and storage/; and
  • other application files should be read-only to the web service account.

New .env files created by the installer use owner-only permissions. Do not solve permission problems by making the complete application tree world-writable.

Persistent state

Plan storage and backups around the state that cannot be recreated from a release:

State Default location Persistence requirement
Environment and secrets .env Required. Protect as a secret.
Database MySQL or MariaDB Required. Contains configuration, users, content, routing, and task state.
Installation and migration state storage/installation.json and storage/migrations.json Required with the deployed site.
Local uploads storage/uploads/ Required when local storage is used.
Runtime locks and error logs storage/ Must be writable; retention requirements depend on the file.

Application code, Composer dependencies, and compiled frontend assets should come from a known release and can be redeployed. They are not a substitute for a database and upload backup.

Network and external services

Allow only the connections required by the deployment:

  • public HTTPS traffic to the web server or load balancer;
  • application-to-database and application-to-Memcached traffic on private or otherwise protected networks;
  • application-to-SMTP traffic if email delivery is configured.

Do not expose the database server, Memcached, MinIO administration, PHP-FPM, or internal service ports to the public internet.

Choose a deployment model

Composer installation on a managed host or VPS

This is the documented production path. It gives the operator control over PHP-FPM, Nginx, filesystem permissions, the database, Memcached, TLS, scheduling, and backup integration. Continue to Installation.

Included Docker Compose environment

The repository's docker-compose.yml is intended for development and local evaluation. It uses APP_ENV=dev, contains public example credentials, mounts the working tree into containers, and publishes database and object-storage ports. It is not a production deployment template.

You may use it to evaluate installation locally:

docker compose build php
docker compose run --rm php composer install
docker compose up -d

Then open http://localhost:5000 and use the local database values documented in the installation chapter. Do not expose this environment to an untrusted network.

Shared hosting

Shared hosting is suitable only when it provides every required PHP extension, a supported MySQL or MariaDB service, Memcached, a document root that can point to public/, command-line access for installation and migrations, and a reliable once-per-minute scheduler. If any of these capabilities is missing, use a VPS, managed application host, or container platform instead.

Pre-installation checklist

  • A specific Stream Engine release series has been selected.
  • PHP 8.3 or newer and every required extension are available to both PHP-FPM and the CLI.
  • Composer 2 is available.
  • An empty MySQL or MariaDB database and dedicated account have been created.
  • Memcached is reachable from the application host.
  • The web document root can be set to public/.
  • Persistent, writable storage has been allocated.
  • The canonical HTTPS site URL and TLS termination are known.
  • A once-per-minute scheduler can be configured.
  • Database, .env, and upload backup destinations have been planned.

Back: Guide overview · Next: Installation

Stream Engine

Administrator Guide

Developer Guide

Clone this wiki locally