Como fazer self-host do ConvertX em 2026: uploads, segredos JWT e limites de recursos

Há duas versões de “executar o ConvertX”: existe um container ou o serviço conclui sua tarefa de verdade. Apenas a segunda importa. Aqui, a comprovação consiste em fazer upload de vários formatos representativos, converter cada um, baixar os resultados e comparar hashes ou propriedades de mídia quando forem determinísticos.

O ConvertX serve a esse propósito: é um serviço de conversão de arquivos baseado no navegador. O deployment precisa preservar os componentes por trás desse comportamento; uma porta, um volume e um certificado são requisitos de entrada, não o resultado.

Escolha a menor topologia viável para o ConvertX

Comece pelo namespace de rede do ConvertX: o listener web usa a porta 3000, não uma porta do host copiada de um tutorial para laptop. O requisito do runtime local é ter CPU, memória e disco temporário adequados aos conversores selecionados. Documente a capacidade esperada, a propriedade e o modo de falha em vez de deixar essas definições como padrões da imagem.

Depois que o requisito for atendido, execute o cenário completo — faça upload de vários formatos representativos, converta cada um, baixe os resultados e compare hashes ou propriedades de mídia quando forem determinísticos. Registre logs e métricas de CPU, memória, disco temporário, tamanho dos arquivos e dos binários de conversão chamados por cada par de formatos. Essas evidências se tornam a primeira arquitetura conhecida como funcional e permitem testar migrações posteriores entre o compute da Dockup e um servidor conectado.

Mantenha as URLs internas e externas bem definidas

Evite usar origins públicas temporárias e permanentes para o ConvertX. Em vez disso, publique a UI via HTTPS com limites de upload definidos de forma deliberada, aponte o nome DNS escolhido para a rota da plataforma e faça proxy apenas para a porta 3000.

Execute esta ação de fora do host: faça upload de vários formatos representativos, converta cada um, baixe os resultados e compare hashes ou propriedades de mídia quando forem determinísticos. Se o ingresso falhar, o guia de troubleshooting de 502 aborda erros de porta e listener. Se o ConvertX receber a solicitação, mas um binário de conversão estiver ausente ou o proxy rejeitar um upload grande, as evidências agora apontam para além do proxy.

Configurações do container que vale a pena revisar

Inicie o ConvertX de modo que a rota permaneça privada até a conclusão do bootstrap.

docker run -d \
  --name convertx \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -v convertx-data:/app/data \
  -e JWT_SECRET=replace-with-a-long-random-value \
  ghcr.io/c4illin/convertx:latest

Se o processo entrar em loop, compare o usuário esperado pela imagem com o proprietário de cada caminho montado. Se continuar em execução, teste a porta 3000 localmente e passe diretamente ao workflow: faça upload de vários formatos representativos, converta cada um, baixe os resultados e compare hashes ou propriedades de mídia quando forem determinísticos. Fixe a versão da imagem somente depois que essa verificação end-to-end passar e registre a configuração exata junto ao serviço.

Faça um ensaio da alteração arriscada no ConvertX

Um health check ocioso diz pouco sobre o ConvertX. Monitore CPU, memória, disco temporário, tamanho dos arquivos e os binários de conversão chamados por cada par de formatos. Em seguida, gere alertas para o sintoma percebido pelos usuários: falha na ação “fazer upload de vários formatos representativos, converter cada um, baixar os resultados e comparar hashes ou propriedades de mídia quando forem determinísticos”. Mantenha o liveness local e barato; faça o readiness informar migrações ou inicialização sem provocar uma tempestade de restarts.

A área de risco do upgrade é que as releases da imagem podem adicionar ou remover conversores. Por isso, teste a matriz exata de formatos da qual os usuários dependem. Leia as release notes, faça um snapshot do estado, faça o deploy da versão-alvo sobre uma cópia restaurada e repita a ação de aceitação. Se um binário de conversão estiver ausente ou o proxy rejeitar um upload grande, correlacione a solicitação do cliente com o primeiro log relevante da aplicação, em vez de apagar o estado ou adicionar redirects às cegas.

Cinco verificações mais fortes que a saúde do container

Não use o tráfego do primeiro usuário como teste de aceitação do ConvertX. Prepare um estado de exemplo inofensivo e execute a ação completa: “fazer upload de vários formatos representativos, converter cada um, baixar os resultados e comparar hashes ou propriedades de mídia quando forem determinísticos”. Anote a URL pública exata, o resultado, a referência da imagem e o intervalo de logs associado à execução.

Substitua o container e repita o processo sem recriar os dados. Depois, faça a recuperação em um host vazio; a condição de recuperação é que as contas e configurações retornem e que a matriz fixa de formatos continue sendo concluída dentro dos limites escolhidos. Observe CPU, memória, disco temporário, tamanho dos arquivos e os binários de conversão chamados por cada par de formatos em todas as execuções e defina um alerta para a degradação da transação, não para métricas de um container ocioso.

Uma verificação final deve falhar de propósito: envie uma entrada inofensiva próxima do limite de recursos ou formatos associado a esta fronteira: um binário de conversão está ausente ou o proxy rejeita um upload grande. Verifique se a mensagem resultante do ConvertX identifica a fronteira relevante, em vez de disparar a exclusão de dados ou um restart interminável. Restaure a condição válida e confirme que a mesma transação de exemplo é concluída com sucesso. Mantenha este exercício curto no checklist de release.

Encontre todos os bytes persistentes do ConvertX

O conjunto necessário para uma recuperação durável inclui os dados da aplicação, as contas e quaisquer configurações de conversão mantidas. Monte /app/data antes do bootstrap, grave dados de exemplo inofensivos e substitua o container para provar que esse caminho é realmente persistente. Um volume protege os dados contra a substituição do container, mas não contra a perda do host, a exclusão acidental ou a corrupção no nível da aplicação.

Faça backups que entendam a fonte dos dados: use dumps lógicos para bancos de dados ativos quando necessário e copie arquivos somente a partir de um estado consistente. Mantenha uma cópia criptografada fora do host do ConvertX. O critério de aceitação de uma restauração é específico: as contas e configurações retornam e a matriz fixa de formatos continua sendo concluída dentro dos limites escolhidos. O guia de backup testado com restauração explica por que o sucesso do job, por si só, não é suficiente.

Reduza as permissões do ConvertX

Depois do primeiro login, revise o que um visitante anônimo, um usuário comum e um administrador podem fazer. O problema do ConvertX a evitar é usar um segredo JWT de exemplo ou oferecer conversões públicas irrestritas. A política pretendida é usar um segredo JWT real, exigir login e limitar os uploads antes de aceitar arquivos não confiáveis da internet.

Gere o JWT_SECRET como um valor longo e aleatório; a rotação normalmente invalida sessões ou tokens, portanto planeje o impacto para os usuários em vez de tratá-la como uma migração de criptografia. Mantenha as contas de dependências separadas das contas humanas, negue o egress não utilizado quando for viável e limite o trabalho influenciado por CPU, memória, disco temporário, tamanho dos arquivos e pelos binários de conversão chamados por cada par de formatos.

Faça o deploy do ConvertX na Dockup sem perder seus limites

A Dockup elimina o trabalho manual de reverse proxy e gerenciamento do lifecycle em torno do ConvertX. O serviço recebe uma rota HTTPS estável para a porta 3000, configuração injetada e armazenamento persistente durante as substituições. Um servidor do cliente conectado segue o mesmo modelo do compute hospedado na Dockup.

Depois do lançamento, atenda ao contrato da aplicação: publique a UI via HTTPS com limites de upload definidos de forma deliberada, confirme o requisito local — CPU, memória e disco temporário adequados aos conversores selecionados — e execute esta comprovação: faça upload de vários formatos representativos, converta cada um, baixe os resultados e compare hashes ou propriedades de mídia quando forem determinísticos. Isso mantém a experiência de um clique útil sem eliminar os detalhes que tornam o ConvertX recuperável e seguro.

Perguntas frequentes

O que o ConvertX precisa para um deployment de produção?

Encaminhe o container do ConvertX na porta 3000 por meio de uma única origin HTTPS. O requisito do runtime local é ter CPU, memória e disco temporário adequados aos conversores selecionados. Não considere o ConvertX pronto até conseguir fazer upload de vários formatos representativos, converter cada um, baixar os resultados e comparar hashes ou propriedades de mídia quando forem determinísticos.

Quais dados do ConvertX devem fazer parte de um backup?

Persista /app/data e inclua os dados da aplicação, as contas e quaisquer configurações de conversão mantidas no mesmo manifesto de recuperação. Uma restauração limpa do ConvertX só é considerada bem-sucedida quando as contas e configurações retornam e a matriz fixa de formatos continua sendo concluída dentro dos limites escolhidos.

O ConvertX exige HTTPS atrás de um reverse proxy?

Use HTTPS para a origin pública do ConvertX e mantenha a porta 3000 na rota interna. Aplique corretamente a configuração do ConvertX: publique a UI via HTTPS com limites de upload definidos de forma deliberada. No ConvertX, o HTTPS protege credenciais ou conteúdo dos usuários durante o trânsito e mantém consistente o comportamento do cliente sensível à origin.

Como testar um upgrade do ConvertX?

Restaure o estado atual do ConvertX em um deployment isolado, aplique a versão candidata e repita sua transação de aceitação. Preste atenção especial ao fato de que as releases da imagem podem adicionar ou remover conversores, portanto teste a matriz exata de formatos da qual os usuários dependem. Mantenha a imagem anterior do ConvertX até entender os limites de migração de dados e rollback.