Service: PHP Runner - EyevinnOSC/community GitHub Wiki

PHP Runner

PHP Runner (serviceId eyevinn-php-runner, catalog page) builds and runs PHP applications directly from a Git repository as an OSC "My Apps" service. It clones the repo, installs Composer dependencies and serves the app with Apache and mod_php (PHP 8.3). It is a long-running service instance. License: MIT. It is the PHP counterpart to Web Runner (Node.js), Python Runner, Golang Runner and .NET Runner.

What it can do

  • Clone a public or private Git repository (optionally a branch and a subdirectory for monorepos) and serve it.
  • Run composer install --no-dev --no-interaction automatically when a composer.json is present at the build root.
  • Serve with Apache and mod_php (PHP 8.3) with .htaccess and mod_rewrite enabled, so framework routing (Laravel, Symfony, Slim, Drupal and similar) works.
  • Auto-detect the document root, or let you pin it with OscEntry.
  • Run an optional setup.sh as root before Apache starts, for extra PHP extensions or OS packages.
  • Load environment variables at startup from an OSC App Config Service instance.

Creating an instance

Call create-service-instance with serviceId: "eyevinn-php-runner". The only required option besides name is SourceUrl. Names are alphanumeric, at most 20 characters.

{ "name": "myphpapp", "SourceUrl": "https://github.com/myorg/myphpapp" }

Private repository, monorepo subdirectory and branch:

{
  "name": "myservice",
  "SourceUrl": "https://github.com/myorg/monorepo#main",
  "GitHubToken": "{{secrets.ghtoken}}",
  "SubPath": "services/myservice"
}

Store the token first with create-service-secret (serviceId: "eyevinn-php-runner"). Verify with wait-for-service-ready or get-instance-status; use get-logs-for-instance to follow the clone and build, and describe-service-instance for the URL.

Options

Option Required Type Meaning
name Yes string Name of the instance. Alphanumeric, at most 20 characters.
SourceUrl Yes string HTTPS URL of the Git repository to clone and serve, e.g. https://github.com/your-org/your-php-app. Append #branchname for a specific branch; otherwise the default branch is used.
GitHubToken No string, sensitive Personal access token (e.g. a GitHub PAT) with read access, used to clone a private repository. Leave empty for public repositories.
OscAccessToken No string, sensitive OSC token used to authenticate with the OSC config service when loading environment variables at startup. Only used together with ConfigService.
ConfigService No string Name of the App Config Service instance to load environment variables from at startup. Only used together with OscAccessToken. Variables are loaded before dependencies are installed; a failure to load is logged without stopping the build.
ConfigApiKey No string, sensitive API key for the config service instance, if it requires one. The catalog describes it only as "API key for authentication".
SubPath No string Subdirectory inside the cloned repository to use as the app root (monorepos), e.g. services/my-php-app. Empty means the repository root.
AnalyticsService No string The catalog gives only the name; the previous version of this page described it as attaching an analytics service to the instance. Not verified further.
OscEntry No string Overrides the auto-detected document root: a directory relative to the app root, e.g. public.

GitHubToken, OscAccessToken and ConfigApiKey should be service secrets passed as {{secrets.NAME}}, which must be the entire field value. Overwriting a secret does not restart a running instance.

Using the instance

Serving model. Apache with mod_php runs in the foreground as the container's single process, listening on the PORT that OSC injects. This differs from the other OSC runners, which run a plain server directly. It is chosen so .htaccess and mod_rewrite behave as on a traditional PHP host. The runtime is pinned to PHP 8.3; selecting another version is not supported in this release.

Entry point detection, first match wins:

  1. OscEntry (if set)
  2. public/index.php (Laravel, Symfony, Slim)
  3. web/index.php (Drupal, some Symfony layouts)
  4. index.php at the repository root

If none is found the build fails. There is no special handling for framework dev servers such as artisan serve; set OscEntry if your layout differs.

Minimal app:

<?php
// public/index.php
header('Content-Type: text/plain');
echo "Hello from PHP Runner on OSC!\n";

System dependencies (setup.sh). Place a setup.sh at the repository root. It runs as root after composer install and before the app starts. Example:

#!/bin/bash
set -e
apt-get update -qq
apt-get install -y --no-install-recommends libzip-dev libpq-dev
docker-php-ext-install pdo_mysql gd intl
apt-get clean && rm -rf /var/lib/apt/lists/*

Parameter store. Create an App Config Service instance, store your values there, then set ConfigService to its name and OscAccessToken to your OSC token. The runner fetches all parameters on startup and injects them as environment variables before composer install, so they are available at install time and runtime.

Example with the OSC CLI:

osc create eyevinn-php-runner myphpapp -o SourceUrl="https://github.com/myorg/myphpapp"

Limitations

  • Memory limit is 512 Mi (256 Mi requested). nproc inside the container reports the node's CPU count (8), not your share, so cap build parallelism in setup.sh (for example -j2 when compiling extensions such as intl). A build killed for running out of memory leaves no log line. See My Apps Runtime Limits.
  • PHP version is fixed at 8.3.
  • HA mode and stage/prod promotion are not confirmed to be supported for PHP Runner in this release; check with the OSC team before relying on them.
  • It deploys your own Git repository as a service; it is not a general-purpose PHP hosting platform.

Resources