Repository navigation
Administrator 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.
| Component | Requirement |
|---|---|
| Stream Engine | Use a tagged release. This guide currently describes the 0.5 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 with InnoDB and utf8mb4_uca1400_ai_ci collation support. The included development environment currently uses MariaDB 12. Do not substitute MySQL without a separately tested compatibility statement. |
| 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. External S3-compatible storage is optional. |
| 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 must be able to:
- create and update
.envduring 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 MariaDB 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-reqscomposer 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.
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 MariaDB administration privileges.
For example, run the following as a MariaDB administrator after replacing the database name, account, host, and password:
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';MariaDB treats 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.
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:
-
.envmust 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
.envandstorage/; 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.
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 | 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. |
| External uploads | Configured S3-compatible bucket | Required when object storage is used; protect it through provider-side backup or replication. |
| 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.
Allow only the connections required by the deployment:
- public HTTPS traffic to the web server or load balancer;
- application-to-MariaDB and application-to-Memcached traffic on private or otherwise protected networks;
- application-to-SMTP traffic if email delivery is configured; and
- application-to-object-storage traffic if S3-compatible storage is used.
Do not expose MariaDB, Memcached, MinIO administration, PHP-FPM, or internal service ports to the public internet.
This is the documented production path. It gives the operator control over PHP-FPM, Nginx, filesystem permissions, MariaDB, Memcached, TLS, scheduling, and backup integration. Continue to Installation.
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 -dThen 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 is suitable only when it provides every required PHP extension,
a compatible 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.
- 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 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.