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.
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):
php call cfg initThe 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 |
php call cfg key -g # a new WINTER_KEYIt 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
php call cfg dockerCreates 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:
# 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:
php call cfg docker -fInside 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:
stop_grace_period: 40sThe 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:
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:
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 winterat 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 |
php call cfg completion -iThe 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
- Installation — where
cfg initsits in the startup chain - Configuration —
.envand configuration classes - Console — overview — every command