Docker Image for Swoole

This image is built for general-purpose. We have different examples included in this Git repository to help developers to get familiar with the image and Swoole.

You can get the image from here.

Table of Contents

• Feature List
• How to Use This Image
  • How to Install More PHP Extensions
  • Serializer and Compression Support in Extension Redis
  • DNS Resolution in Coroutines (c-ares)
  • Disable Installed/Enabled PHP Extensions
  • More Examples
• Image Variants
• Supported Tags and Respective Dockerfile Links
  • Versioned images
    • Swoole 6.3
    • Swoole 6.2
    • Swoole 6.1
    • Swoole 6.0
    • Swoole 5.1
    • Swoole 5.0
    • Swoole 4.8
  • Nightly images
• Build Images Manually
• Credits

Feature List

• Built-in scripts to rebuild Swoole and to manage Supervisord programs.
• Easy to manage booting scripts in Docker.
• Allow running PHP scripts and other commands directly in different environments (including ECS).
• Use one root filesystem for simplicity (one Docker COPY command only in dockerfiles).
• Composer included (Composer v1 for Swoole 4.5.8 and before; Composer v2 for Swoole 4.5.9 and after).
• Built for different architectures.
• Support auto-reloading for local development.¹
• Support code debugging for local development.
• PHP extension pdo_mysql included since 4.8.12+ and 5.0.1+.²
• PHP extension Redis included since 4.8.12+ and 5.0.1+.² The igbinary serializer is enabled in nightly images and in 6.3.0+ images, while the msgpack serializer is not enabled; the lzf and zstd compressions are enabled in nightly images and in 6.1.10+ and 6.2.2+ images.³
• Swoole built with c-ares for asynchronous DNS resolution in coroutines, in nightly images and in 6.3.0+ images.⁴

NOTES

1. The auto-reloading feature is supported for non-Alpine images only.
2. To disable extension pdo_mysql and/or Redis, please check section Disable Installed/Enabled PHP Extensions.
3. For details, please check section Serializer and Compression Support in Extension Redis.
4. For details, please check section DNS Resolution in Coroutines (c-ares).

How to Use This Image

The phpswoole/swoole image is built using the official PHP image as base image, with a few changes. For basic usage, please check the description section of the official PHP image.

How to Install More PHP Extensions

Same as in the official PHP image, most PHP extensions can be installed/configured using built-in helper scripts docker-php-ext-configure, docker-php-ext-install, docker-php-ext-enable, and docker-php-source. Here are some examples.

Install the -dev packages an extension is built against first, as in the official PHP image. Nightly images and 6.3.0+ images no longer come with the -dev packages that earlier images happened to leave behind (e.g., libgmp-dev, libldap-dev, libkrb5-dev and libzstd-dev), so a command like docker-php-ext-install gmp ldap now needs a preceding apt-get install -y libgmp-dev libldap-dev.

# To install the MySQL extensions.
# NOTE: The pdo_mysql extension is included in 4.8.12+ and 5.0.1+ images.
FROM phpswoole/swoole:4.7-php7.4-alpine

RUN docker-php-ext-install mysqli pdo_mysql

# To install the Redis extension.
# NOTE: The Redis extension is included in 4.8.12+ and 5.0.1+ images.
FROM phpswoole/swoole:4.7-php7.4-alpine

RUN set -ex \
    && pecl channel-update pecl.php.net \
    && yes no | pecl install redis-stable \
    && docker-php-ext-enable redis

# To install the Couchbase extension.
FROM phpswoole/swoole:4.8-php7.4-alpine

RUN set -ex \
    && apk update \
    && apk add --no-cache libcouchbase=2.10.6-r0 \
    && apk add --no-cache --virtual .build-deps $PHPIZE_DEPS libcouchbase-dev=2.10.6-r0 zlib-dev \
    && pecl update-channels \
    && pecl install couchbase-2.6.2 \
    && docker-php-ext-enable couchbase \
    && apk del .build-deps \
    && rm -rf /var/cache/apk/* /tmp/* /usr/share/man /usr/src/php.tar.xz*

Serializer and Compression Support in Extension Redis

Extension Redis is compiled with the msgpack serializer disabled. The igbinary serializer is enabled in nightly images and in versioned images since 6.3.0, which include extension igbinary for that purpose; in earlier versioned images it is disabled. The lzf and zstd compressions are enabled in nightly images and in versioned images since 6.1.10+ and 6.2.2+; in earlier versioned images no compression is available. You can check what a given image supports with:

# Tag "php8.4" is a nightly image.
docker run --rm phpswoole/swoole:php8.4 php --ri redis | grep Available

Available serializers => php, json, igbinary
Available compression => lzf, zstd

Serializers and compressions are opt-in at runtime: Redis::OPT_SERIALIZER defaults to Redis::SERIALIZER_NONE and Redis::OPT_COMPRESSION defaults to Redis::COMPRESSION_NONE, so none of them changes how your data is stored unless your application asks for it.

To use Redis::SERIALIZER_IGBINARY in images older than 6.3.0, or the msgpack serializer in any image, extension Redis has to be rebuilt against extension igbinary (or msgpack). Installing igbinary alone is not enough: helper scripts like install-php-extensions skip extensions that are already installed, so the bundled Redis extension is left untouched. Remove it first, then reinstall both:

FROM phpswoole/swoole:latest

COPY --from=mlocati/php-extension-installer /usr/bin/install-php-extensions /usr/local/bin/

RUN set -ex && \
    rm -f "$(php-config --ini-dir)/docker-php-ext-redis.ini" && \
    pecl uninstall redis && \
    install-php-extensions igbinary redis

Note that extension Redis built this way depends on extension igbinary: once rebuilt, it fails to load if igbinary is disabled afterwards.

DNS Resolution in Coroutines (c-ares)

In nightly images and in 6.3.0+ images, Swoole is built with option --enable-cares, so hostnames used in coroutines are resolved by c-ares on the event loop, instead of by blocking calls in Swoole's thread pool. Earlier images are not built with it. You can check whether a given image uses c-ares with:

docker run --rm phpswoole/swoole:php8.4 php --ri swoole | grep c-ares

This changes how hostnames are resolved in coroutines:

• Swoole\Coroutine\System::dnsLookup() checks /etc/hosts first, applies the search domains in /etc/resolv.conf, and uses all nameservers listed there. Without c-ares, it only queries the first nameserver and ignores both, so names like localhost, hosts added with docker run --add-host, or short Kubernetes service names can't be resolved.
• Option dns_server (e.g., Co::set(['dns_server' => '8.8.8.8'])) applies to every hostname resolved in coroutines, including those of coroutine clients, hooked cURL and hooked PDO/Redis connections. Without c-ares, it only affects Swoole\Coroutine\System::dnsLookup(). Entries in /etc/hosts are still checked first.
• Hostnames resolved in coroutines skip the C library's resolver, so /etc/nsswitch.conf is ignored: /etc/hosts is always checked first, then DNS.

Swoole\Coroutine\System::getaddrinfo(), and hostnames resolved outside of coroutines, are not affected.

Disable Installed/Enabled PHP Extensions

Since 4.8.12+ and 5.0.1+, PHP extensions pdo_mysql and Redis are installed and enabled by default. If you want to disable them, you can use the following commands in your Dockerfile.

FROM phpswoole/swoole:4.8-alpine

RUN set -ex && \
    rm -f "$(php-config --ini-dir)/docker-php-ext-pdo_mysql.ini" && \
    rm -f "$(php-config --ini-dir)/docker-php-ext-redis.ini"

Note that above commands will remove the corresponding configuration files for the extensions, but won't remove the extensions themselves.

WARNING: In nightly images and in 6.3.0+ images, extension Redis is built with the igbinary serializer and depends on extension igbinary. Do not remove docker-php-ext-igbinary.ini while keeping extension Redis enabled: extension Redis then fails to load.

More Examples

Following examples are for non-Alpine images only. We don't have examples included for the Alpine images.

You can use the image to serve an HTTP/WebSocket server, or run some one-off command with it. e.g.,

docker run --rm phpswoole/swoole php -m
docker run --rm phpswoole/swoole php --ri swoole
docker run --rm phpswoole/swoole composer --version

We have various examples included under folder "examples/" to help developers better use the image. These examples are numerically ordered. Each example has a docker-compose.yml file included, along with some other files. To run an example, please start Docker containers using the docker-compose.yml file included, then check HTTP output from URL http://127.0.0.1 unless otherwise noted. You may use the following commands to start/stop/restart Docker containers:

./bin/example.sh start   00 # To start container(s) of the first example.
./bin/example.sh stop    00 # To stop container(s) of the first example.
./bin/example.sh restart 00 # To restart container(s) of the first example.

To run another example, just replace the last command line parameter 00 with an example number (e.g., 05).

Here is a list of the examples under folder "examples/":

• Basic examples:
  • 00-autoreload: Restart the Swoole web server automatically if file changes detected under web root.
  • 01-basic: print out "Hello, World!" using Swoole as backend HTTP server.
  • 02-www: to use some customized PHP script(s) in the Docker image built.
  • 03-nginx: to use Swoole behind an Nginx server.
  • 04-entrypoint: to use a self-defined entrypoint script in the Docker image built.
  • 05-boot: to update content in the Docker container through a booting script.
  • 06-update-token: to show how to update server configurations with built-in script update-token.sh.
  • 07-disable-default-server: Please check the docker-compose.yml file included to see show how to disable the default web server created with Swoole.
• Manage PHP extensions and configurations:
  • 10-install-php-extension: how to install/enable PHP extensions.
  • 11-customize-extension-options: how to overwrite/customize PHP extension options.
  • 12-php.ini: how to overwrite/customize PHP options.
• Manage Supervisord programs:
  • 20-supervisord-services: to show how to run Supervisord program(s) in Docker.
  • 21-supervisord-tasks: to show how to run Supervisord program(s) when launching a one-off command with Docker. Please check the README file included to see how to run the example.
  • 22-supervisord-enable-program: to show how to enable program(s) in Supervisord program.
  • 23-supervisord-disable-program: to show how to disable Supervisord program(s).
  • 24-supervisord-gracefully-shutdown: how to gracefully stop Swoole servers (managed by supervisord) in Docker containers.
• Debugging:
  • 30-debug-with-gdb: Please check the README file included to see how to debug your PHP code with gdb.
  • 31-debug-with-valgrind: Please check the README file included to see how to debug your PHP code with Valgrind.
  • 32-debug-with-strace: Please check the README file included to see how to debug your PHP code with strace.
  • 33-debug-with-blackfire: Please check the README file included to see how to debug your PHP code with Blackfire.
  • 34-debug-with-xdebug: Please check the README file included to see how to debug your PHP code using Xdebug. Please note that Xdebug 3.1.0+ works with Swoole 5.0.2+ on PHP 8.1+ only. Lower versions of Xdebug don't work with Swoole.

Image Variants

The phpswoole/swoole images come in three flavors, each designed for a specific use case.

1. latest, <swoole-version>, and <swoole-version>-php<php-version>

• phpswoole/swoole:latest
• phpswoole/swoole:5.1
• phpswoole/swoole:5.1-php8.2
• phpswoole/swoole:5.1.8-php8.2

This variant is based on the php:cli images, with a few changes. It uses Supervisord to manage booting processes, and has Composer preinstalled.

Since Swoole 6.0.0, there is a Zend Thread Safety (ZTS) version of the image available, which is suffixed with -zts. e.g., phpswoole/swoole:6.0-php8.3-zts.

2. latest-dev, <swoole-version>-dev, and <swoole-version>-php<php-version>-dev

• phpswoole/swoole:latest-dev
• phpswoole/swoole:5.1-dev
• phpswoole/swoole:5.1-php8.2-dev
• phpswoole/swoole:5.1.8-php8.2-dev

This variant is very similar to the previous one, but it has extra tools added for testing, debugging, and monitoring purpose, including gdb, git, lsof, strace, tcpdump, Valgrind, and vim.

Since Swoole 6.0.0, there is a Zend Thread Safety (ZTS) version of the image available, which is suffixed with -zts-dev. e.g., phpswoole/swoole:6.0-php8.3-zts-dev.

3. latest-alpine, <swoole-version>-alpine, and <swoole-version>-php<php-version>-alpine

• phpswoole/swoole:latest-alpine
• phpswoole/swoole:5.1-alpine
• phpswoole/swoole:5.1-php8.2-alpine
• phpswoole/swoole:5.1.8-php8.2-alpine

You can use this variant in the same way as using the php:alpine image, except that we changed the default working directory to /var/www. Also, we have Composer preinstalled in the image.

Note: We don't have development tools built in for Alpine images. There is no Docker images like phpswoole/swoole:5.1.8-php8.2-alpine-dev.

Supported Tags and Respective Dockerfile Links

Versioned images (based on stable releases of Swoole)

Swoole 6.3

PHP Versions	Default Images	Dev Images	ZTS Images	Alpine Images
PHP 8.5	6.3.0-rc1-php8.5 6.3-php8.5	6.3.0-rc1-php8.5-dev 6.3-php8.5-dev	6.3.0-rc1-php8.5-zts 6.3-php8.5-zts	6.3.0-rc1-php8.5-alpine 6.3-php8.5-alpine
PHP 8.4	6.3.0-rc1-php8.4 6.3-php8.4 6.3	6.3.0-rc1-php8.4-dev 6.3-php8.4-dev 6.3-dev	6.3.0-rc1-php8.4-zts 6.3-php8.4-zts 6.3-zts	6.3.0-rc1-php8.4-alpine 6.3-php8.4-alpine 6.3-alpine
PHP 8.3	6.3.0-rc1-php8.3 6.3-php8.3	6.3.0-rc1-php8.3-dev 6.3-php8.3-dev	6.3.0-rc1-php8.3-zts 6.3-php8.3-zts	6.3.0-rc1-php8.3-alpine 6.3-php8.3-alpine
PHP 8.2	6.3.0-rc1-php8.2 6.3-php8.2	6.3.0-rc1-php8.2-dev 6.3-php8.2-dev	6.3.0-rc1-php8.2-zts 6.3-php8.2-zts	6.3.0-rc1-php8.2-alpine 6.3-php8.2-alpine

Swoole 6.2

PHP Versions	Default Images	Dev Images	ZTS Images	Alpine Images
PHP 8.5	6.2.5-php8.5 6.2-php8.5	6.2.5-php8.5-dev 6.2-php8.5-dev	6.2.5-php8.5-zts 6.2-php8.5-zts	6.2.5-php8.5-alpine 6.2-php8.5-alpine
PHP 8.4	6.2.5-php8.4 6.2-php8.4 6.2 latest	6.2.5-php8.4-dev 6.2-php8.4-dev 6.2-dev latest-dev	6.2.5-php8.4-zts 6.2-php8.4-zts 6.2-zts latest-zts	6.2.5-php8.4-alpine 6.2-php8.4-alpine 6.2-alpine latest-alpine
PHP 8.3	6.2.5-php8.3 6.2-php8.3	6.2.5-php8.3-dev 6.2-php8.3-dev	6.2.5-php8.3-zts 6.2-php8.3-zts	6.2.5-php8.3-alpine 6.2-php8.3-alpine
PHP 8.2	6.2.5-php8.2 6.2-php8.2	6.2.5-php8.2-dev 6.2-php8.2-dev	6.2.5-php8.2-zts 6.2-php8.2-zts	6.2.5-php8.2-alpine 6.2-php8.2-alpine

Swoole 6.1

PHP Versions	Default Images	Dev Images	ZTS Images	Alpine Images
PHP 8.4	6.1.12-php8.4 6.1-php8.4 6.1	6.1.12-php8.4-dev 6.1-php8.4-dev 6.1-dev	6.1.12-php8.4-zts 6.1-php8.4-zts 6.1-zts	6.1.12-php8.4-alpine 6.1-php8.4-alpine 6.1-alpine
PHP 8.3	6.1.12-php8.3 6.1-php8.3	6.1.12-php8.3-dev 6.1-php8.3-dev	6.1.12-php8.3-zts 6.1-php8.3-zts	6.1.12-php8.3-alpine 6.1-php8.3-alpine
PHP 8.2	6.1.12-php8.2 6.1-php8.2	6.1.12-php8.2-dev 6.1-php8.2-dev	6.1.12-php8.2-zts 6.1-php8.2-zts	6.1.12-php8.2-alpine 6.1-php8.2-alpine
PHP 8.1	6.1.12-php8.1 6.1-php8.1	6.1.12-php8.1-dev 6.1-php8.1-dev	6.1.12-php8.1-zts 6.1-php8.1-zts	6.1.12-php8.1-alpine 6.1-php8.1-alpine

Swoole 6.0

PHP Versions	Default Images	Dev Images	ZTS Images	Alpine Images
PHP 8.4	6.0.2-php8.4 6.0-php8.4 6.0	6.0.2-php8.4-dev 6.0-php8.4-dev 6.0-dev	6.0.2-php8.4-zts 6.0-php8.4-zts 6.0-zts	6.0.2-php8.4-alpine 6.0-php8.4-alpine 6.0-alpine
PHP 8.3	6.0.2-php8.3 6.0-php8.3	6.0.2-php8.3-dev 6.0-php8.3-dev	6.0.2-php8.3-zts 6.0-php8.3-zts	6.0.2-php8.3-alpine 6.0-php8.3-alpine
PHP 8.2	6.0.2-php8.2 6.0-php8.2	6.0.2-php8.2-dev 6.0-php8.2-dev	6.0.2-php8.2-zts 6.0-php8.2-zts	6.0.2-php8.2-alpine 6.0-php8.2-alpine
PHP 8.1	6.0.2-php8.1 6.0-php8.1	6.0.2-php8.1-dev 6.0-php8.1-dev	6.0.2-php8.1-zts 6.0-php8.1-zts	6.0.2-php8.1-alpine 6.0-php8.1-alpine

Swoole 5.1

PHP Versions	Default Images	Dev Images	Alpine Images
PHP 8.3	5.1.8-php8.3 5.1-php8.3 5.1	5.1.8-php8.3-dev 5.1-php8.3-dev 5.1-dev	5.1.8-php8.3-alpine 5.1-php8.3-alpine 5.1-alpine
PHP 8.2	5.1.8-php8.2 5.1-php8.2	5.1.8-php8.2-dev 5.1-php8.2-dev	5.1.8-php8.2-alpine 5.1-php8.2-alpine
PHP 8.1	5.1.8-php8.1 5.1-php8.1	5.1.8-php8.1-dev 5.1-php8.1-dev	5.1.8-php8.1-alpine 5.1-php8.1-alpine
PHP 8.0	5.1.8-php8.0 5.1-php8.0	5.1.8-php8.0-dev 5.1-php8.0-dev	5.1.8-php8.0-alpine 5.1-php8.0-alpine

Swoole 5.0

PHP Versions	Default Images	Dev Images	Alpine Images
PHP 8.2	5.0.3-php8.2 5.0-php8.2	5.0.3-php8.2-dev 5.0-php8.2-dev	5.0.3-php8.2-alpine 5.0-php8.2-alpine
PHP 8.1	5.0.3-php8.1 5.0-php8.1 5.0	5.0.3-php8.1-dev 5.0-php8.1-dev 5.0-dev	5.0.3-php8.1-alpine 5.0-php8.1-alpine 5.0-alpine
PHP 8.0	5.0.3-php8.0 5.0-php8.0	5.0.3-php8.0-dev 5.0-php8.0-dev	5.0.3-php8.0-alpine 5.0-php8.0-alpine

Swoole 4.8

PHP Versions	Default Images	Dev Images	Alpine Images
PHP 8.2	4.8.13-php8.2 4.8-php8.2	4.8.13-php8.2-dev 4.8-php8.2-dev	4.8.13-php8.2-alpine 4.8-php8.2-alpine
PHP 8.1	4.8.13-php8.1 4.8-php8.1	4.8.13-php8.1-dev 4.8-php8.1-dev	4.8.13-php8.1-alpine 4.8-php8.1-alpine
PHP 8.0	4.8.13-php8.0 4.8-php8.0 4.8	4.8.13-php8.0-dev 4.8-php8.0-dev 4.8-dev	4.8.13-php8.0-alpine 4.8-php8.0-alpine 4.8-alpine
PHP 7.4	4.8.13-php7.4 4.8-php7.4	4.8.13-php7.4-dev 4.8-php7.4-dev	4.8.13-php7.4-alpine 4.8-php7.4-alpine
PHP 7.3	4.8.13-php7.3 4.8-php7.3	4.8.13-php7.3-dev 4.8-php7.3-dev	4.8.13-php7.3-alpine 4.8-php7.3-alpine
PHP 7.2	4.8.13-php7.2 4.8-php7.2	4.8.13-php7.2-dev 4.8-php7.2-dev	4.8.13-php7.2-alpine 4.8-php7.2-alpine

Nightly images (built daily using the master branch of swoole-src)

PHP Versions	Default Images	Dev Images	ZTS Images	Alpine Images
PHP 8.5	php8.5	php8.5-dev	php8.5-zts	php8.5-alpine
PHP 8.4	php8.4	php8.4-dev	php8.4-zts	php8.4-alpine
PHP 8.3	php8.3	php8.3-dev	php8.3-zts	php8.3-alpine
PHP 8.2	php8.2	php8.2-dev	php8.2-zts	php8.2-alpine

Build Images Manually

The Docker images are built and pushed out automatically through Travis. If you want to build some image manually, please follow these three steps.

1. Install Composer packages. If you have command "composer" installed already, just run composer update -n.

2. Use commands like following to create dockerfiles:

./bin/generate-dockerfiles.php nightly # Generate dockerfiles to build images from the master branch of Swoole.
./bin/generate-dockerfiles.php 5.1.8   # Generate dockerfiles to build images for Swoole 5.1.8.

3. Build Docker images with commands like the following. The Dockerfiles need BuildKit (the default builder since Docker 23.0), for options ADD --checksum and RUN --mount.

docker build -t phpswoole/swoole:php8.2              -f dockerfiles/nightly/php8.2/cli/Dockerfile   .
docker build -t phpswoole/swoole:5.1.8-php8.2        -f dockerfiles/5.1.8/php8.2/cli/Dockerfile    .
docker build -t phpswoole/swoole:5.1.8-php8.2-alpine -f dockerfiles/5.1.8/php8.2/alpine/Dockerfile .

To build development images (where extra tools are included), add an argument DEV_MODE:

docker build --build-arg DEV_MODE=true -t phpswoole/swoole:php8.2-dev       -f dockerfiles/nightly/php8.2/cli/Dockerfile .
docker build --build-arg DEV_MODE=true -t phpswoole/swoole:5.1.8-php8.2-dev -f dockerfiles/5.1.8/php8.2/cli/Dockerfile  .

Credits

• Current implementation borrows ideas from Demin's work at Glu Mobile.
• Thanks to Blackfire for providing free open-source subscription for their awesome profiling tool.