
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.mdeREADME.md.
Sumário
- Visão geral
- Pré-requisitos
- Estrutura local, segredos e volumes
- Subir o PostgreSQL
- Subir o Redis
- Rede, pod e comunicação entre containers
- Atalho com Podman Compose
- Configurar o relay (
conf.yaml) - Migrations e primeira subida
- Operação do dia a dia
- Backup e restauração
- Persistência, rootless e SELinux
- Autostart com Quadlet/systemd
- Checklist de segurança
- 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-dockercria um wrapperdocker; o daemon continua sem existir. Prefira escreverpodmanpara 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/datana imagem 18 faz oinitdbfalhar 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/migrationse aplicado comnrserver 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.0dentro 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 nosó é aceitável porque o acesso está limitado ao loopback ou à rede interna do Podman. Nunca publique6379em0.0.0.0semrequirepass/ACL e firewall.appendonly yesgrava o AOF em/data(volume), reduzindo perda de dados.- Os três
savemantê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-lrue nãoallkeys-lru? O relay também usa Redis como fila (queue.enabled), baseada em Streams.allkeys-lrupode despejar mensagens da fila.volatile-lrusó 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 inspectpara 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ão600) no lugar de-e. A imagem oficial do Redis não suporta*_FILE, entãopodman secretsó 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. UseSCAN/--scanem 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 composefalhar por falta de provider, instalepodman-compose(pipx install podman-compose) ou habilite o socket e use o providerdocker-compose:systemctl --user enable --now podman.socket podman compose version
Notas específicas do Podman:
restart: unless-stoppedem rootless depende dopodman-restart.service(systemctl --user enable --now podman-restart). Para produção, prefira Quadlet (seção 13).:Znos bind mounts é obrigatório em hosts com SELinux (Fedora, RHEL).- Use
podman unsharepara 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 retorna426 Upgrade Required(normal)./.well-known/nostr.jsonretorna JSON comnames./metricsexpõe as métricas Prometheus./panelserve 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_connectionsewal_buffersexigem 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-serverpelo caminho real do clone neste host. Em Quadlet,%hexpande 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. AdicioneEnvironment=REDIS_PASSWORD=...e useHealthCmd=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
.containergeram units com o mesmo nome do arquivo. Alterações exigemsystemctl --user daemon-reload.
14. Checklist de segurança
- PostgreSQL e Redis publicados apenas em
127.0.0.1(ou semPublishPort, acessíveis só pela rede do Podman). - Senhas fortes e distintas, em arquivos
chmod 600oupodman secret. -
POSTGRES_PASSWORD_FILEem vez dePOSTGRES_PASSWORDna linha de comando. -
requirepass/ACL no Redis sempre que houver mais de um container na rede. -
maxmemory-policy volatile-lru(ounoeviction) quando a fila estiver ativa. -
conf.yamlcomchmod 600e fora do Git (já ignorado). - Imagens fixadas por tag/digest;
podman auto-updatesó 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=disableapenas em loopback/rede interna confiável. - Migrations aplicadas com
nrserver migrate upantes 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 |