Redis
winter-service-redis is a ready-made Redis service. The application starts it before
everything else, waits until it answers, keeps checking it while it runs, restarts it after
a crash or a hang, and stops it last — saving its data first.
What it is and why
What it is. The Redis class, implementing Service:
it knows how to start Redis in the application’s container, how to tell it is ready, how
to stop it, and what it needs in the image.
The problem. A Redis of your own in a container means a configuration with a password that must stay off the command line, a socket instead of an open port, the choice between keeping data and being a cache, a memory limit, and a readiness check that holds the application back while Redis is still loading its data from disk.
The solution. All of it is in the package, tested against a real server. One line is left in the project.
The package runs the server. You connect to it as usual — through winter-redis or
phpredis, see Connecting.
Installation
composer require flytachi/winter-service-redisIt needs PHP 8.4+, flytachi/winter-kernel 4.5+ and the flytachi/winter image (Alpine):
the server itself comes from apk, and call service docker adds it to the image.
Quick start
1. Declare it:
use Flytachi\Winter\Service\Redis\Redis;
protected static function components(Components $components): void
{
$components->service(new Redis(maxmemory: '256mb'));
}2. Add it to the image:
php call service dockerThe Dockerfile gets apk add redis and the directories owned by winter. The command
does not touch compose — it prints what to add:
services:
server:
stop_grace_period: 70s
volumes:
- redis-data:/var/lib/redis
volumes:
redis-data:stop_grace_period— always needed: HTTP 30 s + Redis 30 s (to save its data) + 5 + 5.- The volume — if the data must outlive a recreated container. A cache
(
persist: false) needs neither the volume nor a data directory.
docker compose up -d --build3. Start it. The log says:
[2026-11-15 16:12:37] [INFO ] -sys- [1]: Application starting High: redis
[2026-11-15 16:12:37] [INFO ] -redis- [11]: Server initialized
[2026-11-15 16:12:37] [INFO ] -redis- [11]: Ready to accept connections unix
[2026-11-15 16:12:37] [INFO ] -sys- [1]: redis is up.Keeping data or a cache
persist: true (the default) |
persist: false |
|
|---|---|---|
| On disk | an RDB snapshot on Redis’s schedule and on a stop | nothing |
| After a restart | the data is there | empty |
| The volume | needed | not needed |
| For | sessions, queues, counters | a cache that may be lost |
aof: true adds a log of every write (appendonly yes): after a crash, not everything
since the last snapshot is lost, but next to nothing. It works with persist only.
Without maxmemory Redis has no limit
Without maxmemory Redis grows until the container’s memory runs out, and then the OOM
killer ends the whole application: Redis lives in its container, and the application is
PID 1. Set maxmemory below the container’s memory, leaving room for the application.
With the default policy (noeviction) a full Redis refuses writes (OOM command not allowed), and the application lives on. A cache that may lose keys takes an eviction
policy.
The usual pair for a cache:
new Redis(persist: false, maxmemory: '256mb', maxmemoryPolicy: 'allkeys-lru');Parameters
The server
| Parameter | Default | What it sets |
|---|---|---|
data |
/var/lib/redis |
The data directory, when it keeps data — keep it in a volume |
socket |
/run/redis |
The directory of the Unix socket (redis.sock) |
host |
null |
null — the socket only, nothing outside the container connects. 127.0.0.1 — TCP inside the container too. 0.0.0.0 — other containers as well. A host needs a password |
port |
6379 |
The TCP port |
password |
null |
Asked for on every connection — through the socket too (requirepass) |
persist |
true |
Whether data is kept on disk — see above |
aof |
false |
A log of every write as well. Only with persist |
maxmemory |
null |
How much memory it may use: 256mb, 1gb; null — no limit |
maxmemoryPolicy |
null |
What goes once the memory is full: allkeys-lru, volatile-ttl…; null — Redis’s own, noeviction (writes are refused) |
settings |
[] |
Further configuration, each passed as --key value: ['databases' => 4, 'timeout' => 300]; true/false become yes/no |
args |
[] |
Further redis-server arguments, as they are |
logs |
true |
Whether Redis’s log goes into the application’s — see Log |
The component
| Parameter | Default | What it sets |
|---|---|---|
name |
'redis' |
Its name in logs and app status; the volume in the compose hint is {name}-data |
priority |
Priority::High |
Starts before the rest, stops after them |
critical |
true |
When it cannot run, the application stops |
retries |
3 |
Restarts after a crash within 30 minutes |
grace |
30.0 |
Seconds to stop — to save its data — before SIGKILL |
startTimeout |
60 |
Seconds to become ready |
alive |
true |
true — a PING every 10 s, 5 s for an answer, 6 misses in a row mean it hangs. A Probe of your own. null or false — not checked |
Everything is checked when the object is made: a relative path, a port out of range, a
host without a password, aof without persist, a size or a policy Redis does not
know, a setting the service sets itself (requirepass, port, dir…), a value on two
lines — each is an InvalidArgumentException explaining what is wrong.
What a start does
Before the server, the package’s script runs, and then becomes the server itself
(exec), so the stop signal reaches Redis directly:
- No
redis-serverin the image → the start stops: “Add it to the image: call service docker”. - The configuration — the socket, the address and port or none, the password, the
persistence, the memory limit — goes to the server’s standard input, not its command
line. The password is seen neither in
psnor on disk.
Readiness. Redis is ready once a PING through the socket is answered — but not with
LOADING: while Redis loads its data from disk, the application waits for it. With a
password, a PING without it is answered NOAUTH, loaded or not — then Redis counts as
ready as soon as it answers.
Without a password Redis says at its start that it accepts any local client. Through the socket, inside the container, that is so.
Connecting
$redis->socketPath(); // /run/redis/redis.sockWith phpredis
$client = new \Redis();
$client->connect($redis->socketPath());
if ($redis->password !== null) {
$client->auth($redis->password);
}With winter-redis
The natural place is the Redis configuration class: one and the same class runs the server and connects to it.
namespace Main\Configs;
use Flytachi\Winter\Redis\Config\RedisConfig;
use Flytachi\Winter\Redis\Pool\RedisPoolConfigInterface;
use Flytachi\Winter\Redis\Pool\RedisPoolTrait;
use Flytachi\Winter\Service\Redis\Redis;
class MainRedisConfig extends RedisConfig implements RedisPoolConfigInterface
{
use RedisPoolTrait;
public int $poolMaxConnections = 10;
/** What the application runs. */
public static function service(): Redis
{
return new Redis(maxmemory: '256mb');
}
/** How winter-redis connects to it. */
public function setUp(): void
{
$redis = self::service();
$this->host = $redis->socketPath(); // a socket path is a host for phpredis…
$this->port = 0; // …when the port is not one
$this->password = $redis->password ?? '';
}
}protected static function components(Components $components): void
{
$components->service(MainRedisConfig::service());
}A store points at it:
class VisitStore extends RedisStore
{
protected string $redisConfigClassName = MainRedisConfig::class;
protected string $prefix = 'visits:';
}
$count = new VisitStore()->increment('total');port = 0 is required: phpredis takes a path for a socket only when the port is less than
- With winter-redis’s default port, 6379, it looks the path up as a host name and fails
with
DNS Lookup resolve failed.
Over TCP (host set), setUp() takes 127.0.0.1 — or the container’s name — for the
host, and port from the service.
Log
Redis’s log goes into the application’s: in the same format, under the -redis- channel
(blue in colour), with the PID of the process that wrote the line in the brackets — the
server’s, or a child’s saving a snapshot.
[2026-11-15 16:13:05] [INFO ] -redis- [11]: Saving the final RDB snapshot before exiting.
[2026-11-15 16:13:05] [INFO ] -redis- [11]: DB saved on disk| Redis | Log |
|---|---|
. debug, - verbose |
DEBUG |
* notice |
INFO |
# warning |
WARN |
- Redis’s last words —
Redis is now ready to exit, bye bye...— it writes at warning. That is a stop that went well, so they go to the log atINFO. LOG_LEVELapplies to Redis too. WithoutLOG_LEVEL(the log off) its lines are not seen either. Want Redis’s output untouched?logs: false.
Stopping
SIGTERM: Redis saves its snapshot (with persist), syncs its log (with aof) and exits
0. It stops last, after HTTP, so the container needs stop_grace_period: 70s: 30
seconds for HTTP, 30 for Redis and 5 each of margin.
A large dataset takes longer to save: raise grace, and stop_grace_period with it.
Otherwise SIGKILL comes mid-save, and after the start the data is the previous
snapshot’s.
Next
- Services — what they are and how they work.
- PostgreSQL and MariaDB — the other ready-made services.
- Redis configuration —
RedisConfigand the connection pool.