lzocateli/redis repository overview

⁠Valkey

Imagem de Valkey 9.1.1 compatível com clientes RESP2 e RESP3, com persistência AOF e RDB. Ela preserva o nome público lzocateli/redis, mas não garante compatibilidade dos arquivos persistidos por Redis Community Edition 7.4 ou posterior.

⁠Referência da imagem

⁠Conteúdo e finalidade

⁠Incluído

• Valkey 9.1.1.
• Persistência AOF com appendfsync everysec e snapshots RDB em 900/1, 300/10 e 60/10000 segundos/alterações.
• ACL padrão para desenvolvimento e health check com permissão exclusiva para PING.
• Logs no stdout e health check executado a cada 30 segundos.

⁠Não incluído

• TLS, Sentinel, cluster ou proxy de rede.
• ACL de produção ou secrets de aplicações.
• Ajustes de kernel do host.
• Limite maxmemory e política de remoção de chaves.

⁠Início rápido

Execute os exemplos desta seção a partir da pasta redis/. Crie o diretório persistente antes de iniciar o contêiner:

mkdir -p data/valkey
sudo chown 999:999 data/valkey
docker run --name valkey \
  --detach \
  --publish 127.0.0.1:6379:6379 \
  --mount type=bind,src="$(pwd)/data/valkey",dst=/data \
  lzocateli/redis:9.1.1
docker exec valkey valkey-cli ping

Com Podman:

mkdir -p data/valkey
podman unshare chown 999:999 data/valkey
podman run --name valkey \
  --detach \
  --publish 127.0.0.1:6379:6379 \
  --volume "$(pwd)/data/valkey:/data:Z" \
  lzocateli/redis:9.1.1
podman exec valkey valkey-cli ping

O usuário default da ACL incluída não exige senha e aceita todos os comandos, chaves e canais. O modo protegido fica desativado para permitir clientes em outros contêineres; nunca publique a porta em uma interface externa sem substituir a ACL.

⁠Docker Compose

O arquivo compose.yaml inicia Valkey e P3X Redis UI em uma rede dedicada. Ele não publica a porta 6379 no host e publica a GUI somente em 127.0.0.1:7843.

mkdir -p data/valkey settings/redis-gui
sudo chown 999:999 data/valkey
sudo chown 10001:0 settings/redis-gui
docker compose up -d

Na GUI, conecte ao host valkey, porta 6379, sem TLS. Para Podman, use podman compose up -d com um provedor Compose instalado.

⁠Configuração

⁠Variáveis de ambiente

A imagem não adiciona variáveis de ambiente de configuração. O servidor lê /usr/local/etc/valkey/valkey.conf.

As configurações relevantes são bind * -::*, protected-mode no, AOF e RDB habilitados e a ACL externa em /usr/local/etc/valkey/users.acl. Como protected-mode está desativado, segurança de rede e autenticação são obrigatórias fora do ambiente de desenvolvimento.

⁠Parâmetros de valkey.conf

As três diretivas save são alternativas avaliadas continuamente; basta uma condição ser atendida para iniciar um snapshot. Quando AOF e RDB existem no reinício, Valkey carrega o AOF por representar o estado mais completo.

⁠Portas

⁠Persistência e mounts

Em Linux, o bind mount de /data deve permitir escrita pelo UID/GID 999:999. A configuração e a ACL embarcadas pertencem a root e são somente leitura. Não monte /tmp nem arquivo de log; logs vão para stdout e parâmetros de kernel são configurados no host.

⁠ACL e secrets

⁠Diferença entre os arquivos ACL

O repositório contém apenas users.acl. users.acl.local é criado pelo exemplo abaixo quando necessário e é ignorado por *.acl.local no .gitignore e no .dockerignore. Se esse arquivo aparecer na pasta local, ele foi gerado para configuração ou validação e não deve ser commitado.

O users.acl distribuído contém:

user default on nopass ~* &* +@all
user healthcheck on nopass -@all +ping

Assim, default é irrestrito e inseguro para produção. healthcheck não acessa chaves ou canais e só pode executar PING.

Para produção, gere um segredo e grave somente o hash SHA-256 em um arquivo local ignorado pelo Git:

VALKEY_PASSWORD="$(docker exec valkey valkey-cli ACL GENPASS)"
VALKEY_PASSWORD_HASH="$(printf '%s' "$VALKEY_PASSWORD" | sha256sum | cut -d ' ' -f 1)"
cat > users.acl.local <<EOF
user default off
user healthcheck on nopass -@all +ping
user app on #${VALKEY_PASSWORD_HASH} ~* &* +@all
EOF

No users.acl.local do exemplo, default off bloqueia novas conexões pelo usuário padrão; healthcheck é preservado para a prova de saúde; e app exige a senha correspondente ao hash. As regras ~*, &* e +@all ainda concedem acesso total ao usuário app.

O exemplo concede acesso total ao usuário app apenas para demonstrar a sintaxe. Em produção, substitua ~*, &* e +@all pelos padrões de chave, canais e categorias estritamente necessários.

Recrie o contêiner montando users.acl.local como somente leitura:

docker rm --force valkey

docker run --name valkey \
  --detach \
  --publish 127.0.0.1:6379:6379 \
  --mount type=bind,src="$(pwd)/data/valkey",dst=/data \
  --mount type=bind,src="$(pwd)/users.acl.local",dst=/usr/local/etc/valkey/users.acl,readonly \
  lzocateli/redis:9.1.1

Configure o cliente com usuário app e o valor de VALKEY_PASSWORD. Armazene o segredo em um secret manager; não o grave em Compose, Dockerfile, imagem, log ou repositório. Preserve o usuário healthcheck para manter a prova de saúde.

O usuário healthcheck usa nopass, portanto o argumento --pass healthcheck não representa um secret: qualquer senha seria aceita para esse usuário. Sua proteção está na permissão exclusiva para PING.

ACL não cifra a conexão. Use TLS ou uma rede privada quando houver risco de interceptação.

⁠Inicialização e ciclo de vida

O contêiner inicia diretamente como UID/GID 999:999. O entrypoint upstream não consegue corrigir bind mounts pertencentes a outro usuário, portanto /data deve estar gravável antes da inicialização. SIGTERM aciona o encerramento normal. O health check começa após 10 segundos, roda a cada 30 segundos, espera até 5 segundos e falha após três tentativas.

⁠Segurança

• Nunca exponha 6379 diretamente à internet.
• Substitua a ACL de desenvolvimento em produção e conceda somente comandos e padrões de chave necessários.
• Mantenha /data e a ACL fora do Git e do contexto de build.
• Restrinja acesso aos bind mounts no host.
• Não adicione --privileged; ajuste vm.overcommit_memory no host quando a carga exigir.
• Defina maxmemory e uma política de remoção coerentes com a carga e o limite do contêiner.
• Avalie Transparent Huge Pages e memória adicional para forks de RDB e reescritas AOF no host.

⁠Build local

Execute o build a partir da raiz do repositório:

docker build --pull --tag lzocateli/redis:9.1.1 redis

⁠Tags e compatibilidade

Esta versão substitui Redis 7.4 por Valkey 9.1.1. Valkey mantém compatibilidade de protocolo e de arquivos com Redis OSS 7.2 e versões anteriores. Entretanto, arquivos RDB e AOF produzidos por Redis Community Edition 7.4 ou posterior não são compatíveis com Valkey.

Não aponte esta imagem para o diretório /data usado pelo Redis 7.4. Migre por exportação lógica ou ferramenta compatível, valide a quantidade e o conteúdo das chaves e mantenha o backup original até concluir a verificação. A troca também altera implementação, licença, executáveis, caminho de configuração, usuário efetivo, ACL e health check.

⁠Validação

Antes da publicação, confirme BuildKit, build linux/amd64, PING, leitura e escrita, health check, UID do PID principal, persistência após recriação, encerramento normal, labels OCI, scan de vulnerabilidades, SBOM e proveniência.

⁠Publicação

Use Actions > Publicar imagem de container > Run workflow com:

• context_path: redis;
• image_name: redis;
• image_tag: 9.1.1;
• dockerfile: Dockerfile;
• platforms: linux/amd64.

⁠Operação

Esta imagem usa AOF e RDB simultaneamente; em reinícios, o AOF é preferido por conter o estado mais completo. Não copie arbitrariamente o AOF durante uma reescrita. Antes do backup, confirme em INFO persistence que aof_rewrite_in_progress é 0 e siga o procedimento oficial para preservar todos os arquivos do AOF multiparte. Mantenha também snapshots RDB e a ACL fora do host principal.

Teste a restauração em outro diretório antes de considerar o backup válido. Para atualizar, use uma nova tag imutável. Para rollback, restaure somente dados compatíveis com a versão anterior. Consulte logs com docker logs valkey.

⁠Troubleshooting

⁠Limitações conhecidas

• Somente linux/amd64 está declarado e validado neste repositório.
• A ACL incluída é insegura para produção.
• protected-mode está desativado para permitir clientes em outros contêineres.
• A imagem não fornece TLS nem alta disponibilidade.
• Não há limite de memória predefinido.

⁠Licenças e fontes

O badge MIT descreve somente o conteúdo original deste repositório. Componentes de terceiros permanecem sujeitos aos termos e avisos upstream. Consulte a política de licenciamento⁠.

⁠Referências

• Releases e suporte: https://valkey.io/topics/releases/
• ACL: https://valkey.io/topics/acl/
• Persistência: https://valkey.io/topics/persistence/
• Migração do Redis: https://valkey.io/topics/migration/
• Administração: https://valkey.io/topics/admin/

⁠Histórico de alterações

• 9.1.1: substitui Redis 7.4 por Valkey 9.1.1, adiciona ACL externa, AOF e RDB, health check restrito e integração opcional com P3X Redis UI.