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

Tutorial: construir e usar a imagem do Nostr Relay Server (Docker e Podman)

Este tutorial cobre, de ponta a ponta:

  1. Obter o código do GitHub (release, tag ou commit).
  2. Construir a imagem com Docker e com Podman, incluindo multi-arquitetura.
  3. Rodar a imagem com PostgreSQL e Redis.
  4. Publicar sua própria imagem (Docker Hub, GHCR, GitLab).
  5. Atualizar e diagnosticar a imagem.
  6. Usar o artigo PODMAN_POSTGRES_REDIS.md junto com a imagem.

Aviso importante sobre imagem pronta: o projeto não publica imagem de container oficial. As releases do GitHub trazem apenas os binários nrserver-linux-amd64 e nrserver-linux-arm64; Docker Hub e GHCR não têm nostr-relay-server / nrserver público. Portanto, para usar container é necessário construir a imagem a partir do código — é exatamente o que este tutorial faz.


Sumário

  1. TL;DR
  2. O que a imagem contém
  3. Pré-requisitos
  4. Obter o código do GitHub
  5. Construir com Docker
  6. Construir com Podman
  7. Build args e o que cada estágio faz
  8. Rodar a imagem pela primeira vez
  9. Usar junto com o tutorial de PostgreSQL/Redis
  10. Compose: Docker e Podman
  11. Publicar sua própria imagem
  12. Atualizar a imagem em produção
  13. Segurança e boas práticas
  14. Troubleshooting
  15. Referências

1. TL;DR

Docker

git clone https://github.com/gabrielmoura/nostr-relay-server.git
cd nostr-relay-server

docker build \
  --build-arg VERSION="$(git describe --tags --always)" \
  --build-arg BUILD_DATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  -t nostr-relay-server:local .

docker run --rm nostr-relay-server:local --help

Podman

git clone https://github.com/gabrielmoura/nostr-relay-server.git
cd nostr-relay-server

podman build \
  --build-arg VERSION="$(git describe --tags --always)" \
  --build-arg BUILD_DATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  -t nostr-relay-server:local .

podman run --rm nostr-relay-server:local --help

Rodar (depois de subir PostgreSQL/Redis — seção 9)

# Docker
docker run -d --name nrserver \
  --no-healthcheck \
  --network nrserver-net \
  -p 9090:9090 -p 127.0.0.1:9091:9091 \
  -v "$PWD/conf.yaml:/app/conf.yaml:ro" \
  nostr-relay-server:local

# Podman
podman run -d --name nrserver \
  --no-healthcheck \
  --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

2. O que a imagem contém

O Dockerfile é multi-stage e no final entrega uma imagem distroless:

golang:1.26.3-alpine3.23   ─┐
node:22.19.0-alpine        ─┼─► build (pnpm + go build) ─► distroless/static-debian12:nonroot
                            │                              ├── /app/nrserver
                            │                              └── /app/nostr.png

Características relevantes:

Item Valor
Imagem final gcr.io/distroless/static-debian12:nonroot
Usuário não-root (UID 65532)
WORKDIR /app
Binário /app/nrserver (estático, CGO_ENABLED=0)
ENTRYPOINT ["/app/nrserver"]
CMD ["server"]
Portas 9090 (relay) e 9091 (admin/métricas)
HEALTHCHECK /app/nrserver healthcheck → GET http://127.0.0.1:9090/healthz
Config procurada como conf.yaml em /app, ., ../.., /etc/nrs

Consequências práticas:

  • Não existe shell na imagem final. docker run ... sh falha; para inspecionar o CLI use docker run --rm <img> --help ou sobrescreva --entrypoint.
  • O processo roda como UID 65532, então o conf.yaml montado precisa ser legível por esse UID (normalmente chmod 644; veja a seção 13).
  • Como o WORKDIR é /app, o caminho natural do arquivo é /app/conf.yaml.
  • Healthcheck embutido não funciona hoje (ver 2.1): ele chama /healthz na porta 9090, mas o servidor expõe GET /health na porta interna (port + 1, padrão 9091). Use --no-healthcheck e monitore /health externamente.

2.1 Sobre o HEALTHCHECK da imagem

O Dockerfile declara:

HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
    CMD ["/app/nrserver", "healthcheck"]

E cmd/healthcheck.go consulta um endereço fixo:

const defaultHealthcheckURL = "http://127.0.0.1:9090/healthz"

Porém, o roteador registra a readiness em outro caminho e na porta interna (infra/net/router.go):

app.Get("/health", httphandler.Readiness())   // servidor interno (9091)

Ou seja, /healthz não existe e /health está em 9091. O efeito é que, após o start-period + retries, o container aparece como unhealthy no docker ps/podman ps, embora o relay esteja funcionando. Isso não reinicia o container (Docker/Podman não reiniciam por healthcheck), mas confunde monitoramento e orquestradores.

Formas de lidar:

# 1) desativar o healthcheck embutido (recomendado para esta imagem)
docker run --no-healthcheck ...
podman run --no-healthcheck ...

# 2) monitorar de fora (host, proxy, Prometheus blackbox, systemd)
curl -fsS http://127.0.0.1:9091/health

# 3) se você mantém um fork: corrija o path no Dockerfile/CLI e rebuild
#    (ex.: /health na porta interna) — não é o caso da imagem upstream

Resumo: trate /health (9091) como o probe oficial e ignore o status unhealthy do healthcheck embutido, ou desative-o explicitamente.


3. Pré-requisitos

3.1 Docker

docker version
docker buildx version        # necessário para multi-arquitetura
docker compose version       # opcional
  • Docker Engine 23+ (BuildKit é o builder padrão).
  • ~3 GB livres em disco para camadas, cache de módulos Go e pnpm store.
  • Acesso à internet no build: o Dockerfile baixa imagens base, módulos Go e dependências do painel (pnpm).

3.2 Podman

podman version
podman build --version
podman compose version       # opcional
  • Podman 4.4+ recomendado (Quadlet, --platform, manifest).
  • Rootless funciona sem configuração extra na maioria das distribuições. Verifique:
podman info --format '{{.Host.Security.Rootless}}'   # true
grep "$USER" /etc/subuid /etc/subgid                # necessário para rootless

3.3 Recursos de build usados pelo Dockerfile

Recurso Versão padrão Como trocar
Go 1.26.3 --build-arg GO_VERSION=...
Node.js 22.19.0 --build-arg NODE_VERSION=...
Alpine 3.23 --build-arg ALPINE_VERSION=...
pnpm 11.3.0 fixo no Dockerfile

O BuildKit também baixa a frontend docker/dockerfile:1.7 por causa da diretiva # syntax=. Em ambientes sem internet, espelhe/pre-pull essas imagens e a frontend antes do build.


4. Obter o código do GitHub

Repositório: https://github.com/gabrielmoura/nostr-relay-server

4.1 Existe imagem publicada? (verificação)

# Docker Hub
curl -s -o /dev/null -w '%{http_code}\n' \
  https://hub.docker.com/v2/repositories/gmouradev96/nrserver/     # 404

# GHCR (sem credencial)
curl -s -o /dev/null -w '%{http_code}\n' \
  https://ghcr.io/v2/gabrielmoura/nostr-relay-server/tags/list    # 401

Hoje o resultado é “não existe imagem pública”. As releases do GitHub têm apenas binários. Confirme você mesmo:

gh release view --repo gabrielmoura/nostr-relay-server       # se tiver gh
# ou
curl -s https://api.github.com/repos/gabrielmoura/nostr-relay-server/releases/latest \
  | grep -E '"name"|browser_download_url'

Saída esperada (v0.4.2):

nrserver-linux-amd64
nrserver-linux-arm64

4.2 Clonar o código (recomendado para build)

git clone https://github.com/gabrielmoura/nostr-relay-server.git
cd nostr-relay-server
git log -1 --oneline

Com SSH:

git clone [email protected]:gabrielmoura/nostr-relay-server.git

Clone raso (mais rápido; git describe fica menos preciso):

git clone --depth 1 https://github.com/gabrielmoura/nostr-relay-server.git

4.3 Fixar uma versão (tag) ou commit

# tags disponíveis
git tag --sort=-v:refname | head

# checkout de uma release
git checkout v0.4.2

# ou um commit específico
git checkout <sha>

Build reprodutível: use tag ou SHA, nunca main em produção.

4.4 Atualizar depois

git fetch --tags --prune
git checkout v0.5.0
# rebuild (seções 5 e 6)

4.5 Baixar só o release binário (sem container)

Se você não quer container, a release serve para instalação nativa:

VERSION=v0.4.2
curl -fLO "https://github.com/gabrielmoura/nostr-relay-server/releases/download/$VERSION/nrserver-linux-amd64"
chmod +x nrserver-linux-amd64
./nrserver-linux-amd64 --help

Isso não é uma imagem; é o binário para systemd/bare metal. Para container, siga para a construção.


5. Construir com Docker

5.1 Build básico

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

O primeiro build costuma levar vários minutos (download de módulos Go + pnpm install + build do painel React). Os seguintes aproveitam cache.

5.2 Build com metadados (tags OCI)

VERSION="$(git describe --tags --always --dirty)"
BUILD_DATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)"

docker build \
  --build-arg VERSION="$VERSION" \
  --build-arg BUILD_DATE="$BUILD_DATE" \
  -t nostr-relay-server:"$VERSION" \
  -t nostr-relay-server:local \
  .

O Makefile também tem make docker, mas ele publica localmente como gmouradev96/nrserver:$(VERSION) e passa --build-arg COMMIT, que o Dockerfile atual não consome (o Docker apenas emite um aviso). Prefira os comandos explícitos deste tutorial para controlar nome/tag.

5.3 Cache entre builds

BuildKit já usa cache mounts internos (/go/pkg/mod, /root/.cache/go-build, /pnpm/store). Para compartilhar cache entre máquinas/CI:

docker buildx build \
  --cache-from type=registry,ref=registry.example.com/nrserver:buildcache \
  --cache-to   type=registry,ref=registry.example.com/nrserver:buildcache,mode=max \
  -t registry.example.com/nrserver:local --push .

Ou cache local:

docker build \
  --cache-from nostr-relay-server:local \
  -t nostr-relay-server:local .

5.4 Multi-arquitetura (amd64 + arm64)

docker buildx create --name nrserver-builder --use --driver docker-container
docker buildx inspect --bootstrap

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --build-arg VERSION="$(git describe --tags --always)" \
  -t SEU_USUARIO/nrserver:latest \
  --push .

Notas:

  • --push é obrigatório ao gerar múltiplas plataformas (o resultado não fica na imagem local do Docker).
  • Para carregar uma plataforma localmente: --load --platform linux/amd64.
  • Em Mac ARM, o build amd64 usa emulação QEMU (mais lento); o build arm64 é nativo.
  • O Dockerfile já respeita TARGETOS/TARGETARCH no go build e usa $BUILDPLATFORM para os estágios de toolchain — não é preciso editar nada.

5.5 Verificar

docker images nostr-relay-server
docker image inspect nostr-relay-server:local \
  --format '{{.Config.User}} | {{json .Config.ExposedPorts}} | {{json .Config.Labels}}'
docker history --no-trunc nostr-relay-server:local | head
docker run --rm nostr-relay-server:local --help

Saída esperada para o usuário:

65532:65532 | {"9090/tcp":{},"9091/tcp":{}} | {"org.opencontainers.image.version":"..."}

6. Construir com Podman

6.1 Build básico

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

Se você usa alias docker=podman/podman-docker, os comandos da seção 5 funcionam, mas prefira podman build para deixar claro qual engine executou.

6.2 Build com metadados e camadas explícitas

VERSION="$(git describe --tags --always --dirty)"
BUILD_DATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)"

podman build \
  --layers \
  --build-arg VERSION="$VERSION" \
  --build-arg BUILD_DATE="$BUILD_DATE" \
  -t nostr-relay-server:"$VERSION" \
  -t nostr-relay-server:local \
  .

Opções úteis:

Flag Efeito
--layers Reaproveita camadas entre builds (padrão em versões novas, explícito é mais seguro)
--no-cache Reconstrói tudo
--pull=always Atualiza imagens base
--platform linux/amd64 Força arquitetura
--format docker Gera formato Docker (compatibilidade com registries antigos)
--build-arg-file env.list Lê build args de arquivo
--secret id=npm,src=... Injeta segredos de build sem vazar em camadas

6.3 Multi-arquitetura com manifest

Podman 4.1+ builda direto em manifesto:

podman build \
  --manifest localhost/nrserver:latest \
  --platform linux/amd64,linux/arm64 \
  --build-arg VERSION="$(git describe --tags --always)" \
  .

Fluxo clássico (uma arquitetura por vez):

podman manifest create localhost/nrserver:latest

podman build --platform linux/amd64 -t localhost/nrserver:amd64 .
podman build --platform linux/arm64 -t localhost/nrserver:arm64 .

podman manifest add localhost/nrserver:latest localhost/nrserver:amd64
podman manifest add localhost/nrserver:latest localhost/nrserver:arm64

podman manifest inspect localhost/nrserver:latest

6.4 Rootless: o que pode dar errado

  • newuidmap: write to uid_map failed → falta faixa em /etc/subuid e /etc/subgid para o usuário.
  • cannot clone: Operation not permitted em kernels restritos → verifique user namespaces (sysctl kernel.unprivileged_userns_clone em distros antigas).
  • Cache lento → use --layers e mantenha o storage em disco local (não em NFS).

6.5 Verificar

podman images nostr-relay-server
podman inspect nostr-relay-server:local \
  --format '{{.Config.User}} | {{.Config.ExposedPorts}}'
podman run --rm nostr-relay-server:local --help

7. Build args e o que cada estágio faz

7.1 Estágios do Dockerfile

Estágio Base Função
go-deps golang:1.26.3-alpine3.23 Baixa módulos Go (go mod download)
frontend-deps node:22.19.0-alpine Instala pnpm e dependências do painel
frontend-build frontend-deps pnpm run build → infra/dash/dist
backend-build golang:... Copia o código + dist do painel e compila o binário
final distroless/static-debian12:nonroot Runtime mínimo

7.2 Build args disponíveis

Arg Padrão Usado para
GO_VERSION 1.26.3 Imagem do toolchain Go
NODE_VERSION 22.19.0 Imagem do toolchain Node
ALPINE_VERSION 3.23 Tag Alpine das imagens de build
VERSION 0.1.0 Label org.opencontainers.image.version
BUILD_DATE 2026-04-17T00:00:00Z Label org.opencontainers.image.created
COMMIT — Não declarado no Dockerfile atual

Exemplo trocando o toolchain (útil quando uma tag alpine é removida):

docker build \
  --build-arg GO_VERSION=1.26.4 \
  --build-arg NODE_VERSION=22.20.0 \
  -t nostr-relay-server:local .

7.3 O que não entra na imagem

O .dockerignore exclui .git, docs/, README.md, conf.yaml, binários locais, node_modules, dist/ do host e arquivos de compose. Ou seja:

  • Você precisa montar conf.yaml em runtime — ele não é copiado.
  • O painel é embutido no binário durante o build (não depende de arquivos externos em runtime).
  • torrc, docker-compose.yml e stack.yml não fazem parte da imagem.

8. Rodar a imagem pela primeira vez

Antes de rodar o relay, você precisa de um PostgreSQL acessível (e, opcionalmente, Redis). Se ainda não tem, siga a seção 9.

8.1 Preparar conf.yaml

# recomendado: template padrão gerado pelo próprio binário (sem segredos locais)
docker run --rm nostr-relay-server:local conf print > conf.local.yaml
# ou, se você já mantém um conf.yaml local:
# cp conf.yaml conf.local.yaml

chmod 644 conf.local.yaml         # o container roda como UID 65532

No mínimo, ajuste:

port: 9090
db:
  postgres_uri: "postgres://postgres:SUA_SENHA@postgres:5432/nostr?sslmode=disable"
redis:
  enabled: true
  addr: "redis:6379"
  password: ""

Use postgres:5432 / redis:6379 se o relay estiver na mesma rede de containers. Se o relay rodar no host, use 127.0.0.1:5432 / 127.0.0.1:6379.

8.2 Migrations (obrigatório na primeira vez)

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

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

8.3 Subir o relay

# Docker
docker run -d --name nrserver \
  --no-healthcheck \
  --network nrserver-net \
  --restart unless-stopped \
  -p 9090:9090 \
  -p 127.0.0.1:9091:9091 \
  -v "$PWD/conf.local.yaml:/app/conf.yaml:ro" \
  nostr-relay-server:local

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

8.4 Verificar

docker logs --tail 50 nrserver        # ou: podman logs

# readiness real (porta interna = port + 1)
curl -fsS http://127.0.0.1:9091/health && echo
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 responde 426 Upgrade Required (normal); /health, /metrics e /panel respondem 200.

Não use .State.Health como sinal de saúde desta imagem — o healthcheck embutido aponta para /healthz na 9090 e vai marcar unhealthy (seção 2.1). Use /health na 9091 ou desative com --no-healthcheck.

8.5 Rodar apenas o CLI (sem servidor)

A imagem é o próprio CLI:

docker run --rm nostr-relay-server:local --help

docker run --rm -v "$PWD/conf.local.yaml:/app/conf.yaml:ro" \
  --network nrserver-net \
  nostr-relay-server:local migrate status

docker run --rm -v "$PWD/conf.local.yaml:/app/conf.yaml:ro" \
  nostr-relay-server:local conf validate --file /app/conf.yaml

A imagem final não tem shell. Para “entrar” nela, use docker run --rm -it --entrypoint /app/nrserver nostr-relay-server:local --help ou construa uma imagem de debug com FROM golang:... (seção 14).


9. Usar junto com o tutorial de PostgreSQL/Redis

O tutorial PODMAN_POSTGRES_REDIS.md cobre a infraestrutura (PostgreSQL + Redis) com Podman. A ordem de uso é:

1) infra (Postgres/Redis)  →  2) imagem do relay  →  3) migrations  →  4) relay

9.1 Passo 1 — subir PostgreSQL e Redis

Siga uma das opções do outro tutorial:

  • Podman run: seções 3 (segredos/volumes/rede), 4 (PostgreSQL) e 5 (Redis).
  • Podman Compose: seção 7 (compose.dev.yaml).
  • Podman pod: seção 6.2 (se quiser tudo em localhost).

Com a rede nrserver-net criada e os dois containers rodando:

podman ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
podman healthcheck run nrserver-postgres
podman healthcheck run nrserver-redis

9.2 Passo 2 — construir a imagem

Seções 5 (Docker) ou 6 (Podman). Nome recomendado (o compose oficial já usa):

podman build -t nostr-relay-server:local .
# ou
docker build -t nostr-relay-server:local .

9.3 Passo 3 — apontar o conf.yaml para os containers

Se o relay vai rodar na mesma rede nrserver-net (e é o caso dos comandos da seção 8), use os nomes dos serviços:

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

Se o relay vai rodar no host (./nrserver server), use as portas publicadas:

db:
  postgres_uri: "postgres://postgres:[email protected]:5432/nostr?sslmode=disable"
redis:
  enabled: true
  addr: "127.0.0.1:6379"

Detalhes de cada campo e TTLs: seções 8.2, 8.3 e 5.5 do outro tutorial.

9.4 Passo 4 — migrations

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

O outro tutorial usa exatamente este comando na seção 9.2.

9.5 Passo 5 — relay + validação

Use os comandos da seção 8.3 e valide com 8.4 deste documento. O outro tutorial complementa com:

  • Seção 9.4: endpoints esperados.
  • Seção 10: logs, podman exec, pg_stat_activity, redis-cli.
  • Seção 11: backup/restore do PostgreSQL e Redis.
  • Seção 13: Quadlet para o relay subir no boot.
  • Seção 15: tabela de troubleshooting.

9.6 Sequência completa (copiar e colar, Podman)

# 0) código
git clone https://github.com/gabrielmoura/nostr-relay-server.git
cd nostr-relay-server

# 1) infra — siga PODMAN_POSTGRES_REDIS.md seções 3-5
#    resultado esperado:
podman ps --filter name=nrserver-

# 2) imagem
podman build -t nostr-relay-server:local .

# 3) config — template limpo (não copie conf.yaml/deploy/conf.yaml com segredos)
podman run --rm nostr-relay-server:local conf print > conf.local.yaml
#    edite conf.local.yaml:
#      db.postgres_uri → postgres://postgres:SENHA_HEX@postgres:5432/nostr?sslmode=disable
#      redis.addr      → redis:6379
chmod 644 conf.local.yaml

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

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

# 6) validação
curl -fsS http://127.0.0.1:9091/health && echo
curl -i -H 'Accept: application/nostr+json' http://127.0.0.1:9090/
curl -i http://127.0.0.1:9091/metrics

A mesma sequência com Docker troca podman por docker e remove ,Z (o ,Z é específico de SELinux/Podman; no Docker use :ro).


10. Compose: Docker e Podman

O repositório já inclui docker-compose.yml com postgres, redis, tor, nrserver-migrate e nrserver, todos usando a imagem local nostr-relay-server:local.

10.1 Docker Compose

# build + up
docker compose up -d --build

# apenas rebuild da imagem
docker compose build --no-cache

# acompanhar
docker compose logs -f nrserver
docker compose ps

10.2 Podman Compose

podman compose -f docker-compose.yml up -d --build
podman compose -f docker-compose.yml ps
podman compose -f docker-compose.yml logs -f nrserver

Se podman compose não encontrar provider:

pipx install podman-compose
# ou
systemctl --user enable --now podman.socket
podman compose version

10.3 Diferenças que importam

Tema Docker Compose Podman Compose
Build docker compose build podman compose build (ou podman build antes)
SELinux não se aplica use :z/:Z em bind mounts
Rootless N/A portas < 1024 exigem ajuste
Restart no boot restart: unless-stopped depende de podman-restart.service; prefira Quadlet
Rede bridge gerenciada bridge gerenciada; host.containers.internal para o host

O compose oficial monta deploy/conf.yaml (valores de exemplo/produção). Para desenvolvimento local, copie para conf.local.yaml e ajuste o volume no seu próprio overlay de compose — não edite o arquivo versionado com segredos.

Como a imagem declara um HEALTHCHECK que aponta para /healthz, o serviço nrserver aparece como unhealthy no compose ps (seção 2.1). Para silenciar sem editar o compose versionado, use um override:

# compose.override.yaml
services:
  nrserver:
    healthcheck:
      disable: true

e valide a saúde externamente com curl -fsS http://127.0.0.1:9091/health.


11. Publicar sua própria imagem

11.1 Docker Hub

docker login
docker tag nostr-relay-server:local SEU_USUARIO/nrserver:0.4.2
docker tag nostr-relay-server:local SEU_USUARIO/nrserver:latest
docker push SEU_USUARIO/nrserver:0.4.2
docker push SEU_USUARIO/nrserver:latest

11.2 GitHub Container Registry (GHCR)

echo "$GHCR_TOKEN" | docker login ghcr.io -u SEU_USUARIO --password-stdin

docker tag nostr-relay-server:local ghcr.io/SEU_USUARIO/nostr-relay-server:0.4.2
docker push ghcr.io/SEU_USUARIO/nostr-relay-server:0.4.2

O token precisa de write:packages (e read:packages). Depois, torne o pacote público nas configurações do GitHub, se desejar docker pull anônimo.

11.3 GitLab Registry

echo "$GITLAB_TOKEN" | docker login registry.gitlab.com -u SEU_USUARIO --password-stdin

docker tag nostr-relay-server:local registry.gitlab.com/SEU_GRUPO/nostr-relay-server:0.4.2
docker push registry.gitlab.com/SEU_GRUPO/nostr-relay-server:0.4.2

11.4 Podman

podman login docker.io
podman tag nostr-relay-server:local docker.io/SEU_USUARIO/nrserver:0.4.2
podman push docker.io/SEU_USUARIO/nrserver:0.4.2

# multi-arch
podman manifest push --all localhost/nrserver:latest \
  docker.io/SEU_USUARIO/nrserver:latest

11.5 Multi-arquitetura (Docker buildx → qualquer registry)

echo "$TOKEN" | docker login ghcr.io -u SEU_USUARIO --password-stdin

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --build-arg VERSION=0.4.2 \
  -t ghcr.io/SEU_USUARIO/nostr-relay-server:0.4.2 \
  -t ghcr.io/SEU_USUARIO/nostr-relay-server:latest \
  --push .

11.6 Consumir a imagem publicada

docker pull ghcr.io/SEU_USUARIO/nostr-relay-server:0.4.2
# ou
podman pull ghcr.io/SEU_USUARIO/nostr-relay-server:0.4.2

Em produção, fixe pelo digest:

docker pull ghcr.io/SEU_USUARIO/nostr-relay-server@sha256:...

12. Atualizar a imagem em produção

# 1) atualizar código
git fetch --tags --prune
git checkout v0.5.0

# 2) rebuild
docker build -t nostr-relay-server:0.5.0 -t nostr-relay-server:local .
# ou: podman build ...

# 3) migrations ANTES de subir o novo binário
docker run --rm --network nrserver-net \
  -v "$PWD/conf.local.yaml:/app/conf.yaml:ro" \
  nostr-relay-server:0.5.0 migrate up

# 4) recriar o container
docker rm -f nrserver
docker run -d --name nrserver ... nostr-relay-server:0.5.0

# 5) validar
docker logs --tail 100 nrserver
curl -fsS http://127.0.0.1:9091/health && echo ok

Com Compose:

docker compose build nrserver
docker compose run --rm nrserver-migrate
docker compose up -d nrserver

Rollback: mantenha a tag anterior (nostr-relay-server:0.4.2) e rode-a novamente. Migrations down existem (nrserver migrate down) mas revertem uma versão; use com cautela.


13. Segurança e boas práticas

13.1 Runtime não-root

A imagem já roda como UID 65532. Evite --user root. Se precisar de um UID específico do host para volumes:

podman run --userns=keep-id ...

13.2 Permissão do conf.yaml

Erro comum: conf.yaml com 600 e dono do seu usuário → o container (UID 65532) não consegue ler e sai com permission denied.

ls -l conf.local.yaml
chmod 644 conf.local.yaml       # legível pelo container

Alternativas: --userns=keep-id (Podman) ou montar via --mount com UID explícito. Para segredos reais, prefira variáveis de ambiente suportadas pelo projeto ou um gerenciador de segredos — não versione o arquivo.

13.3 Filesystem somente leitura (com ressalvas)

docker run --read-only \
  --tmpfs /tmp \
  -v "$PWD/conf.local.yaml:/app/conf.yaml:ro" \
  -v nrserver-files:/app/files \
  ...

Só ative depois de validar que o relay não escreve em outros caminhos (por exemplo, mídia do Blossom em files/). Se usar store/Blossom, monte o volume de dados explicitamente.

13.4 Portas e exposição

  • 9090 (relay) pode ser público, idealmente atrás de proxy/TLS.
  • 9091 (admin/métricas) deve ficar em loopback ou rede interna: -p 127.0.0.1:9091:9091.

13.5 Scan e proveniência

# Docker
docker scout cves nostr-relay-server:local

# Qualquer engine
trivy image nostr-relay-server:local

# Labels embutidos
docker image inspect nostr-relay-server:local --format '{{json .Config.Labels}}'

Assine/provenance (opcional, buildx):

docker buildx build --sbom=true --provenance=true --push ...

13.6 Build reprodutível

  • Use tag/SHA do Git, não main.
  • Fixe as imagens base por digest em um fork do Dockerfile, se precisar de reprodutibilidade estrita.
  • Registre VERSION/BUILD_DATE via --build-arg e o digest final da imagem.

14. Troubleshooting

14.1 Build

Sintoma Causa Correção
failed to resolve source metadata for docker/dockerfile:1.7 Sem acesso ao Docker Hub/frontend Configure proxy/mirror; pre-pull da frontend
pnpm install falha (rede/timeout) Sem internet ou proxy --build-arg HTTP_PROXY=.../HTTPS_PROXY, ou build em host com saída
go: downloading ... connection refused Proxy/registry Go bloqueado GOPROXY no build (--build-arg não existe; use --env/--network)
Aviso COMMIT build-arg não consumido Dockerfile não declara ARG COMMIT Ignore ou remova do comando
exec format error ao rodar Arquitetura errada Rebuild com --platform linux/amd64 (ou arm64) e --load
Build multi-arch arm64 falha no Podman qemu-user-static/binfmt ausente Instale qemu-user-static (ex.: sudo dnf install qemu-user-static)
Build fica “parado” em pnpm install Download lento de dependências Aguarde; use cache --mount=type=cache (já presente)
no space left on device Cache de build grande docker system prune -af --volumes / podman system prune -af
Podman: newuidmap: write to uid_map failed /etc/subuid//etc/subgid ausente Configure faixas para o usuário ou rode rootful
Podman rootless: permission denied no build Storage em FS sem suporte a user namespace Use disco local (ext4/xfs/btrfs)

14.2 Execução

Sintoma Causa Correção
panic/erro missing DB URI conf.yaml não montado ou sem db.postgres_uri Monte em /app/conf.yaml e preencha o DSN
open conf.yaml: permission denied Arquivo 600 para UID 65532 chmod 644 ou --userns=keep-id
Container reinicia em loop Banco inacessível, credencial errada, migration pendente docker logs, docker inspect, rode migrate up
connect: connection refused para postgres Containers em redes diferentes Use a mesma rede (--network nrserver-net)
dial tcp 127.0.0.1:5432: connect: refused Relay em container usando loopback Troque para postgres:5432 ou host.containers.internal
unhealthy no docker ps com o relay funcionando HEALTHCHECK embutido chama /healthz (inexistente) na 9090 --no-healthcheck e monitore /health na 9091 (seção 2.1)
docker run ... sh: not found Distroless não tem shell Use docker run --rm <img> --help ou imagem de debug
permission denied no volume de mídia Volume do host com dono diferente Ajuste dono/--userns=keep-id/volume nomeado
curl: (52) Empty reply em :9090 Client não enviou upgrade WebSocket Normal em HTTP puro; teste Accept: application/nostr+json
426 Upgrade Required em / Comportamento esperado Não é erro; use /health na 9091 para saúde

14.3 Inspecionar uma imagem sem shell

# binário e argumentos
docker run --rm --entrypoint /app/nrserver nostr-relay-server:local --help

# arquivos da imagem
docker create --name tmpimg nostr-relay-server:local
docker export tmpimg | tar -tvf - | head -30
docker rm tmpimg

# com Podman
podman create --name tmpimg nostr-relay-server:local
podman export tmpimg | tar -tf - | head -30
podman rm tmpimg

14.4 Limpeza

docker system df
docker system prune -af --volumes

podman system df
podman system prune -af
podman image prune -a

15. Referências

Arquivo Conteúdo
Dockerfile Definição multi-stage da imagem
.dockerignore O que não entra no contexto de build
docker-compose.yml Stack com a imagem nostr-relay-server:local
Makefile Alvo make docker (tag gmouradev96/nrserver)
PODMAN_POSTGRES_REDIS.md PostgreSQL e Redis com Podman, conf.yaml, migrations, backup e troubleshooting
install.md Instalação manual, Compose e Swarm
docs/data-schema.md Schema SQL e chaves Redis
README.md Endpoints, requisitos e execução com Docker

Links externos:

updated 2026-11-13 02:28 JST