CLI · Winter Console

The cfg command

cfg sets up and maintains a project’s configuration: the .env file, the WINTER_KEY secret, the Docker scaffolding and shell completion. It is the first thing that runs when a project is created, and the thing you come back to when setting an environment up.

Subcommands init · key · env · docker · completionFirst run cfg init

What cfg is and why

cfg is the project-configuration command.

The problem. A new project has to be brought into working shape: create the .env, generate a secret key and, if you want them, the Docker files and shell completion. Doing that by hand makes a forgotten step easy.

The solution. cfg gathers those operations into subcommands, and cfg init performs the basic setup in one go. That is what this page is about.

Subcommands

Subcommand Purpose
init Patches composer.json, creates .env, generates the key, drops in the stub meta
key Manages WINTER_KEY
env Manages the .env file
docker Generates the Docker files
completion Installs or prints the shell completion

cfg init

Brings the project into working shape (called automatically on composer create-project):

bash
php call cfg init

The sequence: patch composer.json (rewrite name and description, clear authors, remove keywords and scripts) → create .env → generate WINTER_KEY.

cfg key — the secret key

Flag Action
key -g Generate or regenerate the key (64 hex = 32 bytes) and write it into .env
key -s Show the current key
bash
php call cfg key -g   # a new WINTER_KEY

It needs a .env

key -g warns and stops when .env is missing — create it first (cfg env -i).

cfg env — the environment file

Flag Action
env -i Create .env from the template (skipped when it exists)
env -s Print the loaded $_ENV
env -s --file Print the raw contents of .env

cfg docker — the Docker scaffolding

bash
php call cfg docker

Creates a Dockerfile, a docker-compose.yml and a .dockerignore. The Dockerfile builds on the ready image flytachi/winter: Swoole, the database and Redis drivers, opcache, the winter user and the application’s start are in it already — the project adds only its vendor/ and code:

Dockerfile
# syntax=docker/dockerfile:1

FROM composer:2 AS vendor
WORKDIR /app
COPY composer.json composer.lock ./
RUN composer install --no-dev --no-interaction --optimize-autoloader --ignore-platform-reqs

FROM flytachi/winter:8.5
COPY --from=vendor --chown=winter:winter /app/vendor ./vendor
COPY --chown=winter:winter . .
ENTRYPOINT ["winter-entrypoint"]

The mode is picked with a variable at startup:

Startup Mode
docker compose up Production: opcache on, no watcher
DEV=true docker compose up Development: restart on file change, opcache off

Files already in the project are left alone and marked EXISTS — they are likely edited, and running the command again must not wipe that out. To overwrite — the -f flag:

bash
php call cfg docker -f

Inside the container the application starts as call application start and becomes PID 1: docker stop stops all its components cleanly.

Time to stop

A clean stop takes time: each component gets up to 30 seconds, the application waits for them up to 35 — details in Stopping. docker stop, though, waits only 10 seconds by default and then kills the whole container, so work in progress would be cut at second 10. That is why docker-compose.yml raises the limit with a margin:

docker-compose.yml
    stop_grace_period: 40s

The times nest: a component 30, the application 35, the container 40 seconds. In Kubernetes the same is set by terminationGracePeriodSeconds: 40 in the pod spec: its default of 30 cuts the application’s 35-second budget. If you raise a component’s $grace above 30, the application’s budget grows with it (the longest $grace plus 5 seconds), and the container’s limit has to grow the same way. With priorities the levels stop one after another and their times add up: HTTP on Low, processes on Normal and a database on High with grace: 60.0 make 30 + 30 + 60 + 5 = 125 seconds, and stop_grace_period must be at least that.

Ports

The application declares its port in code — #[EnableHttp(port:)], 8000 by default — and docker-compose.yml only publishes it:

docker-compose.yml
    ports:
    - "8000:8000"

The left number is the port on the machine, change it as you like. The right one has to match the port in the code. A WebSocket with a port of its own is published the same way, on a line of its own.

PHP extensions

The image has pdo_pgsql and pgsql, pdo_mysql, redis (phpredis), bcmath, pcntl and opcache. Anything else is installed in the project’s Dockerfile, as root, and the image then goes back to the winter user. The template carries it as a commented example:

Dockerfile
FROM flytachi/winter:8.5

USER root
RUN apk add --no-cache icu-libs \
  && apk add --no-cache --virtual .intl-deps $PHPIZE_DEPS icu-dev \
  && docker-php-ext-install -j"$(nproc)" intl \
  && apk del .intl-deps
USER winter
  • --virtual — the compiler and headers go in under one name and come out with one command, so they stay out of the image; only the library (icu-libs) remains.
  • $PHPIZE_DEPS — the extension build set from the PHP base image.
  • USER winter at the end — required: the application and any console in the container must not run as root.

The project’s files are copied with --chown=winter:winter: the application writes to .winter/ and logs/, and a RUN chown would not work here — the image does not run as root.

docker-compose.yml mounts the project into the container (volumes: ./:/app/) — that is for development. On a server the volumes line is usually removed, and the code and vendor/ come from the image. If you mount on a server too, on Linux the project folder must be writable by uid 1000 (chown -R 1000:1000 <project folder>); otherwise the application does not start and says which folder it cannot write.

cfg completion — shell completion

Flag Action
(no flag) Print the script to stdout
-i Install it
-if Install it, overwriting
bash
php call cfg completion -i

The shell is detected from $SHELL: zsh → ~/.zsh/completions/_call (an fpath line is added to ~/.zshrc), otherwise bash → ~/.bash_completion.d/call.

./call and call are completed; php call is not: the shell looks a completion up by the command’s name, and here the command is php.

Nothing to install in a container

The flytachi/winter image has bash and the completion already: docker exec -it <container> bash (/bin/bash in Portainer), and ./call <Tab> works at once. -i would not help there: the winter user has no home directory, and the installation would be gone when the container is recreated.

Next