Skip to main content
Skip to main content
🚧 Work in Progress

Customize PHP runtime environment

Build Custom Runtime Images​

Zerops allows you to build custom runtime images (CRI) when the default base runtime images don't meet your PHP application's requirements. This is an optional phase in the build and deploy pipeline.

Configuration​

Default PHP Runtime Environment​

The default PHP runtime environment contains:

  • Alpine 3.20
  • Selected version of PHP when the runtime service was created
  • zCLI
  • Git and Composer

When You Need a Custom Runtime Image​

If your PHP application needs more than what's included in the default environment, you'll need to build a custom runtime image. Common scenarios include:

  • System packages for processing: When your app processes images, videos, or files (requiring packages like sudo apk add --no-cache imagemagick)
  • PHP extensions: When you need additional PHP extensions not included by default
  • Native dependencies: When your Composer packages require system libraries that aren't in the default environment
  • Different base OS: When you need Ubuntu instead of Alpine for specific compatibility requirements
important

You should not include your application code in the custom runtime image, as your built/packaged code is deployed automatically into fresh containers.

Here are PHP-specific examples of configuring custom runtime images in your zerops.yml:

Basic PHP Setup​

run:
os: ubuntu
base: php-apache@8.4
prepareCommands:
- sudo apt-get install -y imagemagick
- composer global require some/package

Using Build Files in Runtime Preparation​

build:
addToRunPrepare:
- composer.json
- composer.lock
run:
prepareCommands:
- sudo apk add --no-cache imagemagick
- sudo apk add --no-cache ffmpeg
- composer install --no-dev

For complete configuration details, see the runtime prepare phase configuration guide.

Process and Caching​

How Runtime Prepare Works​

The runtime prepare process follows the same steps for all runtimes. See how runtime prepare works for the complete process details.

Caching Behavior​

Zerops caches custom runtime images to optimize deployment times. Learn about custom runtime image caching including when images are cached and reused.

Build Management​

For information about managing builds and deployments, see managing builds and deployments.

Warning

Shared storage mounts are not available during the runtime prepare phase.

Troubleshooting​

If your prepareCommands fail, check the prepare runtime log for specific error messages.

Overwrite php.ini files​

You can override PHP configuration directives by setting environment variables in your zerops.yaml file.

Here's an example of how to adjust PHP's post_max_size directive:

zerops:
# define hostname of your service
- setup: app
# ==== how to build your application ====
run:
# REQUIRED. Sets the base technology for the build environment:
base: php-nginx@8.3

# OPTIONAL. Defines the env variables for the build environment:
envVariables:
PHP_INI_post_max_size: 10M