Configuração de Sites

Depois de criar um site, você o ajusta e opera pelas sub-páginas da sua página de detalhe, agrupadas por assunto. Esta página cobre o editor de Ambiente (.env), as páginas Geral, Domínios e SSL, Runtime e Serviços, os ajustes de deploy, a Página de manutenção, a governança das versões de runtime disponíveis, e as páginas Comandos, Logs, Heartbeats e Atividade.

Onde está cada coisa:

#Ambiente

O editor de Ambiente deixa você gerenciar o arquivo .env do site diretamente pelo painel, sem SSH. Ele existe para todos os tipos de site, exceto HTML Estático.

#Editar variáveis

1. Abra a página Ambiente do site.
2. Edite as variáveis individualmente, use Adicionar Variável para criar uma nova com chave e valor, ou Editar Raw para editar o arquivo inteiro de uma vez. A busca filtra as variáveis pelo nome.
3. Clique em Salvar & Aplicar. As mudanças são escritas no servidor imediatamente.

Para proteger dados sensíveis, os valores de segredos (senhas, chaves de API, APP_KEY, credenciais de banco) aparecem mascarados por padrão. O botão Mostrar Segredos revela os valores quando você precisa conferi-los, e Ocultar Segredos os esconde de novo — assim ninguém vê seus segredos por cima do seu ombro em uma sessão compartilhada.

Em sites Laravel, Salvar & Aplicar já limpa o cache de configuração (config:clear) na release ativa e, com a opção Reiniciar os workers da fila ao salvar marcada (padrão), reinicia os workers para que eles leiam os novos valores. Em sites Node.js e Next.js, use Mais → Reiniciar site para que o processo leia o .env novo.

#Variáveis geradas automaticamente

O PrimeForge define estas variáveis durante a preparação do site e reabastece as chaves faltantes a partir do .env.example a cada deploy, então uma app Laravel nova geralmente sobe sem edição manual:

#Configurações → Geral

A página Geral (grupo Configurações) guarda a identidade do site e a zona de perigo.

• Nome do domínio — o domínio em que o site é servido. Para trocar, atualize o registro DNS para o novo domínio apontar para o IP do servidor e use a ação Alterar domínio: o PrimeForge atualiza o server_name do vhost do nginx do site e solicita um novo certificado TLS (via acme.sh) automaticamente.
• URL do repositório, branch de deploy e provedor Git — cada um com a sua própria ação Alterar; a lista de branches é lida do repositório, e o próximo deploy passa a usar o que você escolher.
• Excluir site — remove permanentemente o site do PrimeForge: para as unidades systemd do site, remove o vhost do nginx e limpa as referências no painel. Você digita o domínio para confirmar e escolhe se os serviços externos (banco, bucket, Redis) também devem ser removidos — por padrão eles são preservados, para que um site recriado com o mesmo domínio possa adotá-los. Não há "lixeira".

#Domínios e SSL

A página Domínios e SSL cuida de tudo o que o visitante alcança:

• Domínio principal e apelidos — Adicionar domínio anexa um hostname extra, em um de dois modos: Servir (responde com o próprio site) ou Redirecionar (um 301 para o domínio principal, preservando caminho e query string). Cada apelido entra no server_name e na cobertura do certificado; um site pode ter até 10.
• Domínio gratuito — liga ou desliga o subdomínio {rótulo}.on-primeforge.dev.br do site.
• Certificados — o certificado que o vhost está servindo hoje (emissor, validade) fica ao lado da ação Novo certificado SSL, que escolhe o método de verificação (HTTP-01, DNS-01 pelo token do provedor de DNS, ou DNS-01 via acme-dns para certificados curinga), o algoritmo da chave (ECDSA secp384r1, recomendado, ou RSA) e se a cadeia "ISRG Root X1" fica ativa. O certificado é obtido no próximo deploy. Há também Instalar certificado próprio, colando o certificado com a cadeia (fullchain) e a chave privada em PEM: o painel valida o par, a validade e a cobertura dos domínios antes de gravar — e não renova certificados próprios; a renovação passa a ser sua.
• Autenticação básica — Ativar HTTP basic auth protege o site inteiro com usuário e senha (Gerenciar usuários, ou Importar htpasswd para trazer um usuário existente); Gerenciar regras de acesso protege só prefixos de caminho (ex.: /admin), cada um com seus próprios usuários.
• Redirecionamentos — Gerenciar redirecionamentos cria regras de caminho exato para uma URL ou caminho de destino, com o código HTTP, aplicadas no próprio nginx.

#Runtime

A página Runtime define em que o site roda e com quanto:

• Versões de PHP / Node — a dupla de runtime do site. Cada runtime é instalado no próprio host (php-fpm da PPA do ondrej, Node da NodeSource). Trocar a versão dispara um redeploy e falha fechado: o PrimeForge confirma que a versão já está instalada no servidor antes de qualquer mudança. Seu site nunca é apontado para um runtime que o servidor não tem.
• Porta da aplicação — para sites Node.js e Next.js; duas aplicações Node no mesmo servidor não podem compartilhar a porta.
• Limites e recursos — memória, CPU (Alterar limites), modo de memória (Estrito encerra os processos que passam do limite; Flexível permite usar mais RAM e alerta; ou herdar o padrão do servidor) e, em sites Estáticos e PHP Clássico, o arquivo de índice.
• Pastas de logs — diretórios extras que a página de Logs deve varrer; cada arquivo .log encontrado vira uma aba.
• Configuração do Nginx — o server block do site, editável; a alteração vale imediatamente. Um selo avisa quando o vhost está personalizado.
• Configuração do PHP — ajustes de php.ini do pool do site, nos tipos que rodam PHP.
• Configuração do Supervisor — em sites Node.js e Next.js, como o processo da aplicação é mantido vivo (reinício automático, tentativas e comando de start).

#Serviços

A página Serviços é onde você liga e desliga o que o site consome. Após alterar, refaça o deploy para aplicar:

• Banco de dados — a configuração de conexão no .env do site, com a URL de conexão pronta para copiar.
• Redis (cache e fila) — adiciona ou remove a configuração de Redis, e deixa escolher qual servidor atende.
• Horizon — sobe ou para a unidade systemd do worker de filas do Horizon.
• Reverb (WebSocket) — registra ou desregistra o site no servidor Reverb, com o alvo visível e trocável (Alterar servidor, para outro servidor da organização, ou Reverb externo, para um Reverb/Pusher que você mantém).
• Armazenamento (S3) — provisiona ou remove o bucket MinIO e mostra o endpoint, com Copiar endpoint.
• Agendador — liga o agendador do Laravel (schedule:run) do site; as tarefas próprias ficam na página Agendador, no grupo Processos.

Os workers de fila aparecem aqui apenas como resumo — quem os gerencia é a página Workers e Jobs (Gerenciar em Workers e Jobs).

#Deploy: migrações e hooks

Estes ajustes ficam na seção recolhida Configurações e script de deploy, no rodapé da página Deployments:

• Migrations no Deploy — por padrão o pipeline roda php artisan migrate --force no estágio de Script. Se você roda as migrações por fora (um runner separado, releases controladas), clique em Desabilitar: o pipeline pula a migração e o rastreamento de "schema à frente", mas ainda roda optimize:clear e storage:link. A partir daí, você é o dono das migrações.
• Hooks de deploy — além do script principal deploy.sh (roda depois dos passos internos do Laravel), você tem um Hook Pré-Deploy (hooks/pre-deploy.sh, roda no início do estágio de Script, antes das migrações; como o site é atômico, isso é pré-troca, então o visitante nunca o vê) e um Hook Pós-Deploy (hooks/post-deploy.sh, roda depois que a verificação de saúde passa; falhas nele são apenas registradas, nunca derrubam um deploy já no ar). Hooks vazios são pulados em silêncio.
• Deploy automático e segredo do webhook — cada site tem um segredo de webhook (gerado aleatoriamente, criptografado em repouso) embutido em sua URL única de webhook. É com ele que o PrimeForge verifica a assinatura dos pushes do GitHub para o deploy automático. A URL aparece mascarada, com Copiar URL do webhook e Rotacionar segredo do webhook.
• Releases para manter, Caminho do health check e Caminhos compartilhados (pastas mantidas entre releases além de .env e storage/).

#Página de manutenção

O Modo de Pânico serve uma página de manutenção estática quando ativado. Cada site tem um diretório maintenance/ no servidor com o HTML dessa página, editável em Configurações → Página de manutenção (Developer ou acima): defina uma Mensagem Personalizada e a URL do Logo da sua marca, confira em Pré-visualizar e clique em Salvar & Publicar. A própria página mostra se o Panic está ativo e traz o botão de Panic Mode, para você conferir o texto e ativar na sequência.

#Versões de runtime disponíveis

Todo site fixa uma versão de PHP e uma de Node, servidas pelo php-fpm e pelo Node instalados no próprio host — não há imagem de runtime a construir ou distribuir. Quais versões você pode escolher é governado por um registro de versões de runtime mantido pela plataforma; cada versão tem um status de ciclo de vida:

O que isso significa no dia a dia:

• Criando um site — o seletor de versões só mostra as não descontinuadas, com uma pré-selecionada como padrão da plataforma.
• Uma versão que você usava sumiu do seletor — ela foi descontinuada. Seus sites existentes seguem intactos; só sites novos não podem mais escolhê-la.
• Trocando a versão de um site — na página Runtime do site. A troca dispara um redeploy e falha fechado (a versão é confirmada como instalada no host antes de mudar qualquer coisa).
• Rollback de um deploy — cada release grava o runtime com que foi construída, e o rollback de um clique restaura aquela versão de PHP/Node junto com o código. Se aquele runtime tiver sido removido do servidor no meio-tempo, o rollback é recusado até você reinstalá-lo.

Quais versões o painel oferece (e qual é o padrão) é decidido pela plataforma — você não edita esse registro. O que está na sua mão é quais dessas versões existem em cada servidor seu: a seção Runtimes da página Serviços do servidor lista as versões de PHP e Node instaladas naquele host, com quantos sites usam cada uma, e deixa você instalar uma versão oferecida ou remover uma que ninguém mais usa. A remoção é recusada, com o motivo, quando a versão é o padrão do painel ou quando algum site daquele servidor está fixado nela.

#Comandos

A página Comandos (grupo Processos) roda um comando pontual no site e guarda a saída — sem abrir terminal e sem acesso root. O comando roda no diretório da release ativa, como o usuário Linux do site, e a página lista, logo no topo, quais binários aquele site pode executar:

• php, composer e ./vendor/bin/* — nos sites que rodam PHP;
• npm, npx, node, yarn e pnpm — nos sites que usam Node (Node.js, Next.js, e sites Laravel ou estáticos com build de frontend);
• git — em todos.

Digite o comando no campo da página (por exemplo php artisan about) e pressione Enter ou clique em Rodar comando — o mesmo botão também está no cabeçalho. É um comando simples por vez: pipes, redirecionamentos, encadeamento (&&, ;) e expansão de shell são recusados, assim como caminhos que saem do site (..). Cada comando tem limite de 120 segundos.

A tabela abaixo guarda os últimos 50 comandos do site, com o status (Pendente, Executando, Concluído, Falhou), o código de saída, a duração, quem rodou e quando. Cada linha oferece Saída (a saída capturada), Copiar comando, Rodar de novo e Excluir (Admin ou acima). Rodar comandos exige o papel Developer ou acima e o site no ar; a mesma lista fixa de binários vale para a API.

Para uma sessão interativa (um php artisan tinker, por exemplo), use o Terminal do site.

#Logs

A página Logs (grupo Observar) dá acesso aos registros da aplicação, transmitidos do servidor pelo Agent. As abas dependem do tipo do site e do que ele usa:

Escolha quantas linhas ler, busque um termo nas linhas carregadas e deixe a leitura ao vivo ou pause quando quiser ler com calma. A saída do agendador do Laravel aparece no log da aplicação e na Saída de cada tarefa do Agendador.

#Heartbeats

Um heartbeat monitora algo que precisa acontecer de tempos em tempos — um job agendado, um backup externo, um script de importação: ele é uma URL que o job chama a cada execução. Se o silêncio passar do intervalo esperado mais a tolerância, o PrimeForge abre um incidente e envia a notificação heartbeat.missed pelos canais da organização; o próximo ping resolve sozinho (heartbeat.recovered).

A página Heartbeats (grupo Observar) lista os heartbeats do site com o nome, o intervalo esperado, a tolerância, o status (Aguardando, Saudável, Perdido ou Pausado), o próximo prazo e o último ping.

Para criar um:

1. Clique em Novo heartbeat.
2. Dê um Nome, escolha Esperado a cada (de um minuto a um mês) e a Tolerância (de 1 minuto a 1 hora).
3. Na lista, use Copiar URL e faça o seu job chamá-la com GET ou POST ao terminar — por exemplo, acrescentando && curl -fsS <url> à linha do cron.

Cada heartbeat pode ser Editado (a URL continua a mesma), Pausado/Retomado ou Excluído. Para tarefas do Agendador você nem precisa copiar a URL: ligue Monitorar com heartbeat na tarefa e o painel cria o heartbeat e acrescenta o ping à linha do cron sozinho — esses aparecem aqui marcados como gerenciados pela tarefa. Criar e editar heartbeats exige o papel Developer ou acima; os heartbeats perdidos também aparecem no feed de Incidentes.

#Atividade

A página Atividade (grupo Observar) é o registro de auditoria por site: quem fez o quê e quando. Cada deploy, alteração de configuração, ativação de pânico, troca de runtime, edição de .env e mais aparece com autor e horário.

É onde você reconstrói a linha do tempo de um site — útil para investigar uma mudança inesperada de comportamento ou para prestar contas de quem alterou o quê. A atividade por site é um recorte da auditoria geral da organização, filtrado para aquele site, e segue a mesma política: quem não pode ler a auditoria da organização não vê esta página.

#Próximos passos

• Daemons e Workers — processos supervisionados, pools de fila e o agendador do site
• Deploys e Rollback — o pipeline de deploy e o script de deploy
• Serviços, Bancos e Armazenamento — os servidores que hospedam o banco, Redis e S3 que você liga aqui
• Alertas e Monitoramento — regras de alerta e o histórico de eventos