faulo/farah repository overview

⁠Farah CMS server for Linux and Windows containers

faulo/farah⁠ runs Farah CMS applications with Apache, PHP, and Composer on Linux and Windows. Choose a PHP release, mount your application, and let the included launcher install its Composer dependencies before starting the web server.

The image includes a minimal Farah application, a built-in HTTP health check, and tools for image processing, browser automation, and archive handling.

Docker Hub⁠ · Image tags⁠ · Report an issue⁠

⁠Available images

PHP variants are available for 7.4, 8.0, 8.1, 8.2, 8.3, 8.4, and 8.5. The latest tag family currently aliases PHP 8.5.

The same versioned tag structure applies to every PHP variant. Use latest for automatic platform selection, a PHP tag to select a release line, or a platform-specific tag when your deployment needs one. Use an image digest when a deployment needs a fixed image revision.

Linux variants use Debian Trixie Slim. Windows variants use faulo/choco:windowsservercore-ltsc2019 and require a compatible Windows container engine and isolation mode.

Legacy PHP variants remain available for compatibility. PHP 7.4 through 8.1 no longer receive upstream security updates; consult PHP's supported versions⁠ when choosing a release.

⁠Quick start

Start the bundled application:

docker run --detach --name farah --publish 8080:80 faulo/farah:latest

Open http://localhost:8080/slothsoft@farah/phpinfo⁠ to view the PHP information page. The bundled application provides this endpoint without an application mount; a site homepage requires your own application and sitemap.

Inspect startup output and run the health probe:

docker logs --follow farah
docker exec farah farah health

The container listens on HTTP port 80. Its default command is farah serve. Supplying another command replaces server startup completely:

docker run --rm faulo/farah:latest php --version
docker run --rm faulo/farah:latest composer --version

⁠Run your application

Your application directory should contain its composer.json, optional composer.lock, and public files under html/. Require slothsoft/farah and register your sitemap from your application's Composer bootstrap, typically with Kernel::setCurrentSitemap(). The image does not supply a site sitemap.

For a Linux container engine, save this as compose.yaml and place your application in ./app:

services:
  farah:
    image: faulo/farah:latest-linux
    ports:
      - "8080:80"
    environment:
      SERVER_NAME: localhost
      COMPOSER_UPDATE: install
    volumes:
      - type: bind
        source: ./app
        target: /var/www

For a Windows container engine, use this configuration instead:

services:
  farah:
    image: faulo/farah:latest-windows
    ports:
      - "8080:80"
    environment:
      SERVER_NAME: localhost
      COMPOSER_UPDATE: install
    volumes:
      - type: bind
        source: ./app
        target: c:/www

Start the server:

docker compose up -d
docker compose logs --follow farah

The application mount replaces the bundled application. Startup runs Composer in the application root, so the mount must allow dependency installation unless you supply an existing vendor/ directory and set COMPOSER_UPDATE=skip. On Linux, Apache serves requests as www-data; give that user read access to application files and write access to any application-managed data directories.

The test application⁠ demonstrates Composer bootstrap and sitemap registration.

⁠Application paths

Apache routes requests without a matching public resource through the bundled Farah front controller. The /slothsoft@farah/phpinfo route also provides the endpoint used by the image's health check.

⁠Configuration

Set FARAH_PAGE_TYPE=xml for application/xhtml+xml, or FARAH_PAGE_TYPE=html for text/html. Asset URLs do not inherit this setting.

⁠Composer startup modes

COMPOSER_UPDATE is case-sensitive. Every Composer invocation uses --no-interaction.

Modes without development packages also use --optimize-autoloader and --classmap-authoritative. Unknown modes and Composer failures produce warnings and allow Apache to start; inspect startup logs when dependencies are missing. Use skip when dependencies are prepared during your own image build.

⁠PHP and server defaults

The bundled PHP configuration enables error display and logging, allows up to 1 GiB per upload, and sets a 4 GiB memory limit. Review these settings and access to the PHP information endpoint for your deployment. Configuration sources are linux/php.ini⁠, windows/php.ini⁠, linux/apache.conf⁠, and windows/apache.conf⁠.

⁠Included tools

Linux PHP packages include curl, DS, GD, Imagick, IMAP, Intl, Mbstring, MySQL, XML, and Zip extensions. Exact package and extension declarations are maintained in linux/⁠ and windows/⁠, including a manifest for each PHP release. Linux applications must use native Linux executables; Wine is not included.

⁠Development and tests

The native launcher and its NUnit tests live in common/⁠. With the .NET 9 SDK installed, run the launcher tests without Docker:

dotnet test docker-farah.sln --configuration Release --logger junit

The Pester integration tests in tests/⁠ cover installed tools, PHP versions and extensions, Composer, Firefox, server startup, command overrides, HTTP responses, page media types, and the health probe.

Both Dockerfiles use the repository root as their build context. PHP_VERSION defaults to 8.2 in local builds; pass it explicitly to match a published PHP variant. Build with a container engine matching the selected platform:

docker build --build-arg PHP_VERSION=8.5 --tag tmp/farah:latest --file linux/Dockerfile .

docker build --build-arg PHP_VERSION=8.5 --tag tmp/farah:latest --file windows/Dockerfile .

Images are rebuilt on a monthly schedule and when changes are published. The shared Docker publication workflow⁠ reads docker.json⁠ for PHP variants, native builds, public tags, and Docker Hub metadata.

⁠Support and contributions

Report bugs and feature requests through GitHub issues⁠. Include the image tag or digest, PHP version, container OS and architecture, Docker version, and a minimal reproduction with credentials removed. For Windows issues, include the isolation mode where relevant.

Contributions are welcome. Add tests for behavior changes, keep shared launcher code in common/, and maintain platform packaging in linux/ or windows/.

⁠License

The repository's code and documentation are licensed under the MIT License⁠. Bundled applications, libraries, and tools retain their respective licenses.