Guia da família: publicar apps no Coolify

Você publica um app em três passos: o código vai para o GitHub, o Coolify monta o app, e ele abre em https://seunome-app.apps.aguiar.net. Funciona com qualquer ferramenta de IA, porque o Coolify só precisa do repositório no GitHub.

Painel: https://coolify.aguiar.net

1. Primeiro acesso

1. Abra o link do e-mail de convite (começa com https://coolify.aguiar.net/...). Ele já entra no painel.
2. Troque a senha: clique no seu nome/perfil e defina uma senha sua.
3. Escolha o time certo. No canto superior esquerdo há um seletor de time. Use sempre Root Team, que é onde está o servidor. O time com o seu nome (ex.: lucas's Team) não tem servidor: projeto criado ali não publica.
4. Se ainda não tiver, crie uma conta gratuita em https://github.com. É lá que o código fica guardado.

Você entra como administrador do painel. Isso permite criar tudo sozinho, mas também dá acesso a telas que controlam o servidor inteiro. Leia a seção 7 antes de começar.

2. Leve seu código para o GitHub

Cada app é um repositório no GitHub. Como chegar lá depende da ferramenta que você usa:

Repositório público funciona direto. Para repositório privado, veja o passo 5.2.

3. Peça à sua IA para preparar o projeto

Antes de publicar, cole este pedido na ferramenta de IA que você usa. Ele deixa o projeto pronto para o Coolify:

Vou publicar este projeto no Coolify (deploy a partir do GitHub, atrás de um proxy que faz o HTTPS).
Prepare o projeto para isso:
1. Crie um Dockerfile na raiz que construa e rode o app em modo produção.
2. O app deve escutar em 0.0.0.0 (não em localhost), numa porta fixa. Me diga qual porta.
3. Nenhuma senha ou chave dentro do código: leia tudo de variáveis de ambiente
   e me dê a lista dessas variáveis com o que cada uma significa.
4. Se o app grava arquivos ou usa banco de dados, me diga quais pastas precisam
   de volume persistente e de qual banco ele precisa.
5. Crie um .dockerignore e confirme que o build funciona.
No fim, me diga: a porta, as variáveis de ambiente e as pastas persistentes.

Guarde as três respostas do fim (porta, variáveis, pastas). Você vai usá-las no próximo passo. Depois envie as mudanças para o GitHub de novo.

4. Como seu app vai se chamar

Todo app segue o padrão seunome-app: o mesmo nome vale para o projeto no Coolify, para o repositório no GitHub e para o endereço, que fica https://seunome-app.apps.aguiar.net.

• Use só letras minúsculas, números e hífen. Nada de acento, espaço, _ ou ponto: o servidor recusa o HTTPS de nomes fora desse formato.
• O nome vem sempre antes de .apps.aguiar.net, num nível só. lucas-blog.apps.aguiar.net funciona; blog.lucas.apps.aguiar.net não.
• Comece pelo seu nome. Assim ninguém pega o endereço do outro e todos sabem de quem é cada app.
• Para uma versão de teste, acrescente -teste no fim: lucas-blog-teste.
• Banco de dados e outros serviços do app levam o mesmo prefixo: lucas-blog-db.
• Escolha o nome com calma. Cada endereço novo gera um certificado na primeira visita (leva alguns segundos), e há um teto de cerca de 50 certificados novos por semana para todo o domínio aguiar.net.
• Domínio próprio (como meusite.com.br) não funciona sozinho: peça ao Marcos, que configura o servidor e o DNS.

5. Publique no Coolify

5.1 Criar o app

1. Confira que o time selecionado é Root Team.
2. Projects → + Add. Dê um nome começando com o seu (ex.: lucas-blog).
3. Entre no projeto → ambiente production → + New.
4. Escolha a origem: - Public Repository: cole o endereço do repositório (https://github.com/voce/seu-app). - Private Repository (with GitHub App): para repositório privado (veja 5.2).
5. Em Server, escolha localhost.
6. Build Pack: escolha Dockerfile (o que a IA criou no passo 3).
7. Ports Exposes: a porta que a IA informou (ex.: 3000).

8. Domains: escreva com http://, não https://:

   http://lucas-blog.apps.aguiar.net

O HTTPS é feito pelo servidor; o site abrirá em https://lucas-blog.apps.aguiar.net. Use um único nome antes de .apps (nada de a.b.apps.aguiar.net). 9. Environment Variables: cadastre as variáveis que a IA listou (senhas e chaves ficam aqui). 10. Resources (limites, obrigatório): CPU limit 1 e Memory limit de modo que a soma dos seus apps não passe de 3g. 11. Clique em Deploy e acompanhe o log. Quando terminar, abra o endereço do passo 8.

5.2 Repositório privado e publicação automática

Faça uma vez só, para ligar a sua conta do GitHub ao Coolify:

1. No Root Team: Sources → + Add → GitHub App.
2. Dê um nome com o seu (ex.: github-lucas), desmarque "Pull request previews" e clique em Continue.
3. O GitHub abre (entre com a sua conta): confirme a criação do app.
4. De volta ao Coolify, clique em Install e escolha Only select repositories, marcando só os repositórios que você quer publicar. Para incluir outro depois, repita o Install ou ajuste a lista nas configurações da App no GitHub.

Ao criar o app (5.1), escolha Private Repository (with GitHub App) e a sua fonte, nunca a de outra pessoa. Com isso, cada vez que você (ou sua IA) enviar mudanças para o GitHub, o Coolify publica a nova versão sozinho. Com repositório público sem GitHub App, clique em Redeploy no app para atualizar.

5.3 Banco de dados

Se o app precisa de banco: no mesmo projeto, + New → Databases (PostgreSQL, MySQL etc.). O Coolify mostra o endereço interno de conexão; copie para a variável de ambiente do app. Ative Backups no banco.

6. Limites

Cada pessoa tem 1 CPU e 3 GB de memória, somando todos os seus apps. O servidor tem 4 CPUs, 16 GB de memória e 199 GB de disco, divididos entre a família e os sistemas de produção do Marcos.

• Preencha CPU limit e Memory limit em todo app, na aba Resources. Campo vazio ou 0 significa sem limite.
• Divida os 3 GB entre seus apps. Um site simples roda com 256m a 512m; três apps de 1g já usam tudo.
• App que passa do próprio limite de memória é reiniciado sozinho. Se isso acontecer, veja os Logs antes de aumentar o limite.
• O servidor não tem placa de vídeo. Não cabem aqui modelos de IA rodando localmente, mineração ou conversão pesada de vídeo.
• Precisa de mais do que isso para um projeto? Combine com o Marcos antes.

7. Privacidade, backup e bom uso

Tudo o que você publica fica aberto na internet: qualquer pessoa com o endereço acessa.

• Privacidade: se o app tem dados pessoais ou de terceiros, ele precisa de login. Peça isso à sua IA antes de publicar.
• Senhas e chaves: vão em Environment Variables, nunca dentro do código nem no GitHub. Chave que vazou no GitHub deve ser trocada.
• Backup: o servidor copia os dados dos apps toda madrugada, mas trate isso como rede de segurança. O código fica no GitHub, dados ficam em volumes (Storages) e banco de dados fica com Backups ligado.
• Apagar é definitivo: excluir um app, banco ou volume no painel remove os dados na hora. Na dúvida, pare o app (Stop) em vez de excluir.
• Limpeza: app de teste que você não usa mais deve ser parado ou excluído, para liberar memória e disco.
• Só os seus projetos: o painel mostra os de todos, mas cada um cuida dos seus. Não altere projetos, fontes (Sources) nem chaves de outra pessoa.
• Telas proibidas: você é administrador, então o painel deixa entrar em tudo. Não entre em Servers, Settings nem Teams, e não mexa no proxy. A tela Servers → localhost → Resources lista os sistemas de produção do Marcos com botões de parar e reiniciar: nunca clique neles.
• Sem acesso ao servidor: não use privileged e não monte pastas do servidor (/, /etc, /var/run/docker.sock). Se sua IA sugerir isso, recuse.
• Custo: nenhum para você. A conta gratuita do GitHub basta.
• Dúvida ou algo estranho: fale com o Marcos antes de apagar qualquer coisa.

8. Se algo der errado