bfren/redis repository overview

⁠Redis

Docker Hub⁠ - Quay.io⁠ - bfren ecosystem⁠

⁠Introduction

Redis⁠ server, configured with environment variables. It is built on Alpine + S6⁠, with Redis from Alpine's packages - each Redis version uses the newest Alpine release that has it.

It is meant to be used inside a private Docker network, by other containers - for example as the cache or metadata store for Send⁠. By default anyone who can reach port 6379 can use it, so don't publish the port unless you set a password.

⁠Quickstart

services:
  redis:
    image: quay.io/bfren/redis:redis8
    restart: unless-stopped
    volumes:
      - ./v/redis:/data

  app:
    image: your/app
    environment:
      - REDIS_HOST=redis

Run docker compose up -d - your app connects to redis:6379. To use the Redis CLI:

docker compose exec redis redis-cli

⁠Features

• 🟥 Redis 6, 7 and 8 - choose with the image tag
• ⚙️ Password, bind address, persistence, log level and client limit set with environment variables
• 💾 Data saved to /data with Redis's default snapshot schedule, and optional append-only file
• 🩺 Health check that pings the server, using the password if one is set
• 👤 Redis runs as redis (UID 1000), not root
• 🧪 Built-in tests

⁠Tags

Images are published to Docker Hub (bfren/redis) and Quay.io (quay.io/bfren/redis) for linux/amd64, linux/arm/v7 and linux/arm64.

Use Redis 8 for anything new - Redis 6 and 7 are kept for apps that need them.

⁠Configuration

⁠Ports

⁠Volumes

⁠Environment Variables

See Alpine + S6⁠ for BF_DEBUG, BF_TZ and the other base image variables.

⁠How It Works

On every start /etc/redis/redis.conf is generated from the environment variables, then redis-server runs under S6 as redis. The container stops if Redis crashes.

Redis saves a snapshot of the data to /data/dump.rdb using its default schedule: after an hour if at least 1 key changed, after 5 minutes if 100 changed, and after a minute if 10,000 changed. With BF_REDIS_APPEND_ONLY=yes every write is also logged, so at most about a second is lost (with everysec). Mount a volume at /data to keep the data when the container is replaced.

The health check (every 30 seconds) runs redis-cli ping against the first address in BF_REDIS_BIND, or the container's address if that is empty, and passes BF_REDIS_PASS if it is set.

⁠Host configuration

Redis warns at start-up if memory overcommit is turned off, as background saves (which fork the process) may then fail when memory is low. This is a kernel setting, so it can't be changed from inside the container - set it on the Docker host:

sudo sysctl vm.overcommit_memory=1
echo 'vm.overcommit_memory = 1' | sudo tee /etc/sysctl.d/99-overcommit.conf

⁠Testing

./test.nu                   # builds Redis 8 and runs /test
./test.nu 6                 # or any version directory
./test.nu --all             # every version, in parallel
./run.sh 8                  # builds and opens a shell
./generate-dockerfiles.sh   # regenerates the Dockerfiles from Dockerfile.esh

/test runs this image's tests alongside the base images' tests: the generated redis.conf (defaults, settings, bind address, password and snapshots), how the health check chooses its address and password, and the installed Redis version.

⁠Troubleshooting

⁠Clients get NOAUTH Authentication required

BF_REDIS_PASS is set - give the same password to your app.

⁠Clients can't connect

Check the app uses the Redis container's name and port 6379, on the same Docker network. If BF_REDIS_BIND is set, Redis only listens on those addresses.

⁠Data is lost when the container is replaced

Mount a volume at /data. Snapshots are only taken on Redis's schedule, so turn on BF_REDIS_APPEND_ONLY if losing the last few minutes matters.

⁠WARNING Memory overcommit must be enabled!

See Host configuration⁠.

⁠FAQs

⁠Should I publish port 6379?

Only if something outside Docker needs Redis, and then set BF_REDIS_PASS and publish it to 127.0.0.1 only (e.g. "127.0.0.1:6379:6379"). Redis is not designed to be exposed to the internet.

⁠Can I add my own Redis settings?

redis.conf is generated on every start, so changes to it are lost. Build your own image from this one and change /etc/bf/templates/redis.conf.esh.

⁠Licence

⁠Copyright