Hospede o Relayium por conta própria: rode seu servidor de transferência de arquivos e texto

Última atualização: 2026-08-06

O Relayium tem licença AGPL-3.0 e é de código aberto, e o servidor é uma única imagem autocontida — sem banco de dados externo, sem bucket de armazenamento de terceiros, nada para se cadastrar. Se você prefere rodar tudo por conta própria em vez de depender do relayium.com, este guia coloca um servidor no ar com Docker e aponta a CLI para ele.

Auto-hospedar dá a você controle total sobre onde seus dados ficam, seu próprio domínio e certificado TLS, e nenhuma dependência da infraestrutura de mais ninguém. Tudo a seguir se baseia nos arquivos que acompanham o repositório — docker-compose.yml, server/.env.example e docs/self-hosting.md — então nada aqui é uma flag ou configuração que não exista de verdade.

Por que auto-hospedar

As transferências em tempo real do Relayium têm criptografia de ponta a ponta. Um retransmissor TURN auto-hospedado pode transportar bytes cifrados e o servidor processa metadados de sinalização, mas nenhum deles pode ler ou descriptografar o texto simples dos arquivos; nem o servidor nem o retransmissor armazenam uma cópia ou histórico do conteúdo em tempo real no servidor. O servidor guarda sua conta e — para transferências armazenadas/baseadas em link — blobs de texto cifrado e um pequeno banco de dados SQLite. Auto-hospedar significa que esses dados ficam em infraestrutura que você controla, sob seu próprio domínio, sem as decisões operacionais de mais ninguém envolvidas.

Como o projeto tem licença AGPL-3.0 e é de código aberto (github.com/relayium/relayium), você pode ler exatamente o que o servidor faz antes de confiar qualquer coisa a ele, e fazer fork ou modificá-lo livremente.

Início rápido com Docker

O que você precisa antes do passo 1

Um host com o Docker Engine e o plugin do Compose. docker compose version imprime uma linha de versão; se aparecer «docker: 'compose' is not a docker command», o plugin não está instalado.
Um clone do repositório. O arquivo compose constrói a imagem a partir desta árvore de fontes, então precisa do Dockerfile e de web/ ao lado dele — não existe imagem pronta para baixar.
Espaço em disco para o volume nomeado relayium-data: o banco SQLite mais o texto cifrado das transferências armazenadas que você mantiver.
Um domínio e um proxy reverso que termine TLS, caso alguém além de você vá usar. O contêiner só fala HTTP em claro e, por padrão, publica apenas na interface de loopback.
Nada mais. Sem banco de dados externo, sem bucket de armazenamento de objetos, sem conta de terceiros.

A raiz do repositório traz um Dockerfile e um docker-compose.yml que constroem uma única imagem autocontida — um binário Go estático que serve o aplicativo web pré-compilado, então não é preciso um Node, uma cadeia de ferramentas Go ou nginx separados só para executá-lo.

Clone o repositório e entre nele.

git clone https://github.com/relayium/relayium.git

cd relayium

Construa e suba. O segredo de espaço reservado é obrigatório mesmo com o retransmissor desligado: o Compose valida a variável exigida pelo serviço coturn desativado por perfil já na hora de analisar o arquivo, de modo que um docker compose up puro se recusa a iniciar.
```
RELAYIUM_TURN_SECRET=placeholder docker compose up -d --build
```
Confirme que o contêiner continuou de pé em vez de entrar em ciclo de reinício.
```
docker compose ps
```
Pergunte à instância se ela realmente consegue servir. Use /readyz, não /healthz: a diferença entre os dois é todo o sentido dessa checagem, e a caixa de resultado esperado abaixo explica por quê.
```
curl -s http://127.0.0.1:8080/readyz
```
Copie o modelo de configuração e defina sua URL pública. RELAYIUM_BASE_URL monta os links dos e-mails enviados e decide se os cookies de sessão levam o atributo Secure, então precisa ser seu endereço https:// de verdade.
```
cp server/.env.example server/.env
```
```
chmod 600 server/.env
```
Coloque nginx ou Caddy na frente, terminando TLS para o seu domínio e encaminhando tudo — /, /api, /ws, /admin — para a porta 8080. Depois reinicie para que server/.env valha.
```
docker compose up -d
```

Como é uma instância que funciona

O contêiner informa Up e os dois endpoints respondem. O que importa é ready: /healthz devolve ok incondicionalmente, antes de qualquer coisa ser aberta, então também passa numa instância cujo banco ou diretório de blobs está inutilizável. /readyz faz ping no banco SQLite e no diretório de blobs, e responde 503 assim que um dos dois quebra.

$ docker compose ps
NAME                IMAGE                     STATUS          PORTS
relayium-server-1   relayium/relayium:local   Up 12 seconds   127.0.0.1:8080->8080/tcp

$ curl -s http://127.0.0.1:8080/healthz
ok
$ curl -s http://127.0.0.1:8080/readyz
ready

Esse é o servidor inteiro, escutando em :8080. Coloque nginx ou Caddy na frente para o TLS em produção — docs/self-hosting.md cobre o caminho Docker e o que precisa ser redirecionado (proxy); a configuração nginx de produção da própria Relayium não é publicada.
A configuração do aplicativo vem de um arquivo server/.env opcional mais o bloco environment: no docker-compose.yml. Cada configuração tem uma chave RELAYIUM_* — copie server/.env.example como ponto de partida.
As quatro chaves que importam para uma implantação básica: RELAYIUM_ADDR (endereço de escuta), RELAYIUM_STATIC (caminho para o aplicativo web compilado), RELAYIUM_DB (caminho do arquivo SQLite) e RELAYIUM_BLOB_DIR (onde o texto cifrado dos links armazenados é escrito). O docker-compose.yml já define valores padrão sensatos para as quatro e as persiste em um volume nomeado.

Adicione um retransmissor TURN para transferências entre redes

Transferências na mesma rede (rede local) e o push/pull baseado em SSH funcionam sem nada a mais. Transferências em tempo real entre redes (dois dispositivos atrás de NATs diferentes) às vezes precisam de um retransmissor TURN para estabelecer um caminho — o retransmissor só vê texto cifrado, nunca o conteúdo dos seus arquivos.

O docker-compose.yml tem um perfil relay opcional que inicia o coturn (o servidor TURN) e uma pequena instância Redis para a medição de bytes retransmitidos, ao lado do servidor principal:

O segredo precisa chegar a dois lugares diferentes, e errar isso falha em silêncio. O coturn o recebe pela substituição de variáveis do Compose, que só é resolvida a partir do shell ou de um .env na raiz do projeto. Já o servidor o lê do próprio ambiente — ou seja, de server/.env — e um segredo vazio desliga o TURN por completo. Se você definir só um dos dois, fica com um coturn rodando para o qual o servidor nunca emite credenciais: todos os contêineres se declaram saudáveis, nada é registrado, e as transferências através de NAT estrito continuam falhando exatamente como antes.

Gere um único segredo aleatório longo. É o mesmo valor em tudo abaixo.
```
openssl rand -hex 32
```
Coloque esse segredo, junto com os endereços de retransmissão para os quais seu domínio aponta, em server/.env: é isso que faz o servidor ativar o TURN.
```
RELAYIUM_TURN_SECRET=<the value from step 1>
RELAYIUM_TURN_URLS=turn:example.com:3478,turns:example.com:5349
```
Exporte esse mesmo arquivo para o shell, para que a substituição do Compose consiga entregar ao coturn um segredo idêntico. Dar source mantém uma fonte única e deixa o segredo fora da linha de comando, onde o ps o exporia.
```
set -a; . ./server/.env; set +a
```

Suba a pilha com o perfil relay.

docker compose --profile relay up -d --build

Abra as portas de retransmissão no firewall do host. O coturn roda com a rede do host, então são regras do host e não do Docker: UDP 3478 e 49152-65535, TCP 3478 e 5349.
Confirme que o servidor — e não apenas o coturn — subiu com o segredo. É essa checagem que pega o caso silencioso.
```
docker compose exec server env | grep RELAYIUM_TURN
```

Como é um retransmissor que funciona

As duas chaves voltam não vazias de dentro do contêiner do servidor. O coturn estar no ar não prova nada sozinho: o navegador só recebe credenciais de retransmissão emitidas pelo servidor.

$ docker compose exec server env | grep RELAYIUM_TURN
RELAYIUM_TURN_SECRET=3f7a…
RELAYIUM_TURN_URLS=turn:example.com:3478,turns:example.com:5349

O coturn precisa do IP público real do host e de uma faixa de portas UDP aberta para funcionar — docs/self-hosting.md cobre como executá-lo com o perfil relay do Docker; a configuração coturn de produção da própria Relayium (incluindo o script de instalação) não é publicada.
Sem --profile relay e RELAYIUM_TURN_SECRET, o servidor ainda funciona bem — as transferências entre redes apenas recorrem a só STUN, que funciona para os tipos de NAT mais fáceis, mas não para os mais rígidos.

Instale a CLI na sua máquina

Este último passo roda a CLI do relayium no seu próprio computador (não no servidor), então instale-a ali se ainda não tiver. No macOS ou Linux:

curl -fsSL https://relayium.com/install.sh | sh

relayium.com/cli lista todas as opções de instalação — um binário para Windows, a página de releases, ou go build se você tiver Go.
relayium --version confirma. Sem a CLI, o comando abaixo imprime “command not found”.

Aponte a CLI para o seu servidor

A CLI do Relayium usa por padrão o servidor de encontro do relayium.com para send/receive e text entre redes. Passe --server para usar o seu em vez dele:

Numa máquina que já tenha a CLI da seção anterior, entre no seu servidor em vez de no relayium.com. Ele imprime uma URL e um código; aprove no navegador com sessão iniciada na sua instância.
```
relayium login --server https://your-domain
```
Confirme a qual servidor as credenciais salvas estão vinculadas. whoami não aceita flags: ele relata o que o login de fato gravou, e é justamente isso que faz valer a pena rodá-lo.
```
relayium whoami
```
Passe o mesmo --server ao enviar. Sem ele, a CLI cunha o código de emparelhamento no relayium.com e o outro lado nunca vai encontrá-lo na sua instância.
```
relayium send ./report.pdf --server https://your-domain
```

Receba na outra máquina com o código impresso e o mesmo --server. As sessões de texto funcionam do mesmo jeito.

relayium receive 483920 --server https://your-domain

relayium text --server https://your-domain

relayium text 483920 --server https://your-domain

Como saber que ela está falando com a sua instância

whoami imprime a conta e, entre parênteses, o servidor a que ela está vinculada. Seu próprio domínio ali — e não relayium.com — é a confirmação.

$ relayium login --server https://your-domain
Open https://your-domain/device and enter code: WDJB-MJHT
logged in as you@example.com

$ relayium whoami
you@example.com (https://your-domain)

A CLI é gratuita em qualquer dos casos — --server apenas muda o servidor de encontro. send ou text sem código geram um código nele, e up guarda sob uma conta nesse servidor, então entre primeiro com relayium login --server https://your-domain. receive, down e text com o código impresso não precisam de login.
As duas pontas de text precisam permanecer online. As mensagens usam uma sessão P2P direta própria, criptografada de ponta a ponta. text na CLI é apenas direto e não usa o retransmissor TURN do app web. Nem o Relayium nem o servidor auto-hospedado armazenam o corpo das mensagens ou um histórico no servidor, mas qualquer terminal ou destinatário pode copiar ou guardar o texto depois de recebê-lo.
push/pull (pelo seu próprio SSH) e serve + o push daemon direto relayium://host não tocam o relayium.com em nada, com ou sem auto-hospedagem — eles se conectam diretamente ao remoto que você especificar.

Quando não funciona

Cinco falhas cobrem quase toda auto-hospedagem malsucedida. Cada uma tem uma linha para ler ou um comando para rodar que resolve a questão, e três das cinco parecem sucesso até você rodar a checagem.

Sintoma, checagem, correção

O docker compose up se recusa a iniciar, antes mesmo de construir qualquer coisa.

docker compose up -d --build
# required variable RELAYIUM_TURN_SECRET is missing a value

O Compose substitui as variáveis do arquivo inteiro antes de filtrar por perfis, então a variável exigida pelo serviço coturn desativado é validada mesmo com o retransmissor desligado. Prefixe qualquer valor de espaço reservado — RELAYIUM_TURN_SECRET=placeholder docker compose up -d --build — e troque por um segredo real só quando de fato ativar o perfil relay.

O contêiner está Up, mas um navegador em outra máquina não chega nele.

docker compose ps
# PORTS  127.0.0.1:8080->8080/tcp

Esse vínculo com o loopback é o padrão, para que um host público não exponha HTTP em claro na internet. Em produção, deixe assim e termine TLS num proxy reverso no mesmo host. Para uma máquina só de LAN sem proxy, publique de forma mais ampla com RELAYIUM_BIND=0.0.0.0 docker compose up -d: essa variável é lida pelo compose, não pelo servidor.

O /healthz diz ok, mas o cadastro falha e os links armazenados nunca aparecem.

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/readyz
# 503

O /healthz devolve ok incondicionalmente e só prova que o processo está escutando. O /readyz faz ping no banco SQLite e no diretório de blobs, então um 503 significa que um dos dois está inutilizável: verifique se o volume relayium-data está montado e se RELAYIUM_DB e RELAYIUM_BLOB_DIR apontam para dentro dele.

O relayium login imprime uma URL de verificação em localhost que você não consegue abrir.

relayium login --server https://your-domain
# Open http://localhost:8080/device and enter code: WDJB-MJHT

O servidor monta essa URL a partir de RELAYIUM_BASE_URL, cujo padrão é http://localhost:8080. Defina em server/.env o seu endereço https:// real e reinicie. Ela também decide se os cookies de sessão levam o atributo Secure, então deixá-la errada não é só questão de aparência.

O coturn está rodando, mas as transferências entre redes através de NAT estrito continuam falhando — e sem nada nos registros.

docker compose exec server env | grep RELAYIUM_TURN
# nenhuma saída

O segredo chegou ao coturn pela substituição do Compose, mas nunca chegou ao servidor, cujo segredo vazio desliga o TURN por completo. Coloque RELAYIUM_TURN_SECRET e RELAYIUM_TURN_URLS em server/.env, dê source com set -a; . ./server/.env; set +a para que a substituição enxergue o mesmo valor, e reinicie o perfil relay. As duas chaves precisam voltar não vazias nessa checagem.

Perguntas frequentes

Preciso configurar o TURN?

Só se você quiser que as transferências em tempo real entre redes funcionem através de NATs rígidos. Transferências na mesma rede, o push/pull baseado em SSH e o daemon direto funcionam todos sem ele — o TURN serve puramente para a travessia de NAT no caminho do código de emparelhamento entre redes.

A CLI continua gratuita se eu auto-hospedar?

Sim. A CLI continua gratuita com relayium.com ou com o seu servidor. send ou text sem código precisam de uma conta no servidor de destino para gerar um, e up precisa dela para guardar um arquivo. receive, down e text com o código impresso não exigem login.

Posso usar meu próprio domínio e certificado TLS?

Sim. A imagem Docker escuta em HTTP simples na :8080; coloque nginx ou Caddy na frente com seu próprio domínio e certificado (por exemplo, via certbot/Let's Encrypt). docs/self-hosting.md cobre o que precisa ser redirecionado; a configuração nginx de produção da própria Relayium não é publicada, então você vai escrever a sua.

Quais dados o meu servidor auto-hospedado armazena?

Um banco de dados SQLite (contas, sessões) em RELAYIUM_DB e, para transferências armazenadas/baseadas em link, blobs criptografados em RELAYIUM_BLOB_DIR que o próprio servidor não consegue descriptografar. O servidor não guarda arquivos em tempo real nem corpos de mensagens e apenas retransmite o handshake de sinalização; os destinatários ainda podem salvar arquivos ou reter texto.

Instale a CLI gratuita do Relayium e aponte-a para o seu próprio servidor com --server.

Obter a CLI