N.KOJIRA.IO
Timeline
OK3E
[email protected] · npub1jxl2tnvnv9gycsy64aze295c3a529lx5sfmzlktf5lxuw805g5wqew0z0n

Podman na prática: PostgreSQL e Redis para o Nostr Relay Server

  • PostgreSQL — armazenamento obrigatório (eventos, perfis, NIP-29, Blossom, jobs).
  • Redis — cache e fila de jobs (opcional, mas recomendado em produção).

Tudo com Podman (rootless), incluindo os equivalentes em podman run, rede nomeada, pod, Compose, Quadlet/systemd e as configurações exatas que o projeto espera em conf.yaml.

Referências usadas como base: docker-compose.yml, deploy/postgres/postgresql.conf, deploy/redis/redis.conf, deploy/conf.yaml, docs/data-schema.md e README.md.


Sumário

  1. Visão geral
  2. Pré-requisitos
  3. Estrutura local, segredos e volumes
  4. Subir o PostgreSQL
  5. Subir o Redis
  6. Rede, pod e comunicação entre containers
  7. Atalho com Podman Compose
  8. Configurar o relay (conf.yaml)
  9. Migrations e primeira subida
  10. Operação do dia a dia
  11. Backup e restauração
  12. Persistência, rootless e SELinux
  13. Autostart com Quadlet/systemd
  14. Checklist de segurança
  15. Troubleshooting

1. Visão geral

Arquitetura mínima em desenvolvimento:

┌──────────────────────┐        ┌───────────────────────────┐
│  nrserver (host ou   │  TCP   │  Podman (rootless)        │
│  container)          │───────▶│  ┌─────────────┐          │
│  porta 9090 (relay)  │        │  │ PostgreSQL  │ :5432    │
│  porta 9091 (admin)  │───────▶│  └─────────────┘          │
│                      │        │  ┌─────────────┐          │
└──────────────────────┘        │  │ Redis       │ :6379    │
                                │  └─────────────┘          │
                                └───────────────────────────┘

Portas e nomes usados neste guia (os mesmos do docker-compose.yml):

Serviço Container Porta publicada Volume
PostgreSQL nrserver-postgres 127.0.0.1:5432:5432 nrserver-pg-data
Redis nrserver-redis 127.0.0.1:6379:6379 nrserver-redis-data
Relay nrserver 9090 e 9091 conf.yaml montado

Publicar em 127.0.0.1 (e não em 0.0.0.0) é intencional: banco e cache não devem ficar expostos na rede local/servidor sem firewall.


2. Pré-requisitos

2.1 Instalar o Podman

# Fedora / RHEL / CentOS Stream
sudo dnf install -y podman

# Debian / Ubuntu
sudo apt update && sudo apt install -y podman

# Arch
sudo pacman -S --needed podman

Opcional, para compatibilidade com comandos docker ...:

sudo dnf install -y podman-docker    # ou: apt install podman-docker

O podman-docker cria um wrapper docker; o daemon continua sem existir. Prefira escrever podman para não confundir o restante da equipe.

2.2 Verificações

podman --version
podman info --format '{{.Host.Security.Rootless}}'   # true = rootless
podman run --rm docker.io/library/alpine:3.23 echo ok

Para Compose (necessário apenas na seção 7):

podman compose version     # usa podman-compose ou docker-compose como provider
# alternativa explícita:
pipx install podman-compose

2.3 Imagens usadas pelo projeto

podman pull docker.io/library/postgres:18.4-alpine3.23
podman pull docker.io/library/redis:8.8.0-alpine3.23

As tags acima são as do docker-compose.yml. Se preferir fixar por digest:

podman pull docker.io/library/postgres:18.4-alpine3.23
podman image inspect docker.io/library/postgres:18.4-alpine3.23 \
  --format '{{.Digest}}'

3. Estrutura local, segredos e volumes

Crie um diretório local (fora do Git) para senhas e arquivos gerados:

mkdir -p .local/podman
printf '.local/\n' >> .gitignore   # garante que não vai para o repositório

Gere a senha do PostgreSQL em hexadecimal para evitar caracteres que precisam de URL-encoding dentro de postgres://...:

openssl rand -hex 24 > .local/podman/pg-password.txt
chmod 600 .local/podman/pg-password.txt

Crie os volumes nomeados e a rede:

podman volume create nrserver-pg-data
podman volume create nrserver-redis-data
podman network create nrserver-net

Inspecione o que foi criado:

podman volume ls
podman network inspect nrserver-net --format '{{range .Subnets}}{{.Subnet}}{{end}}'

Por que volume nomeado e não bind mount? O Podman gerencia permissões, labels SELinux e o ciclo de vida; além disso, em rootless o volume fica em ~/.local/share/containers/storage/volumes/..., sem depender do diretório do projeto.


4. Subir o PostgreSQL

4.1 Configuração do projeto

O arquivo deploy/postgres/postgresql.conf já vem com um ajuste razoável para relay (mais memória de cache e WAL do que o default):

listen_addresses = '*'
max_connections = 100
shared_buffers = 256MB
effective_cache_size = 768MB
maintenance_work_mem = 64MB
checkpoint_completion_target = 0.9
wal_buffers = 16MB
default_statistics_target = 100
random_page_cost = 1.1
effective_io_concurrency = 200
work_mem = 4MB
huge_pages = off
min_wal_size = 1GB
max_wal_size = 4GB

Como o relay abre até db.max_conns conexões (50 no exemplo do projeto), deixe max_connections sempre acima desse valor, com margem para manutenção (psql, pg_dump, migrations):

max_connections >= db.max_conns + 10

4.2 Comando podman run

podman run -d \
  --name nrserver-postgres \
  --network nrserver-net \
  --restart=unless-stopped \
  -p 127.0.0.1:5432:5432 \
  -e POSTGRES_DB=nostr \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password \
  -e POSTGRES_INITDB_ARGS="--data-checksums" \
  -v nrserver-pg-data:/var/lib/postgresql \
  -v "$PWD/deploy/postgres/postgresql.conf:/etc/postgresql/postgresql.conf:ro,Z" \
  -v "$PWD/.local/podman/pg-password.txt:/run/secrets/postgres_password:ro,Z" \
  --health-cmd "pg_isready -U postgres -d nostr" \
  --health-interval 10s \
  --health-timeout 5s \
  --health-retries 10 \
  --health-start-period 10s \
  docker.io/library/postgres:18.4-alpine3.23 \
  postgres -c config_file=/etc/postgresql/postgresql.conf

O que cada parte faz:

Item Efeito
POSTGRES_DB=nostr Cria o banco nostr no primeiro initdb.
POSTGRES_USER=postgres Define o superusuário.
POSTGRES_PASSWORD_FILE Lê a senha do arquivo montado, evitando senha em podman inspect.
POSTGRES_INITDB_ARGS="--data-checksums" Habilita checksums de página (detecta corrupção).
-v ...:/var/lib/postgresql PostgreSQL 18+: o PGDATA é .../18/docker; monte o pai. Em imagens ≤ 17 use /var/lib/postgresql/data.
config_file=... Faz o servidor usar o postgresql.conf montado.
:ro,Z Somente leitura + relabel SELinux do arquivo.
--health-cmd Healthcheck real (pg_isready), usado por Compose e por podman healthcheck run.

Atenção (PostgreSQL 18): montar o volume em /var/lib/postgresql/data na imagem 18 faz o initdb falhar com diretório não vazio ou dados em local inesperado. Use /var/lib/postgresql.

4.3 Primeiro start e validação

podman logs -f nrserver-postgres
# em outro terminal:
podman healthcheck run nrserver-postgres
podman exec -it nrserver-postgres pg_isready -U postgres -d nostr

Teste autenticação com senha (lendo do arquivo, sem imprimir no histórico):

PGPASSWORD="$(cat .local/podman/pg-password.txt)" \
  podman exec -i -e PGPASSWORD nrserver-postgres \
  psql -U postgres -h 127.0.0.1 -d nostr -c 'select version();'

Confira os parâmetros efetivos:

podman exec -it nrserver-postgres \
  psql -U postgres -d nostr -c 'show shared_buffers; show max_connections;'

4.4 Scripts de inicialização (opcional)

Arquivos .sql, .sh ou .sql.gz montados em /docker-entrypoint-initdb.d rodam apenas quando o volume está vazio:

mkdir -p .local/podman/initdb
cat > .local/podman/initdb/001-extensions.sql <<'SQL'
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
SQL

E adicione ao podman run:

-v "$PWD/.local/podman/initdb:/docker-entrypoint-initdb.d:ro,Z"

O schema do relay não é criado por aqui: ele é versionado em infra/db/migrations e aplicado com nrserver migrate up (seção 9).

4.5 Alterar senha depois de criado o volume

As variáveis POSTGRES_* só valem no primeiro initdb. Para trocar a senha:

NEW_PASS="$(openssl rand -hex 24)"
printf '%s' "$NEW_PASS" > .local/podman/pg-password.txt

podman exec -it nrserver-postgres \
  psql -U postgres -d nostr \
  -c "ALTER USER postgres WITH PASSWORD '$NEW_PASS';"

Depois atualize db.postgres_uri em conf.yaml e reinicie o relay.


5. Subir o Redis

5.1 Configuração do projeto

deploy/redis/redis.conf:

bind 0.0.0.0
port 6379
protected-mode no
appendonly yes
save 900 1
save 300 10
save 60 10000
dir /data
loglevel warning

Pontos importantes:

  • bind 0.0.0.0 dentro do container é necessário para o port mapping e para outros containers da rede. A exposição externa é controlada pelo -p 127.0.0.1:6379:6379.
  • protected-mode no só é aceitável porque o acesso está limitado ao loopback ou à rede interna do Podman. Nunca publique 6379 em 0.0.0.0 sem requirepass/ACL e firewall.
  • appendonly yes grava o AOF em /data (volume), reduzindo perda de dados.
  • Os três save mantêm snapshots RDB complementares.

Versão endurecida com senha e limites de memória:

bind 0.0.0.0
port 6379
protected-mode no
appendonly yes
appendfsync everysec
dir /data
loglevel warning

# autenticação (Redis 6+ ACL)
requirepass TROQUE_ESTA_SENHA

# cache + fila de jobs convivem no mesmo Redis:
# não use allkeys-lru, pois isso pode descartar streams da fila
maxmemory 512mb
maxmemory-policy volatile-lru

# desconecta clientes ociosos
timeout 300
tcp-keepalive 60

Por que volatile-lru e não allkeys-lru? O relay também usa Redis como fila (queue.enabled), baseada em Streams. allkeys-lru pode despejar mensagens da fila. volatile-lru só descarta chaves com TTL — que são justamente as chaves de cache.

5.2 Comando podman run (sem senha)

podman run -d \
  --name nrserver-redis \
  --network nrserver-net \
  --restart=unless-stopped \
  -p 127.0.0.1:6379:6379 \
  -v nrserver-redis-data:/data \
  -v "$PWD/deploy/redis/redis.conf:/usr/local/etc/redis/redis.conf:ro,Z" \
  --health-cmd "redis-cli ping" \
  --health-interval 10s \
  --health-timeout 3s \
  --health-retries 5 \
  docker.io/library/redis:8.8.0-alpine3.23 \
  redis-server /usr/local/etc/redis/redis.conf

5.3 Comando podman run (com senha via variável de ambiente)

Crie a senha:

openssl rand -hex 24 > .local/podman/redis-password.txt
chmod 600 .local/podman/redis-password.txt

Suba com requirepass injetado pelo shell do container (a senha não aparece nos argumentos do processo redis-server, apenas no ambiente do container):

podman run -d \
  --name nrserver-redis \
  --network nrserver-net \
  --restart=unless-stopped \
  -p 127.0.0.1:6379:6379 \
  -e REDIS_PASSWORD="$(cat .local/podman/redis-password.txt)" \
  -v nrserver-redis-data:/data \
  -v "$PWD/deploy/redis/redis.conf:/usr/local/etc/redis/redis.conf:ro,Z" \
  --health-cmd 'redis-cli --no-auth-warning -a "$REDIS_PASSWORD" ping' \
  --health-interval 10s \
  --health-timeout 3s \
  --health-retries 5 \
  docker.io/library/redis:8.8.0-alpine3.23 \
  sh -c 'exec redis-server /usr/local/etc/redis/redis.conf --requirepass "$REDIS_PASSWORD"'

E em conf.yaml:

redis:
  enabled: true
  addr: "127.0.0.1:6379"
  password: "a-mesma-senha"
  db: 0

A variável ainda aparece em podman inspect para quem tem acesso ao usuário que roda o container. Para não deixá-la no histórico do shell, use --env-file .local/podman/redis.env (permissão 600) no lugar de -e. A imagem oficial do Redis não suporta *_FILE, então podman secret só funciona com um entrypoint wrapper que leia o arquivo e exporte a variável.

5.4 Validação

podman logs -f nrserver-redis
podman healthcheck run nrserver-redis

# sem senha
podman exec -it nrserver-redis redis-cli ping

# com senha
podman exec -it nrserver-redis \
  redis-cli --no-auth-warning -a "$(cat .local/podman/redis-password.txt)" ping

Comandos úteis de diagnóstico:

podman exec -it nrserver-redis redis-cli INFO server | head -20
podman exec -it nrserver-redis redis-cli INFO memory
podman exec -it nrserver-redis redis-cli CONFIG GET maxmemory maxmemory-policy appendonly
podman exec -it nrserver-redis redis-cli --scan --pattern 'event:*' | head
podman exec -it nrserver-redis redis-cli TTL 'event:ALGUM_ID'
podman exec -it nrserver-redis redis-cli DBSIZE

Fila de jobs (Streams). As chaves seguem rq:{<fila>}:..., com rq:{default}:stream:{high|normal|low}, rq:{default}:dead e rq:{default}:jobs:

podman exec -it nrserver-redis redis-cli XLEN 'rq:{default}:stream:normal'
podman exec -it nrserver-redis redis-cli XINFO GROUPS 'rq:{default}:stream:normal'
podman exec -it nrserver-redis redis-cli XPENDING 'rq:{default}:stream:normal' nrserver
podman exec -it nrserver-redis redis-cli LRANGE 'rq:{default}:dead' 0 9
podman exec -it nrserver-redis redis-cli SLOWLOG GET 10

KEYS * funciona, mas bloqueia o servidor. Use SCAN/--scan em qualquer ambiente com dados reais.

5.5 Chaves que o relay cria

O relay usa Redis como acelerador, com TTLs definidos em redis.cache.* (schema completo em docs/data-schema.md):

Chave Tipo TTL padrão Campo de configuração
ban:{pubkey} string 1h cache.ban_ttl
profile:{pubkey} hash 5m cache.profile_ttl
query:{hash} string 30s cache.query_ttl
query:meta:{hash} hash 30s cache.query_meta_ttl
event:{id} string 10m cache.event_ttl
dedup:{id} string 1h cache.dedup_ttl
nip05:doc string 24h fixo no código
sub:filter:{hash} string 5m fixo no código
ws:last_seen:{id} string 2m fixo no código
nip29:* hash/string/list configurável nip29.*_cache_ttl_seconds

Chaves da fila de jobs (rq = relay queue, definidas em infra/queue/redis/keys.go):

Chave Tipo Papel
rq:{<fila>}:stream:{high|normal|low} stream Mensagens por prioridade
rq:{<fila>}:jobs hash Estado/índice dos jobs
rq:{<fila>}:body:<id> string Payload do job (TTL queue.body_ttl_seconds)
rq:{<fila>}:result:<id> string Resultado (TTL queue.result_ttl_seconds)
rq:{<fila>}:meta:<id> hash Metadados do job
rq:{<fila>}:delayed zset Jobs agendados/retry
rq:{<fila>}:dead list Dead-letter
rq:{<fila>}:state, :attempts, :seq hash/string Controle interno
rq:{<fila>}:metrics:*, :workers:* hash Métricas por minuto (TTL queue.metrics_ttl_seconds)

As filas usadas pelo projeto são default, admin e cron (jobs.default_queue e jobs.*.queue).

Por isso o volume do Redis é importante: AOF preserva cache e, principalmente, o estado da fila entre reinícios.


6. Rede, pod e comunicação entre containers

6.1 Rede bridge nomeada (recomendado)

O podman network create nrserver-net da seção 3 já permite que containers se encontrem pelo nome:

postgres:5432
redis:6379

Um container de aplicação na mesma rede usa esses hostnames no conf.yaml. Do host, use 127.0.0.1:5432 e 127.0.0.1:6379 (portas publicadas).

6.2 Podman pod (tudo em localhost)

Um pod compartilha o namespace de rede. Útil quando o relay também roda em container e você quer um único endereço:

podman pod create --name nrserver-pod \
  -p 127.0.0.1:5432:5432 \
  -p 127.0.0.1:6379:6379 \
  -p 9090:9090 \
  -p 127.0.0.1:9091:9091

Depois, em cada podman run, troque --network nrserver-net por --pod nrserver-pod e remova os -p individuais (as portas são do pod):

podman run -d --pod nrserver-pod --name nrserver-postgres \
  -e POSTGRES_DB=nostr -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password \
  -v nrserver-pg-data:/var/lib/postgresql \
  -v "$PWD/deploy/postgres/postgresql.conf:/etc/postgresql/postgresql.conf:ro,Z" \
  -v "$PWD/.local/podman/pg-password.txt:/run/secrets/postgres_password:ro,Z" \
  docker.io/library/postgres:18.4-alpine3.23 \
  postgres -c config_file=/etc/postgresql/postgresql.conf

podman run -d --pod nrserver-pod --name nrserver-redis \
  -v nrserver-redis-data:/data \
  -v "$PWD/deploy/redis/redis.conf:/usr/local/etc/redis/redis.conf:ro,Z" \
  docker.io/library/redis:8.8.0-alpine3.23 \
  redis-server /usr/local/etc/redis/redis.conf

Dentro do pod, 127.0.0.1:5432 e 127.0.0.1:6379 funcionam para o relay. Inspecione o pod com:

podman pod ps
podman pod inspect nrserver-pod --format '{{.InfraContainerID}}'
podman pod stats nrserver-pod

6.3 Acessar serviços do host a partir de um container

Se o PostgreSQL estiver no host (fora do Podman) e o relay em container:

podman run --add-host host.containers.internal:host-gateway ...
# e use host.containers.internal:5432 em db.postgres_uri

Alternativa: --network=host (perde isolamento; evite em produção).


7. Atalho com Podman Compose

Crie compose.dev.yaml (o *.yaml já é ignorado pelo .gitignore):

services:
  postgres:
    image: docker.io/library/postgres:18.4-alpine3.23
    container_name: nrserver-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: nostr
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
      POSTGRES_INITDB_ARGS: "--data-checksums"
    command: ["postgres", "-c", "config_file=/etc/postgresql/postgresql.conf"]
    ports:
      - "127.0.0.1:5432:5432"
    volumes:
      - pg_data:/var/lib/postgresql
      - ./deploy/postgres/postgresql.conf:/etc/postgresql/postgresql.conf:ro,Z
      - ./.local/podman/pg-password.txt:/run/secrets/postgres_password:ro,Z
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d nostr"]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 10s

  redis:
    image: docker.io/library/redis:8.8.0-alpine3.23
    container_name: nrserver-redis
    restart: unless-stopped
    command: ["redis-server", "/usr/local/etc/redis/redis.conf"]
    ports:
      - "127.0.0.1:6379:6379"
    volumes:
      - redis_data:/data
      - ./deploy/redis/redis.conf:/usr/local/etc/redis/redis.conf:ro,Z
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 5

volumes:
  pg_data:
  redis_data:

Subida e verificação:

podman compose -p nrserver-dev -f compose.dev.yaml up -d
podman compose -p nrserver-dev -f compose.dev.yaml ps
podman compose -p nrserver-dev -f compose.dev.yaml logs -f postgres redis

Para subir a stack completa do repositório (relay + migrations + Tor), use o docker-compose.yml oficial — ele já espera deploy/conf.yaml:

podman compose -f docker-compose.yml up -d postgres redis
podman compose -f docker-compose.yml run --rm nrserver-migrate
podman compose -f docker-compose.yml up -d nrserver

Se podman compose falhar por falta de provider, instale podman-compose (pipx install podman-compose) ou habilite o socket e use o provider docker-compose:

systemctl --user enable --now podman.socket
podman compose version

Notas específicas do Podman:

  • restart: unless-stopped em rootless depende do podman-restart.service (systemctl --user enable --now podman-restart). Para produção, prefira Quadlet (seção 13).
  • :Z nos bind mounts é obrigatório em hosts com SELinux (Fedora, RHEL).
  • Use podman unshare para inspecionar/altear arquivos de volumes rootless.

8. Configurar o relay (conf.yaml)

O binário procura conf.yaml no diretório atual, em ../.. e em /etc/nrs (config/config.go). O container oficial monta em /app/conf.yaml.

8.1 Exemplo mínimo para desenvolvimento no host

port: 9090
app_env: development

relay_information:
  url: http://127.0.0.1:9090
  name: Nostr Relay Server
  description: Relay local de desenvolvimento
  canonical_url: ws://127.0.0.1:9090

db:
  max_conns: 20
  min_conns: 1
  max_conn_lifetime_minutes: 30
  max_conn_idle_minutes: 5
  health_check_period_seconds: 30
  postgres_uri: "postgres://postgres:[email protected]:5432/nostr?sslmode=disable"

redis:
  enabled: true
  addr: "127.0.0.1:6379"
  password: ""
  db: 0
  pool_size: 10
  subscription_cleanup_interval_seconds: 60
  subscription_stale_after_seconds: 120
  cache:
    ban_ttl: 3600
    profile_ttl: 300
    query_ttl: 30
    query_meta_ttl: 30
    event_ttl: 600
    dedup_ttl: 3600
  queue:
    enabled: true
    consumer_group: nrserver
    worker_count: 2
    block_ms: 5000
    batch_size: 32
    max_len_approx: 100000
    body_ttl_seconds: 259200
    result_ttl_seconds: 259200
    metrics_ttl_seconds: 172800
    reclaim_idle_seconds: 120
    reclaim_batch_size: 100
    promote_batch_size: 100
    promote_interval_ms: 1000
    recent_jobs_list_limit: 1000

Se o relay também estiver na rede do Podman/Compose, troque para os hostnames:

db:
  postgres_uri: "postgres://postgres:SENHA_HEX@postgres:5432/nostr?sslmode=disable"
redis:
  addr: "redis:6379"

8.2 Campos do PostgreSQL

Campo Papel Observação
postgres_uri DSN completo Obrigatório. Formato postgres://user:pass@host:port/db?sslmode=...
max_conns Conexões máximas do pool Deve ser menor que max_connections do servidor
min_conns Conexões mantidas 1 é suficiente para dev
max_conn_lifetime_minutes Idade máxima da conexão Recicla conexões atrás de PgBouncer/proxy
max_conn_idle_minutes Tempo ocioso máximo Libera recursos em ociosidade
health_check_period_seconds Intervalo do ping 30s padrão

Codificação da senha: caracteres como @, :, /, # e % precisam de URL-encoding dentro da URI (@ → %40, : → %3A, / → %2F). Usar senha hexadecimal (openssl rand -hex 24) evita o problema por completo.

TLS: com sslmode=disable o tráfego é texto puro — aceitável em loopback ou rede interna. Em rede compartilhada, configure TLS no PostgreSQL e use sslmode=verify-full com sslrootcert.

8.3 Campos do Redis

Campo Papel
enabled Liga/desliga todo o uso de Redis; false mantém o relay funcionando só com PostgreSQL
addr host:porta
password Senha (requirepass/ACL); vazio se não houver
db Índice do banco lógico (0–15 por padrão)
pool_size Conexões no pool
subscription_cleanup_interval_seconds Frequência da limpeza de inscrições
subscription_stale_after_seconds Idade para considerar inscrição abandonada
cache.* TTLs por tipo de chave (ver tabela 5.5)
queue.* Fila de jobs em Streams: grupo, workers, batch, retenção e reclaim

redis.enabled: false é suportado, mas você perde cache de consultas e a fila de jobs. Em produção com tráfego real, mantenha habilitado.

8.4 Segurança do arquivo

chmod 600 conf.yaml
grep -n 'postgres_uri\|priv_key\|admin_token' conf.yaml   # revise antes de commitar

Nunca versione conf.yaml real: ele já está no .gitignore do projeto.


9. Migrations e primeira subida

O schema não é criado automaticamente pelo PostgreSQL; ele é versionado em infra/db/migrations e embutido no binário.

9.1 Binário local

# com as variáveis apontando para os containers
./nrserver migrate status
./nrserver migrate up

Ou via Go:

go run ./cmd/nrserver migrate up

9.2 Com a imagem do projeto

podman build -t nostr-relay-server:local .

podman run --rm \
  --network nrserver-net \
  -v "$PWD/conf.yaml:/app/conf.yaml:ro,Z" \
  nostr-relay-server:local migrate up

9.3 Subir o relay

./nrserver server
# ou:
podman run -d --name nrserver \
  --network nrserver-net \
  -p 9090:9090 -p 127.0.0.1:9091:9091 \
  -v "$PWD/conf.yaml:/app/conf.yaml:ro,Z" \
  nostr-relay-server:local

9.4 Validar a stack

curl -i -H 'Accept: application/nostr+json' http://127.0.0.1:9090/
curl -i http://127.0.0.1:9090/.well-known/nostr.json
curl -i http://127.0.0.1:9091/metrics
curl -i http://127.0.0.1:9091/panel

Esperado:

  • GET / sem o header Nostr retorna 426 Upgrade Required (normal).
  • /.well-known/nostr.json retorna JSON com names.
  • /metrics expõe as métricas Prometheus.
  • /panel serve o painel administrativo embutido.

Confirme que o relay está gravando no banco e usando o cache:

podman exec -it nrserver-postgres psql -U postgres -d nostr -c '\dt'
podman exec -it nrserver-postgres psql -U postgres -d nostr -c 'select count(*) from event;'
podman exec -it nrserver-redis redis-cli DBSIZE

10. Operação do dia a dia

# estado
podman ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
podman stats --no-stream nrserver-postgres nrserver-redis
podman healthcheck run nrserver-postgres
podman healthcheck run nrserver-redis

# logs
podman logs --tail 100 nrserver-postgres
podman logs -f nrserver-redis

# shell
podman exec -it nrserver-postgres psql -U postgres -d nostr
podman exec -it nrserver-redis redis-cli

# ciclo de vida
podman stop nrserver-postgres nrserver-redis
podman start nrserver-postgres nrserver-redis
podman restart nrserver-redis

# inspeção
podman inspect nrserver-postgres --format '{{json .Config.Env}}'
podman volume inspect nrserver-pg-data --format '{{.Mountpoint}}'
podman port nrserver-postgres

Monitoramento rápido do PostgreSQL:

podman exec -it nrserver-postgres psql -U postgres -d nostr -c '
select state, count(*)
from pg_stat_activity
where datname = $$nostr$$
group by state;'

podman exec -it nrserver-postgres psql -U postgres -d nostr -c '
select relname, n_live_tup
from pg_stat_user_tables
order by n_live_tup desc
limit 10;'

podman exec -it nrserver-postgres psql -U postgres -d nostr -c '
select pg_size_pretty(pg_database_size($$nostr$$));'

Ajuste de parâmetros sem recriar o container (persistente no volume):

podman exec -it nrserver-postgres psql -U postgres -d nostr -c \
  'alter system set work_mem = $$8MB$$;'
podman exec -it nrserver-postgres psql -U postgres -d nostr -c \
  'select pg_reload_conf();'

shared_buffers, max_connections e wal_buffers exigem restart (podman restart nrserver-postgres).

Estatísticas e manutenção:

podman exec -it nrserver-postgres psql -U postgres -d nostr -c 'VACUUM (ANALYZE);'
podman exec -it nrserver-postgres psql -U postgres -d nostr -c 'REINDEX DATABASE nostr;'

O relay já agenda VACUUM/ANALYZE/REINDEX em cron.db_optimization; use os comandos acima apenas para manutenção manual pontual.


11. Backup e restauração

11.1 PostgreSQL — dump lógico

podman exec nrserver-postgres \
  pg_dump -U postgres -Fc -d nostr > "backup-nostr-$(date +%F-%H%M).dump"

Restaurar em um banco vazio (ou recriado):

podman exec -i nrserver-postgres \
  pg_restore -U postgres -d nostr --clean --if-exists < backup-nostr-XXXX.dump

Ou em SQL puro:

podman exec nrserver-postgres \
  pg_dump -U postgres -d nostr | gzip > nostr-$(date +%F).sql.gz

11.2 PostgreSQL — base física (parar o serviço)

podman stop nrserver-postgres
podman run --rm \
  -v nrserver-pg-data:/from:ro \
  -v "$PWD/.local/backup:/to" \
  docker.io/library/alpine:3.23 \
  sh -c 'tar czf /to/pg-data-$(date +%F).tgz -C /from .'
podman start nrserver-postgres

11.3 Redis

# força um snapshot
podman exec nrserver-redis redis-cli BGSAVE
sleep 2
podman cp nrserver-redis:/data/dump.rdb ./.local/backup/dump.rdb

# restaurar
podman stop nrserver-redis
podman cp ./.local/backup/dump.rdb nrserver-redis:/data/dump.rdb
podman start nrserver-redis

Com AOF habilitado, copie também appendonlydir/:

podman cp nrserver-redis:/data/appendonlydir ./.local/backup/appendonlydir

Redis é cache/fila, não fonte da verdade. Perder o volume não corrompe o relay: o pior efeito é perda de jobs pendentes e cache frio.


12. Persistência, rootless e SELinux

12.1 Onde ficam os dados

podman volume inspect nrserver-pg-data --format '{{.Mountpoint}}'
podman volume inspect nrserver-redis-data --format '{{.Mountpoint}}'

Rootless: sob ~/.local/share/containers/storage/volumes/..., cujo acesso direto pelo host é limitado pelo user namespace. Use podman unshare:

podman unshare ls -la \
  "$(podman volume inspect nrserver-pg-data --format '{{.Mountpoint}}')"

12.2 SELinux

Em hosts com SELinux, bind mount sem label gera Permission denied:

# correto
-v "$PWD/deploy/redis/redis.conf:/usr/local/etc/redis/redis.conf:ro,Z"

# diagnóstico
ls -Z deploy/redis/redis.conf
podman logs nrserver-redis
sudo ausearch -m avc -ts recent

Z aplica label privado (só aquele container acessa); z aplica label compartilhado. Para arquivos de configuração de um único serviço, use Z.

12.3 Portas privilegiadas

Rootless não publica portas < 1024 por padrão. Alternativas:

# 1) aumentar o mínimo permitido
sudo sysctl net.ipv4.ip_unprivileged_port_start=80

# 2) redirecionar com firewall/socat/proxy reverso para a porta alta

O relay usa 9090/9091, então isso normalmente não é um problema.

12.4 Limites de recurso

podman run ... \
  --memory 2g --memory-swap 2g \
  --cpus 2 \
  --pids-limit 512 \
  ...

Para PostgreSQL, não limite memória abaixo de shared_buffers + (work_mem × max_connections); caso contrário o OOM killer derruba o processo.


13. Autostart com Quadlet/systemd

podman generate systemd está depreciado. O caminho atual é Quadlet (Podman 4.4+), que transforma arquivos declarativos em units systemd.

Diretório (rootless):

mkdir -p ~/.config/containers/systemd

Substitua /CAMINHO/ABSOLUTO/nostr-relay-server pelo caminho real do clone neste host. Em Quadlet, %h expande para o home do usuário, mas caminhos absolutos são mais previsíveis.

13.1 Rede

~/.config/containers/systemd/nrserver.network:

[Network]
Subnet=10.89.10.0/24

13.2 PostgreSQL

~/.config/containers/systemd/nrserver-postgres.container:

[Unit]
Description=PostgreSQL para o Nostr Relay Server
Wants=network-online.target
After=network-online.target

[Container]
Image=docker.io/library/postgres:18.4-alpine3.23
ContainerName=nrserver-postgres
Network=nrserver.network
PublishPort=127.0.0.1:5432:5432
Environment=POSTGRES_DB=nostr
Environment=POSTGRES_USER=postgres
Environment=POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password
Environment=POSTGRES_INITDB_ARGS=--data-checksums
Volume=nrserver-pg-data:/var/lib/postgresql
Volume=/CAMINHO/ABSOLUTO/nostr-relay-server/deploy/postgres/postgresql.conf:/etc/postgresql/postgresql.conf:ro,Z
Volume=/CAMINHO/ABSOLUTO/nostr-relay-server/.local/podman/pg-password.txt:/run/secrets/postgres_password:ro,Z
Exec=postgres -c config_file=/etc/postgresql/postgresql.conf
HealthCmd=pg_isready -U postgres -d nostr
HealthInterval=10s
HealthTimeout=5s
HealthRetries=10
HealthStartPeriod=10s

[Service]
Restart=always

[Install]
WantedBy=default.target

13.3 Redis

~/.config/containers/systemd/nrserver-redis.container:

[Unit]
Description=Redis para o Nostr Relay Server
Wants=network-online.target
After=network-online.target

[Container]
Image=docker.io/library/redis:8.8.0-alpine3.23
ContainerName=nrserver-redis
Network=nrserver.network
PublishPort=127.0.0.1:6379:6379
Volume=nrserver-redis-data:/data
Volume=/CAMINHO/ABSOLUTO/nostr-relay-server/deploy/redis/redis.conf:/usr/local/etc/redis/redis.conf:ro,Z
Exec=redis-server /usr/local/etc/redis/redis.conf

[Service]
Restart=always

[Install]
WantedBy=default.target

Se você habilitar requirepass, o healthcheck precisa de autenticação. Adicione Environment=REDIS_PASSWORD=... e use HealthCmd=sh -c 'redis-cli --no-auth-warning -a "$REDIS_PASSWORD" ping'.

13.4 Ativar

systemctl --user daemon-reload
systemctl --user enable --now nrserver-postgres.service
systemctl --user enable --now nrserver-redis.service

systemctl --user status nrserver-postgres.service
journalctl --user -u nrserver-postgres -f

Para os serviços subirem sem sessão aberta (boot do servidor), habilite o linger:

loginctl enable-linger "$USER"

Os arquivos .container geram units com o mesmo nome do arquivo. Alterações exigem systemctl --user daemon-reload.


14. Checklist de segurança

  • PostgreSQL e Redis publicados apenas em 127.0.0.1 (ou sem PublishPort, acessíveis só pela rede do Podman).
  • Senhas fortes e distintas, em arquivos chmod 600 ou podman secret.
  • POSTGRES_PASSWORD_FILE em vez de POSTGRES_PASSWORD na linha de comando.
  • requirepass/ACL no Redis sempre que houver mais de um container na rede.
  • maxmemory-policy volatile-lru (ou noeviction) quando a fila estiver ativa.
  • conf.yaml com chmod 600 e fora do Git (já ignorado).
  • Imagens fixadas por tag/digest; podman auto-update só com política definida.
  • Usuário não-root no host, rootless Podman.
  • Backup automatizado do PostgreSQL (dump diário + retenção).
  • journalctl/logs com rotação; disco do volume monitorado.
  • sslmode=disable apenas em loopback/rede interna confiável.
  • Migrations aplicadas com nrserver migrate up antes de trocar o binário.

15. Troubleshooting

Sintoma Causa provável Correção
initdb: directory "/var/lib/postgresql/data" exists but is not empty Volume no caminho errado para PG 18 Monte em /var/lib/postgresql
role "postgres" does not exist Volume já inicializado com outro POSTGRES_USER Recrie o volume ou use createuser/ALTER ROLE
password authentication failed for user "postgres" Senha com caractere especial não escapado na URI, ou senha antiga no volume Use %40/%3A/%2F ou senha hex; se necessário ALTER USER
Variável POSTGRES_PASSWORD alterada não tem efeito Só vale no primeiro initdb ALTER USER postgres WITH PASSWORD ...
Permission denied ao montar redis.conf SELinux Adicione :ro,Z ao bind mount
Permission denied em arquivos do volume rootless User namespace podman unshare chown -R 0:0 <mountpoint>
NOAUTH Authentication required no relay Redis com requirepass, conf.yaml sem redis.password Preencha redis.password
MISCONF Redis is configured to save RDB snapshots... Disco cheio ou /data sem permissão de escrita Libere espaço; garanta o volume em /data
OOM/container do Postgres morto Limite de memória baixo Aumente --memory ou reduza shared_buffers/work_mem
bind: address already in use Porta ocupada no host ss -ltnp | grep -E '5432|6379' e ajuste o -p
Relay não conecta no banco 127.0.0.1 usado de dentro de container Use postgres:5432 (rede) ou host.containers.internal
too many connections db.max_conns ≥ max_connections Aumente max_connections ou reduza o pool
Redis perde jobs após restart AOF desligado ou volume ausente appendonly yes + volume em /data
Healthcheck do Redis falha com senha redis-cli ping sem auth Use -a "$REDIS_PASSWORD" --no-auth-warning

Diagnóstico geral:

podman inspect nrserver-postgres --format '{{.State.Health.Status}}'
podman events --filter container=nrserver-postgres --since 30m
podman system df
podman volume ls --format '{{.Name}}\t{{.Mountpoint}}'
journalctl --user -u nrserver-postgres -n 100 --no-pager

Referências no repositório

Arquivo Conteúdo
docker-compose.yml Stack de referência (postgres, redis, relay, tor)
deploy/postgres/postgresql.conf Tuning do PostgreSQL usado em produção
deploy/redis/redis.conf Configuração do Redis (AOF + snapshots)
deploy/conf.yaml Exemplo de configuração com hostnames internos
conf.yaml Configuração local/desenvolvimento
config/conf-data.go Structs de db e redis (todos os campos válidos)
docs/data-schema.md Schema SQL e chaves/TTLs do Redis
README.md Requisitos, endpoints e execução com Docker
infra/db/migrations/ Migrations aplicadas por nrserver migrate up
updated 2026-11-13 02:18 JST