Install Winter Boot

Set up your machine for Winter Boot development. Pick one path — you only need one:

• Option A — Docker (recommended). PHP, Swoole, the winter_boot native extension, and the commonly needed extensions come pre-installed in the Winter Boot base image. No PECL, no php.ini editing, no manual extension builds.
• Option B — Manual install. Install PHP yourself, require the packages with Composer, and build the extensions.

Option A — Docker (recommended)

The suvera/winter-boot image is built on php:8.5-cli-alpine and already contains swoole, winter_boot, redis, rdkafka, pcntl, curl, zip, and pdo_pgsql. It does not include Composer, so install your dependencies in a separate build stage using the official composer image:

Dockerfile

# Stage 1: install Composer dependencies
FROM composer:2 AS vendor
WORKDIR /app
COPY composer.json composer.lock ./
RUN composer install --no-dev --optimize-autoloader --ignore-platform-reqs

# Stage 2: runtime image
FROM suvera/winter-boot:latest
WORKDIR /app
COPY --from=vendor /app/vendor/ vendor/
COPY Application.php ./
COPY src/    src/
COPY config/ config/

EXPOSE 8080
CMD ["php", "Application.php"]

Build and run

docker build -t my-winter-service:latest .
docker run -p 8080:8080 my-winter-service:latest

Caution

Inside a container the server must listen on all interfaces. Set server.address: 0.0.0.0 in application.yml; with the default 127.0.0.1 the published port cannot be reached from your machine.

Tip

Prefer to keep editing locally while the runtime lives in Docker? Install dependencies once, then mount your project into the base image instead of building:

docker run --rm -v "$(pwd)":/app -w /app composer:2 composer install --ignore-platform-reqs
docker run --rm -it -v "$(pwd)":/app -w /app -p 8080:8080 suvera/winter-boot:latest php Application.php

Once the container is serving traffic, continue with the Quickstart — the code is the same inside or outside Docker. For a complete project layout (Phar build, datasource configuration, and more), see suvera/winter-example-service.

Option B — Manual install

1. Install PHP 8.5 or later

   Confirm your version, and make sure the PHP development tools (phpize, php-config) are installed — you need them to build the native extension:

   php -v
   phpize --version

2. Install the Composer packages

   Install the framework, plus only the libraries you use:

   Framework only

   composer require suvera/winter-boot

   Adding libraries (install winter-boot alongside each one)

   composer require suvera/winter-boot suvera/winter-modules
   composer require suvera/winter-boot suvera/winter-doctrine
   composer require suvera/winter-boot suvera/winter-eureka
   composer require suvera/winter-boot suvera/winter-memdb

   Package	What it gives you
   suvera/winter-boot	Framework core: DI, AOP, REST, PDBC, transactions, migrations, async, scheduling, actuator, telemetry — always install this
   suvera/winter-modules	Integration modules: Kafka, SQS, S3, OpenSearch, Redis, Memcache, DTCE
   suvera/winter-doctrine	Doctrine ORM and DBAL plus multi-tenant datasources
   suvera/winter-eureka	Service discovery via Consul or Netflix Eureka
   suvera/winter-memdb	Embedded in-memory servers (Redis, Ignite, Memcached, Hazelcast) managed by the app (experimental)

   Note

   The library packages do not declare suvera/winter-boot as a dependency, so always require it explicitly. Also note that suvera/winter-modules requires the redis, swoole, and pcntl extensions to be present for composer require to succeed, even if you only use one of its modules.

3. Install the required PHP extensions

   Two extensions are required. Everything else is optional — see the table below.

   • swoole — the built-in HTTP server (WinterWebSwooleApplication), #[Async], #[Scheduled], daemon threads, and several libraries.

     pecl install swoole

   • winter_boot — the framework’s native extension, required since Winter Boot 2.1.0; the application refuses to start without it. See Native Extension for what it provides.

     Build it from the php-ext/ directory that ships inside the Composer package you installed in the previous step:

     cd vendor/suvera/winter-boot/php-ext/
     phpize
     ./configure --enable-winter_boot
     make
     sudo make install

   Enable both extensions in your php.ini:

   php.ini

   extension=swoole.so
   extension=winter_boot.so

   Optional extensions — install only for the integrations you use. Extensions you never use only add build time and attack surface.

   You need	Extension	Install
   Redis module, DTCE with Redis backend	redis (phpredis)	pecl install redis
   Kafka module, DTCE with Kafka backend	rdkafka (needs the librdkafka-dev system library)	pecl install rdkafka
   Memcache module, Memdb Hazelcast client	memcached or memcache	pecl install memcached
   OpenTelemetry tracing	opentelemetry	pecl install opentelemetry
   A relational database	one of pdo_sqlite, pdo_mysql, pdo_pgsql, pdo_sqlsrv, pdo_oci	via your OS PHP packages
   Image processing (how-to guide)	imagick	pecl install imagick

   Note

   What each extension is needed for — and what happens when it is missing — is covered in Extension Limits.

4. Verify the setup

   php -v
   php --ri swoole
   php --ri winter_boot

   All three commands should succeed without errors before you move on.

What’s next?

QuickstartWrite your first service and REST controller and have a running HTTP server in minutes.