Services · Package

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.

Package flytachi/winter-service-redisClass RedisVersion 8.8 (Alpine 3.24)

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

bash
composer require flytachi/winter-service-redis

It 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:

bootstrap.php
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:

bash
php call service docker

The Dockerfile gets apk add redis and the directories owned by winter. The command does not touch compose — it prints what to add:

docker-compose.yml
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.
bash
docker compose up -d --build

3. Start it. The log says:

text
[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:

php
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:

  1. No redis-server in the image → the start stops: “Add it to the image: call service docker”.
  2. 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 ps nor 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

php
$redis->socketPath();   // /run/redis/redis.sock

With phpredis

php
$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.

main/Configs/MainRedisConfig.php
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 ?? '';
  }
}
bootstrap.php
protected static function components(Components $components): void
{
  $components->service(MainRedisConfig::service());
}

A store points at it:

php
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

  1. 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.

text
[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 at INFO.
  • LOG_LEVEL applies to Redis too. Without LOG_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