
Tutorial: construir e usar a imagem do Nostr Relay Server (Docker e Podman)
Este tutorial cobre, de ponta a ponta:
- Obter o código do GitHub (release, tag ou commit).
- Construir a imagem com Docker e com Podman, incluindo multi-arquitetura.
- Rodar a imagem com PostgreSQL e Redis.
- Publicar sua própria imagem (Docker Hub, GHCR, GitLab).
- Atualizar e diagnosticar a imagem.
- Usar o artigo
PODMAN_POSTGRES_REDIS.mdjunto 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-amd64enrserver-linux-arm64; Docker Hub e GHCR não têmnostr-relay-server/nrserverpúblico. Portanto, para usar container é necessário construir a imagem a partir do código — é exatamente o que este tutorial faz.
Sumário
- TL;DR
- O que a imagem contém
- Pré-requisitos
- Obter o código do GitHub
- Construir com Docker
- Construir com Podman
- Build args e o que cada estágio faz
- Rodar a imagem pela primeira vez
- Usar junto com o tutorial de PostgreSQL/Redis
- Compose: Docker e Podman
- Publicar sua própria imagem
- Atualizar a imagem em produção
- Segurança e boas práticas
- Troubleshooting
- 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 ... shfalha; para inspecionar o CLI usedocker run --rm <img> --helpou sobrescreva--entrypoint. - O processo roda como UID 65532, então o
conf.yamlmontado precisa ser legível por esse UID (normalmentechmod 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
/healthzna porta 9090, mas o servidor expõeGET /healthna porta interna (port + 1, padrão 9091). Use--no-healthchecke monitore/healthexternamente.
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 statusunhealthydo 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.7por 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
Makefiletambém temmake docker, mas ele publica localmente comogmouradev96/nrserver:$(VERSION)e passa--build-arg COMMIT, que oDockerfileatual 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
amd64usa emulação QEMU (mais lento); o buildarm64é nativo. - O
Dockerfilejá respeitaTARGETOS/TARGETARCHnogo builde usa$BUILDPLATFORMpara 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/subuide/etc/subgidpara o usuário.cannot clone: Operation not permittedem kernels restritos → verifique user namespaces (sysctl kernel.unprivileged_userns_cloneem distros antigas).- Cache lento → use
--layerse 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.yamlem 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.ymlestack.ymlnã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:6379se o relay estiver na mesma rede de containers. Se o relay rodar no host, use127.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.Healthcomo sinal de saúde desta imagem — o healthcheck embutido aponta para/healthzna 9090 e vai marcarunhealthy(seção 2.1). Use/healthna 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 --helpou construa uma imagem de debug comFROM 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
podmanpordockere 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 paraconf.local.yamle ajuste o volume no seu próprio overlay de compose — não edite o arquivo versionado com segredos.
Como a imagem declara um
HEALTHCHECKque aponta para/healthz, o serviçonrserveraparece comounhealthynocompose ps(seção 2.1). Para silenciar sem editar o compose versionado, use um override:# compose.override.yaml services: nrserver: healthcheck: disable: truee 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_DATEvia--build-arge 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:
- Repositório: https://github.com/gabrielmoura/nostr-relay-server
- Releases (binários): https://github.com/gabrielmoura/nostr-relay-server/releases
- Distroless: https://github.com/GoogleContainerTools/distroless
- Podman build: https://docs.podman.io/en/latest/markdown/podman-build.1.html
- Docker buildx: https://docs.docker.com/build/