Atualização

Uma atualização move uma instância para uma versão mais recente. install.sh --update faz tudo: backup, baixa os novos arquivos de stack, baixa as novas imagens, recria os contêineres que mudaram. Os arquivos de stack são os arquivos do compose, o Caddyfile e .env.example. Reserve cerca de vinte minutos, a maior parte para o backup e o pull.

Requisito	Valor
Diretório de trabalho	O que contém .env, docker-compose.yml, docker-compose.proxy.yml, tunnel.compose.yml e Caddyfile
Comandos do Compose	Atrás do seu próprio proxy reverso, defina COMPOSE_FILE em .env uma vez e todos os comandos pegarão a sobreposição
Disco livre	Espaço para um dump de banco de dados, uma cópia dos uploads e as novas imagens ao lado das antigas
Tempo de inatividade	Um ou dois minutos para recriar, mais o tempo que a cópia dos uploads levar com a stack parada

Leia as notas de lançamento entre a versão que você executa e a qual você está mudando, em Releases.

Corresponder as imagens aos arquivos de stack

As imagens vêm de FLUXER_IMAGE_TAG no .env. Os arquivos de stack vêm de um ref do git, que é um branch ou uma tag no repositório do Decoding Chat. O instalador deriva esse ref a partir da tag da imagem: main para v1 ou latest, e a própria string da tag para qualquer outra coisa. --ref substitui a derivação. docker compose pull nunca atualiza um arquivo de stack, e atualizar um arquivo de stack nunca move uma imagem.

O repositório não contém nenhum ref com o nome de uma tag de imagem fixada. Um lançamento marca cada imagem por conta própria, como fluxer-api@2026.813.205040, então passe --ref com essa tag ou com o commit para o qual ela aponta. Sem essa substituição, o download falha com a saída 4.

O que o script faz

--update executa estas etapas nesta ordem e para na primeira que falhar:

Etapa	O que faz
Mint	Escreve qualquer chave que a stack atualizada exija e que não esteja no .env, listadas em Executar a atualização
Record	Escreve as referências das imagens, o ID de imagem que cada contêiner possui e a tag que o .env nomeia, em um novo diretório de registro
Save	Copia .env e os arquivos da stack para esse registro
Dump	Faz o dump do banco de dados com a stack ainda em serviço e verifica o cabeçalho de formato personalizado no resultado
Copy	Para a stack, copia o volume de uploads e a inicia novamente nas imagens que já estava executando
Fetch	Baixa os arquivos da stack no ref para um diretório de preparação dentro do diretório de trabalho
Guard	Recusa quando o docker-compose.yml atualizado move o Postgres para uma nova versão principal
Place	Move todos os arquivos baixados para o diretório de trabalho de uma só vez
Pull	Baixa (pull) as imagens enquanto os contêineres antigos ainda estão servindo
Recreate	Executa docker compose up -d --remove-orphans, e então reinicia o edge quando o Caddyfile for alterado
Verify	Consulta o estado do Compose até que todos os serviços estejam prontos, depois testa /_health no nome de host

Uma execução falha deixa a instância rodando nas imagens que ela já tinha.

docker compose up -d não percebe um Caddyfile alterado. O script reinicia o edge pelo nome para capturá-lo.

Uma instância configurada antes do edge servir o LiveKit em /livekit precisa de uma edição que a atualização não faz. Até você fazer isso, a voz não conecta. A sinalização de voz mudou para /livekit tem a edição.

O docker-compose.yml atualizado renomeia o serviço caddy para edge, e os dois publicam as mesmas portas de host. --remove-orphans desliga o contêiner antigo na mesma chamada, para que o novo possa vinculá-las. Sem isso, a etapa para com Bind for 0.0.0.0:443 failed. Ele também remove qualquer contêiner no projeto cujo serviço não seja mais definido pelos arquivos do Compose carregados, então mantenha o COMPOSE_FILE igual durante uma atualização. Manter uma alteração local do compose tem o layout de arquivo que sobrevive a isso. Quando a lista de arquivos do compose nomeia um arquivo ausente tem o erro que o Compose imprime quando o COMPOSE_FILE nomeia um arquivo que não existe.

A renomeação também move os volumes caddy-data e caddy-config para edge-data e edge-config, então os dois antigos ficam sem uso e o edge solicita seu certificado novamente na primeira inicialização.

As atualizações alteram FLUXER_IMAGE_TAG e adicionam segredos obrigatórios ausentes. Os valores existentes são preservados, exceto pelo espaço reservado inutilizável do upload-relay descrito abaixo.

A stack atualizada requer FLUXER_ERLANG_COOKIE. --update gera um valor ausente como 64 caracteres hexadecimais. Sem ele, os comandos do Compose falham com set FLUXER_ERLANG_COOKIE in .env.

Para escrevê-lo manualmente, execute o gerador em um shell:

printf '\nFLUXER_ERLANG_COOKIE=%s\n' "$(openssl rand -hex 32)" >> .env

Não cole FLUXER_ERLANG_COOKIE=$(openssl rand -hex 32) no .env. O Compose não executa comandos shell nesse arquivo.

api e media-proxy exigem que FLUXER_MEDIA_PROXY_UPLOAD_RELAY_SECRET_BASE64 seja decodificado para pelo menos 32 bytes. --update substitui um valor ausente ou CHANGE_ME por um segredo gerado. Ambos os serviços devem usar o mesmo valor.

Para escrevê-lo manualmente, execute o gerador em um shell da mesma maneira:

printf '\nFLUXER_MEDIA_PROXY_UPLOAD_RELAY_SECRET_BASE64=%s\n' "$(openssl rand -base64 32)" >> .env

O script é a referência

Leia o Instalador para Linux e macOS ou o Instalador para Windows antes de executá-lo.

Manter uma alteração local do compose

Uma atualização substitui os arquivos da stack, incluindo edições diretas em docker-compose.yml, docker-compose.proxy.yml, tunnel.compose.yml ou no Caddyfile. Use --dry-run para ver quais arquivos serão alterados.

A forma suportada de manter uma escolha local é um arquivo separado, listado no COMPOSE_FILE no .env:

COMPOSE_FILE=docker-compose.yml:docker-compose.proxy.yml:local.compose.yml

O Compose mescla os arquivos da esquerda para a direita, portanto, local.compose.yml prevalece sobre os anteriores. Uma atualização renova os arquivos da stack e nada mais, então um arquivo fora desse conjunto sobrevive a qualquer atualização intocado. Um registro copia .env e esses arquivos, e nenhum outro arquivo do diretório de trabalho. Um arquivo de substituição nunca tem o backup feito com eles, então mantenha-o onde quer que o resto da configuração viva.

Mantenha as configurações de ambiente no .env. As atualizações as preservam, com exceção das alterações na tag e nos segredos obrigatórios descritas acima.

Ativar a sobreposição tem a sobreposição para a qual isso é mais frequentemente usado. Rótulos do Docker tem um terceiro arquivo trabalhado.

Quando a lista de arquivos do compose nomeia um arquivo ausente

COMPOSE_FILE nomeia os arquivos em relação ao diretório de trabalho, e o Compose se recusa a carregar o conjunto quando um deles está ausente:

stat /srv/fluxer/docker-compose.proxy.yml: no such file or directory

Cada comando docker compose para por aí. Isso pode afetar instalações mais antigas cujo .env nomeia uma sobreposição que não foi baixada. O instalador relata o arquivo ausente e um comando para restaurá-lo.

Baixe o arquivo ausente no ref para o qual a atualização se move e, em seguida, execute a atualização:

curl -fsSL --proto '=https' --tlsv1.2 -o docker-compose.proxy.yml \
  https://raw.githubusercontent.com/fluxerapp/fluxer/main/deploy/self-hosting/docker-compose.proxy.yml

main é o ref para FLUXER_IMAGE_TAG=v1 e para latest. Corresponder as imagens aos arquivos de stack tem o ref que uma tag fixada precisa.

Remover a linha do .env também permite que a atualização seja executada, e essa é a correção incorreta. Sem a sobreposição, o edge publica as portas de host 80 e 443, que o proxy reverso que já está no host utiliza.

Executar a atualização

Mantenha o instalador ao lado dos arquivos da stack. Começar tem o download e a verificação de checksum para uma cópia nova.

Veja o plano primeiro:

cd ~/fluxer
sh install.sh --update --dry-run

Ele imprime:

• As imagens que a stack executa agora
• O backup que pretende fazer
• Os arquivos da stack que o ref altera
• Os serviços que essas alterações farão reiniciar
• Qualquer recusa que interromperia a execução

Ele não grava nada fora de um diretório temporário que remove ao sair.

Em seguida, execute-o:

sh install.sh --update

No Windows:

.\install.ps1 -Update

A execução termina nomeando o registro que gravou e o comando que reverte para ele. Ele verifica seu próprio trabalho com a pesquisa de prontidão e um teste de /_health. Execute os testes públicos em Verificar se funciona depois.

Flag	Windows	Significado
--update	-Update	Registrar, fazer backup, atualizar, baixar (pull), recriar, verificar
--rollback	-Rollback	Colocar de volta as imagens e arquivos de stack do registro mais recente
--dry-run	-DryRun	Imprimir o plano. Não altera nada
--backup-dir <path>	-BackupDir	Para onde vão os registros. O padrão é <dir>/backups
--no-volume-backup	-NoVolumeBackup	Faz o dump do banco de dados e pula a cópia dos uploads
--skip-backup-accept-data-loss	-SkipBackupAcceptDataLoss	Atualiza sem nenhum backup

--dir e --ref significam o que significam em uma instalação, e o instalador deriva um --ref omitido da linha FLUXER_IMAGE_TAG no .env. Cada falha imprime uma frase no erro padrão e sai com código diferente de zero, e o cabeçalho do script lista o que cada código significa. Uma mudança na versão principal do Postgres é a saída 3.

A sinalização de voz mudou para /livekit

O edge atende o LiveKit em /livekit/*. Uma instância configurada antes desse roteamento o atendia em /gateway/livekit, e esse caminho desapareceu. A voz para de se conectar após a atualização e a execução ainda relata sucesso, porque a pesquisa de prontidão e o teste /_health nunca chegam à voz.

Antes:

wss://chat.example.com/gateway/livekit

Depois:

wss://chat.example.com/livekit

Tanto https quanto wss funcionam. Atualize FLUXER_LIVEKIT_URL no .env para o novo caminho, ou remova-o para usar o endereço derivado e, em seguida, execute docker compose up -d api.

Quando a api inicia, ela grava o novo endereço no servidor default-server-1 existente na região default. Para qualquer outro servidor, altere Endpoint em Voice Servers no painel de administração. Corrija o .env primeiro, ou uma reinicialização posterior poderá restaurar o endereço antigo no servidor padrão.

A mídia de voz não é afetada. Ela nunca passou pelo edge e as portas 7881/tcp e 7882/udp ainda chegam diretamente ao host.

O que o backup abrange

Cada atualização escreve um diretório de registro, nomeado record- e um carimbo UTC, em backups ou onde quer que --backup-dir aponte. Ele contém:

Artefato	O que abrange
fluxer.dump	Cada conta, mensagem, guilda e linha de configuração, no formato personalizado do Postgres
seaweedfs-data.tgz	Cada upload, avatar, relatório e coleta
.env	Todos os segredos com os quais a instância foi construída

Os arquivos da stack ficam no registro ao lado deles, portanto, uma reversão coloca de volta os arquivos exatos que a instância estava executando. O diretório de registro é criado como 0700 e a cópia do .env dentro dele é 0600. Mantenha os registros onde você já mantém os segredos.

Nada mais é copiado. O dump cobre postgres-data. Os outros volumes reconstroem-se sozinhos ou guardam trabalhos em fila, e Volumes e buckets os lista todos com o que cada um contém.

Coloque um dump em um cronômetro também. No Linux e no macOS, esta linha do crontab escreve um a cada noite e mantém duas semanas deles:

15 3 * * * cd /srv/fluxer && docker compose exec -T postgres pg_dump -U fluxer -d fluxer --format=custom > "backups/fluxer-$(date -u +\%Y\%m\%dT\%H\%M\%SZ).dump" && find backups -name 'fluxer-*.dump' -mtime +14 -delete

/srv/fluxer significa o diretório contendo .env. Escreva-o como um caminho absoluto, pois o cron não expande ~. Um % sem escape em um crontab é uma nova linha, e é por isso que cada um acima tem uma barra invertida.

Executar um armazenamento de dados fora da stack

A stack envia seu próprio Postgres e seu próprio armazenamento de objetos e aponta para ambos pelo nome do serviço. .env move qualquer um deles para outro lugar, e o serviço embutido é usado quando a linha está ausente:

FLUXER_POSTGRES_HOST=db.example.com
FLUXER_POSTGRES_PORT=5432
FLUXER_POSTGRES_SSL=true
FLUXER_S3_ENDPOINT=https://s3.eu-central-1.amazonaws.com
FLUXER_S3_REGION=eu-central-1
FLUXER_S3_FORCE_PATH_STYLE=false

FLUXER_S3_PUBLIC_ENDPOINT segue FLUXER_S3_ENDPOINT quando não é definido por conta própria, e as credenciais permanecem FLUXER_S3_ACCESS_KEY e FLUXER_S3_SECRET_KEY. FLUXER_S3_BUCKET_CDN, FLUXER_S3_BUCKET_UPLOADS, FLUXER_S3_BUCKET_DOWNLOADS, FLUXER_S3_BUCKET_REPORTS e FLUXER_S3_BUCKET_HARVESTS nomeiam os buckets. O armazenamento de objetos embutido cria os nomes que eles contêm, e um armazenamento fora da stack precisa que esses buckets já existam.

FLUXER_KV_URL, FLUXER_NATS_URL, FLUXER_SEARCH_URL e FLUXER_LIVEKIT_INTERNAL_URL movem os outros serviços embutidos da mesma maneira, e FLUXER_NATS_JETSTREAM_URL e FLUXER_SVC_NATS_URL seguem FLUXER_NATS_URL quando não são definidos por conta própria.

Apontar a stack para outro lugar deixa o serviço embutido definido e em execução com nada o lendo. Remova-o com um arquivo de substituição listado em COMPOSE_FILE, que Manter uma alteração local do compose descreve, em vez de editar docker-compose.yml, que a etapa Place substitui em cada atualização.

O instalador faz backup apenas do banco de dados embutido e do armazenamento de objetos embutido. Providencie backups separados para armazenamentos externos antes de atualizar e guarde-os com o registro de backup do lançamento.

Reverter

Uma reversão coloca o lançamento anterior de volta:

cd ~/fluxer
sh install.sh --rollback

No Windows é .\install.ps1 -Rollback. Ele pega o registro mais recente, coloca de volta as imagens e os arquivos da stack que ele contém, recria, reinicia o edge e verifica. --dry-run também imprime esse plano.

Uma reversão nunca faz pull, então ela precisa das imagens antigas ainda no host. Execute Recuperar disco somente depois que a atualização for confirmada como boa.

Uma reversão não desfaz as migrações do banco de dados nem restaura os dados. Se o lançamento anterior exigir o esquema antigo, restaure o backup do banco de dados separadamente.

Restaurar um backup

Restaure ambos os artefatos com a stack parada, para que nada escreva enquanto eles são substituídos. Dê o nome do seu próprio diretório de registro em vez daquele abaixo.

O banco de dados é restaurado do dump de formato personalizado:

docker compose stop
docker compose up -d --wait postgres
docker compose exec -T postgres pg_restore -U fluxer -d fluxer --clean --if-exists \
  < backups/record-20260831T120000Z/fluxer.dump
docker compose up -d

--clean imprime avisos sobre objetos que ainda não existem, o que é esperado em um diretório novo.

O PowerShell não tem o redirecionamento <. No Windows, copie o dump para o contêiner e nomeie-o como um arquivo:

docker compose stop
docker compose up -d --wait postgres
docker compose cp backups\record-20260831T120000Z\fluxer.dump postgres:/tmp/fluxer.dump
docker compose exec -T postgres pg_restore -U fluxer -d fluxer --clean --if-exists /tmp/fluxer.dump
docker compose exec -T postgres rm /tmp/fluxer.dump
docker compose up -d

Os uploads são restaurados por meio do mesmo contêiner auxiliar que o backup usou, no sentido inverso:

docker compose stop
docker run --rm -v fluxer_seaweedfs-data:/data \
  -v "$PWD/backups/record-20260831T120000Z:/backup" alpine:3.22 \
  sh -c 'find /data -mindepth 1 -delete && tar xzf /backup/seaweedfs-data.tgz -C /data'
docker compose up -d

O tar extrai por cima do que quer que já esteja no volume, então o find o esvazia primeiro. No PowerShell, escreva ${PWD} em vez de $PWD. O sucesso é uma URL de anexo existente respondendo a 200 novamente. O prefixo fluxer_ é o nome do projeto do Compose, que docker-compose.yml define como fluxer.

Mudar para uma nova versão principal do Postgres

O docker-compose.yml fixa postgres:16-alpine. Uma versão principal mais recente não lê o diretório de dados que uma versão principal mais antiga gravou, então os dados são movidos através de um dump. A atualização recusa quando o arquivo do compose atualizado altera essa fixação, porque a movimentação destrói o volume que contém o banco de dados.

Faça o dump enquanto a versão principal antiga ainda estiver atendendo, então pare tudo e remova o volume:

docker compose exec -T postgres pg_dump -U fluxer -d fluxer --format=custom \
  > backups/pre-major.dump
docker compose down
docker volume rm fluxer_postgres-data

No Windows, execute pg_dump dentro do contêiner com -f /tmp/pre-major.dump e copie o arquivo para fora com docker compose cp. Restaure-o com docker compose cp e pg_restore como mostra Restaurar um backup.

Uma vez que esse volume for removido, o dump é a única cópia do banco de dados.

Coloque a nova tag do postgres no docker-compose.yml, inicie o banco de dados por conta própria e restaure no diretório vazio:

docker compose up -d --wait postgres
docker compose exec -T postgres pg_restore -U fluxer -d fluxer --clean --if-exists \
  < backups/pre-major.dump
docker compose up -d

Execute sh install.sh --update depois para finalizar a mudança nos arquivos atualizados.

Fixar um lançamento

FLUXER_IMAGE_TAG=v1 rastreia o lançamento compatível mais recente, de modo que cada atualização pode mover a instância. Defina-o para uma tag de lançamento para manter uma versão e atualizar no seu próprio cronograma.

Uma instância fixada também fixa seus arquivos de stack. Corresponder as imagens aos arquivos de stack tem o --ref que uma tag fixada precisa.

A tag se aplica apenas às imagens do Decoding Chat. caddy, postgres, valkey, nats, meilisearch, seaweedfs e livekit são fixados no docker-compose.yml e se movem apenas quando uma atualização atualiza esse arquivo.

Alterar o domínio ou a parte confiável da passkey

FLUXER_DOMAIN fornece o FLUXER_PASSKEY_RP_ID padrão, que é o domínio ao qual uma passkey está vinculada. Uma passkey só funciona com o identificador com o qual foi criada.

Alterar qualquer valor invalida todas as passkeys

As passkeys registradas sob o antigo FLUXER_PASSKEY_RP_ID param de funcionar e não podem ser recuperadas. Todo usuário deve registrar uma nova, então mantenha outro método de login funcionando antes de alterá-lo.

Alterar FLUXER_DOMAIN também altera o certificado que o edge solicita, as origens CORS que a API aceita e a URI de redirecionamento do OAuth do administrador.

Recuperar disco

Cada atualização deixa para trás as imagens anteriores, o que se acumula em alguns gigabytes com o tempo:

docker image prune -f

Na tag móvel padrão, o pull move a v1 para as novas imagens e deixa as que substituiu sem tag, e isso as remove. Uma reversão em uma tag móvel precisa dessas imagens. Faça a limpeza somente quando a atualização for confirmada como boa. Um lançamento fixado mantém sua própria tag e sobrevive à limpeza. Remova uma delas nomeando sua tag em docker image rm.

docker system prune -a recupera mais. Também exclui todas as imagens que nenhum contêiner referencia, incluindo as que não estão relacionadas ao Decoding Chat.

Nunca adicione -a a uma limpeza de volume

docker volume prune -a remove os volumes nomeados que nenhum contêiner utiliza. Depois de um docker compose down, isso é cada volume que a instância possui, que é toda a instância.