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-interactionautomatically when acomposer.jsonis present at the build root. - Serve with Apache and mod_php (PHP 8.3) with
.htaccessandmod_rewriteenabled, 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.shas 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:
OscEntry(if set)public/index.php(Laravel, Symfony, Slim)web/index.php(Drupal, some Symfony layouts)index.phpat 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).
nprocinside the container reports the node's CPU count (8), not your share, so cap build parallelism insetup.sh(for example-j2when compiling extensions such asintl). 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.