niceos/redis repository overview

⁠1. Introduction

How this image differs from the vanilla Docker Hub image and Bitnami.

• NiceOS libraries baked in. The image ships with the NiceOS runtime libraries (logging, filesystem, OS/user helpers, validations, networking). These small, focused utilities power safer entrypoints, graceful shutdowns, permission fixes, health probes, and configuration edits without re-implementing ad-hoc shell fragments in every script.

• Strict idempotency and verifiable configuration. Defaults are copied without overwriting user files; updates to redis.conf are done via explicit, line-level operations rather than blind rewrites. On each start, the same inputs lead to the same outputs—making behavior predictable in CI/CD and easy to audit during incident reviews.

• Enterprise-grade logging by default. Structured logging (plain and JSON), leveled output (ERROR/WARN/INFO/DEBUG/TRACE), rate-limiting of duplicate messages, optional color, and consistent module tags give you readable container logs locally and machine-parsable logs in production. This reduces noise and speeds up troubleshooting.

• Production-first posture (not just dev convenience). The image runs as a non-root user, honors secret files (*_FILE) to avoid leaking credentials, supports TLS/ACL configuration with validation, and keeps Redis in the foreground for clean PID 1 semantics and graceful termination. Quick-start commands are available, but the defaults and documentation assume real deployments, not only demos.

⁠2. Key Differentiators of NiceOS Redis

📦 Idempotent configuration management Default configs are copied into place without overwriting user-provided files. Every container start is predictable and audit-friendly.

🛠 Clear separation: Setup vs Run The setup script fine-tunes redis.conf Bitnami-style (safe defaults, security hardening). The run script always launches Redis in foreground mode with --daemonize no, ensuring clean PID 1 behavior in containers.

🧑‍💻 Runs as non-root by default Redis starts as UID:GID 10001:10001, with safe directory ownership checks and permission fixes. No privileged user required.

🔒 Secret management via *_FILE Passwords, certificates, and sensitive data are mounted as files—not plain env vars—so they never leak in docker inspect or ps.

🌐 Built-in TLS and ACL support with validations TLS is first-class: certs, keys, CA, DH params are validated before start. ACL files are supported out-of-the-box for fine-grained access control.

📝 Enterprise-grade logging Structured JSON and colorful human logs, deduplication of repeated messages, module tags, and consistent levels (ERROR/WARN/INFO/DEBUG/TRACE). Tail logs comfortably or parse them automatically.

🇷🇺 Russian localization available When LANG=ru_RU.UTF-8, all helper scripts switch to Russian messages and log output—helpful for operators in domestic environments.

⁠3. Quick Start (TL;DR) 🚀

The NiceOS Redis container comes with sane defaults, but you can start small or go production-ready in just a few lines.

⁠🔓 Easiest way (development only!)

docker run --rm -it \
  --name redis-dev \
  -e ALLOW_EMPTY_PASSWORD=yes \
  niceos/redis:8.2.1

👉 Runs Redis without a password. Use only for local testing.

⁠🔐 Recommended way (with password & persistent volume)

docker run -d \
  --name redis \
  -e REDIS_PASSWORD=supersecret \
  -v /my/redis-data:/app/data \
  niceos/redis:8.2.1

👉 Starts Redis with authentication enabled and data persisted in /my/redis-data.

⁠🩺 Healthcheck example

The image ships with a built-in HEALTHCHECK. You can verify it manually:

docker exec redis \
  /usr/bin/redis-cli -a supersecret ping

Expected response:

PONG

For TLS deployments, use:

docker exec redis \
  /usr/bin/redis-cli --tls --cert /path/redis.crt --key /path/redis.key --cacert /path/ca.crt ping

⁠4. Getting the Image 🐳

There are multiple ways to obtain the NiceOS Redis image, depending on your workflow.

⁠📥 Pull from registry

Always use a versioned tag for reproducibility:

docker pull niceos/redis:8.2.1

👉 This ensures you always get the same Redis version, not a moving latest.

⁠🛠 Use with Docker Compose

Define Redis as a service in your docker-compose.yml:

version: "3.9"

services:
  redis:
    image: niceos/redis:8.2.1
    container_name: redis
    restart: unless-stopped
    environment:
      - REDIS_PASSWORD=supersecret
    volumes:
      - ./redis-data:/app/data
    ports:
      - "6379:6379"

Then start everything with:

docker-compose up -d

Your app can now connect to Redis at localhost:6379 with the configured password.

⁠5. Secrets & Security 🔐

NiceOS Redis is designed with security as a first-class concern. While you can spin up a quick development container without a password, production deployments should always apply secure defaults.

⁠📄 File-based secrets (*_FILE support)

Every sensitive environment variable supports a *_FILE counterpart. Instead of:

-e REDIS_PASSWORD=supersecret

you can mount a Docker secret or Kubernetes Secret:

-e REDIS_PASSWORD_FILE=/run/secrets/redis_pass

👉 This prevents your password from leaking into docker inspect, logs, or process arguments.

⁠⚠️ ALLOW_EMPTY_PASSWORD is for development only

You can bypass password enforcement by setting:

-e ALLOW_EMPTY_PASSWORD=yes

This is acceptable in quick demos or local tests, but extremely unsafe in production. In production, always provide REDIS_PASSWORD or REDIS_PASSWORD_FILE.

⁠🗝 Access control: ACL & disabling commands

• ACL: You can provide an ACLFILE to define fine-grained users, commands, and key patterns:

  -e REDIS_ACLFILE=/app/mounted-etc/users.acl
  -v ./users.acl:/app/mounted-etc/users.acl
  

  Copy

• Disabled commands: By default, unsafe commands such as FLUSHALL, FLUSHDB, CONFIG, DEBUG, SHUTDOWN, and CLUSTER are disabled during setup unless you explicitly override REDIS_DISABLE_COMMANDS. This prevents accidents like flushing production databases.

⁠👤 Non-root execution and directory ownership

Redis runs as user app (UID 10001) by default.

• All runtime directories (/app/data, /app/logs, /app/run) are created if missing and ownership is fixed automatically.
• The container never requires root privileges at runtime, which lowers the attack surface.

⁠🔐 TLS for encrypted traffic

Redis traffic can be encrypted end-to-end. Enable TLS with:

-e REDIS_TLS_ENABLED=yes \
-e REDIS_TLS_CERT_FILE=/app/certs/redis.crt \
-e REDIS_TLS_KEY_FILE=/app/certs/redis.key \
-e REDIS_TLS_CA_FILE=/app/certs/ca.crt \
-v ./certs:/app/certs

• The container validates that certs, keys, and CA files exist before starting.
• You can configure client auth (REDIS_TLS_AUTH_CLIENTS=yes) for mutual TLS.

⁠🌐 Secure replication with master-auth

When running replicas, use REDIS_MASTER_PASSWORD to authenticate against the master:

# Master
docker run -d --name redis-master \
  -e REDIS_REPLICATION_MODE=master \
  -e REDIS_PASSWORD=masterpass \
  niceos/redis:8.2

# Replica
docker run -d --name redis-replica \
  -e REDIS_REPLICATION_MODE=replica \
  -e REDIS_MASTER_HOST=redis-master \
  -e REDIS_MASTER_PORT_NUMBER=6379 \
  -e REDIS_MASTER_PASSWORD=masterpass \
  -e REDIS_PASSWORD=replicapass \
  niceos/redis:8.2

👉 Replicas will refuse to start if REDIS_MASTER_PASSWORD is missing (unless ALLOW_EMPTY_PASSWORD=yes is set for development).

Summary: With file-backed secrets, strict defaults, disabled unsafe commands, enforced non-root execution, TLS validation, and authenticated replication, the NiceOS Redis image is built to be production-safe out of the box.

⁠6. Configuration ⚙️

The NiceOS Redis image offers multiple, predictable ways to configure Redis, from mounting your own redis.conf to using lightweight overrides. All approaches are idempotent: the same input always produces the same result.

⁠📂 Using your own redis.conf (mounted-etc)

If you mount a full redis.conf into the container at:

/app/mounted-etc/redis.conf

the setup logic will copy it into place and skip auto-tuning. Example:

-v ./redis.conf:/app/mounted-etc/redis.conf

👉 In this mode, the image treats your config as authoritative and does not generate or patch defaults.

⁠📝 Using overrides.conf

If you only want to override a few settings, mount a file at:

/app/mounted-etc/overrides.conf

The entrypoint ensures that this file is included at the end of the active redis.conf via an include directive. This lets you apply small adjustments (like changing memory limits or maxclients) without maintaining a full config file.

⁠💾 Persistence (AOF and RDB)

• AOF (Append Only File) is enabled by default (REDIS_AOF_ENABLED=yes). It fsyncs every second (appendfsync everysec) for a safe performance balance.

• RDB snapshots are disabled by default in the setup flow (save ""). You can re-enable them by:

  -e REDIS_RDB_POLICY="900#1 300#10"
  -e REDIS_RDB_POLICY_DISABLED=no
  

  Copy

  which produces lines like:

  save 900 1
  save 300 10
  

  Copy

⁠📦 Idempotent defaults copying

On startup, the entrypoint copies files from:

/app/etc.default/ → /app/etc/

using rsync --ignore-existing or cp -rnp.

• Existing files are never overwritten.
• If no redis.conf exists, one is seeded from /app/etc.default/redis.conf or, as a last resort, from /etc/redis.conf. This guarantees that a working config is always present, but your changes are preserved.

⁠🔧 Behavior of the setup script (setup-redis.sh)

The setup phase is optional and runs when explicitly requested (NICEOS_REDIS_RUN_SETUP=yes or legacy run path). It:

• Validates environment variables (passwords, TLS, ports).

• Creates and fixes ownership of data/log/tmp directories.

• Ensures redis.conf is readable and group-safe (if configured).

• Applies Bitnami-style tuning idempotently to the existing redis.conf:

  • disables unsafe commands (e.g., FLUSHALL),
  • configures AOF and persistence policy,
  • sets password and ACL,
  • enables TLS if requested,
  • applies replication and Sentinel settings.

What it does not do:

• It never blindly regenerates redis.conf from scratch.
• It does not overwrite a mounted user config.
• It does not enable insecure defaults automatically (only if you explicitly set them).

✅ Result: the configuration layer in NiceOS Redis is transparent, reproducible, and safe—whether you prefer to bring your own config, override a few lines, or rely on environment-driven tuning.

⁠7. Running & Management 🚦

The lifecycle of the container is split into clear phases:

⁠🛠 Entrypoint → Setup

• The container always starts with entrypoint.sh.

• The entrypoint decides whether to run the setup script:

  • Runs automatically if NICEOS_REDIS_RUN_SETUP=yes (default in this image).
  • Also runs for legacy paths (/run.sh, Bitnami compatibility).

• setup-redis.sh validates env vars, applies defaults, fixes permissions, and tunes redis.conf idempotently.

⁠🚀 Run script (run-redis.sh)

The actual Redis process is launched by run-redis.sh, which guarantees:

• Foreground execution: --daemonize no is always enforced for clean PID 1 behavior.
• Pidfile safety: generates a pidfile only if the directory is writable; otherwise, runs without.
• Logfile control: defaults to stdout (--logfile "") unless you override it.
• Extra args respected: appends REDIS_EXTRA_FLAGS and any user arguments.

⁠📦 Examples

Standalone (no persistence, dev mode):

docker run --rm -it \
  --name redis-dev \
  -e ALLOW_EMPTY_PASSWORD=yes \
  niceos/redis:8.2

With persistent data volume:

docker run -d \
  --name redis \
  -e REDIS_PASSWORD=supersecret \
  -v ./redis-data:/app/data \
  niceos/redis:8.2

With additional flags (REDIS_EXTRA_FLAGS):

docker run -d \
  --name redis \
  -e REDIS_PASSWORD=supersecret \
  -e REDIS_EXTRA_FLAGS="--maxmemory 256mb --maxmemory-policy allkeys-lru" \
  niceos/redis:8.2

👉 Flags are merged at the end, so they override defaults where supported.

⁠👤 Non-root execution

Redis is always launched as user UID:GID 10001:10001 (app:app).

• No root privileges are needed at runtime.
• Ownership of /app/data, /app/logs, and /app/run is adjusted during setup.
• If you mount volumes, ensure they are writable by UID 10001.

✅ With this design, you get predictable startup, secure defaults, and full control over Redis arguments without breaking container best practices.