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:
| Você quer mudar | Página |
|---|---|
| Variáveis de ambiente | Ambiente |
| Domínio, apelidos, certificado TLS, autenticação básica, redirecionamentos | Domínios e SSL |
Versões de PHP/Node, limites de CPU e memória, vhost do nginx, php.ini |
Runtime |
| Ligar/desligar banco, Redis, Horizon, Reverb, Agendador, S3 | Serviços |
Script de deploy (deploy.sh, com as migrações), hooks, deploy automático, releases a manter |
Deployments → Configurações e script de deploy |
| Workers de fila, pools, daemons, tarefas agendadas do site | Processos e Agendador — veja Daemons e Workers |
Rodar um comando pontual (php artisan …, composer …) |
Comandos |
| Monitorar um job que precisa "dar sinal de vida" | Heartbeats |
| Domínio, repositório, branch, provedor Git, excluir o site | Configurações → Geral |
| Página de manutenção do Panic Mode | Configurações → Página de manutenção |
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
- Abra a página Ambiente do site.
- 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.
- 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 o
.env(pelo editor ou por uma linha da tabela) já refaz o cache de configuração (config:cache) na release ativa. Com Refazer o cache do Laravel ao salvar marcada (padrão), roda tambémphp artisan optimize, que refaz o cache de configuração, rotas, eventos e views, e avisa se falhar. Com Reiniciar os workers da fila ao salvar marcada (padrão), reinicia os workers depois disso, para que eles leiam os novos valores. Em sites Node.js e Next.js, use Mais → Reiniciar site para que o processo leia o.envnovo.
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:
| Variável | Descrição |
|---|---|
APP_KEY |
Chave de criptografia da aplicação Laravel (gerada se ausente) |
DB_HOST, DB_DATABASE, DB_USERNAME, DB_PASSWORD |
Credenciais de conexão do banco |
REDIS_HOST, REDIS_PASSWORD, REDIS_PORT |
Detalhes de conexão do Redis |
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_BUCKET |
Credenciais S3 do bucket do site (no SeaweedFS) |
REVERB_APP_ID, REVERB_APP_KEY, REVERB_APP_SECRET |
Credenciais WebSocket do Reverb |
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_namedo 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_namee na cobertura do certificado; um site pode ter até 10. -
Domínio gratuito — o subdomínio
{rótulo}.on-primeforge.dev.braparece na lista com o selo Domínio PrimeForge, e o menu da linha liga ou desliga. -
Certificado — um selo com o estado e quatro quadros com o certificado que o vhost está servindo hoje (emissor, validade); o menu Certificados traz Instalar certificado próprio e 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.
-
HTTP Basic Auth — Ativar protege o site inteiro com usuário e senha; o menu Usuários traz Gerenciar usuários e Importar htpasswd (para trazer um usuário existente). Sem nenhum usuário, a seção oferece Adicionar usuário.
-
Regras por caminho — o menu Gerenciar traz Gerenciar regras de acesso, que protege só prefixos de caminho (ex.:
/admin), cada um com seus próprios usuários — uma regra em/protege o site inteiro com os usuários dela —, e Gerenciar redirecionamentos, que 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 — ou packages.sury.org no Ubuntu 26.04 —, Node das builds oficiais do nodejs.org). 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 é um teto rígido: o site não usa swap e o kernel encerra o processo que passa do limite; Flexível nunca encerra — acima do limite o kernel desacelera o site e recupera memória, e o painel alerta; ou herdar o padrão do servidor; o ? ao lado do título explica cada opção e como deixar o site livre) 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
.logencontrado vira uma aba. - Nginx — o vhost do site é sempre gerado pelo painel (certificado, Basic Auth, aliases, regras, Reverb). O que você edita são as Diretivas personalizadas: elas entram como a primeira coisa de cada bloco
serverque atende o site (HTTPS e, sem certificado, HTTP), antes das diretivas do painel — cabeçalhos,locations a mais, limites, redirecionamentos. Ao salvar, o painel testa comnginx -t: se o nginx recusar, nada muda e você vê a mensagem dele. As diretivas valem em todos os deploys, migrações e restaurações. Umalocationcom expressão regular sua é avaliada antes das do painel; o nginx recusa uma diretiva repetida no mesmo bloco. Sobrescrever o que o painel define é por sua conta e risco. Ver o nginx gerado pelo painel mostra, só para leitura, o arquivo inteiro que atende o site. Limpar diretivas remove todas. Precisa do agente 0.4.25 ou mais novo no servidor. - Configuração do PHP — ajustes de
php.inido pool do site, nos tipos que rodam PHP. Cada ajuste mostra de onde vem o valor: Padrão do sistema, Padrão do servidor (definido em Serviços › Runtimes › PHP {versão} › Configurar do servidor) ou Personalizado (definido aqui) — e Voltar ao padrão do servidor desfaz a personalização daquele ajuste. Os valores ficam guardados no painel, então sobrevivem a uma troca de versão do PHP, a um rollback e aos deploys. - Configuração do Node — em sites Node.js e Next.js, os ajustes do Node (como
NODE_ENVeNODE_OPTIONS), herdados do servidor (Serviços › Runtimes › Node {versão}) enquanto não forem personalizados aqui; Salvar e reiniciar reinicia o processo Node do site. UmNODE_ENVouNODE_OPTIONSno.envdo site tem precedência sobre os dois. - 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. Redis, Reverb e IA Local valem na hora: o painel regrava o .env, refaz o cache de configuração, recarrega o PHP-FPM e reinicia com cuidado os workers e o Horizon do site (eles terminam o job atual), porque esses processos só leem a configuração quando sobem. O modal de cada alteração avisa disso antes de você confirmar.
-
Banco de dados — a configuração de conexão no
.envdo 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 — Habilitar/Desabilitar no menu da linha troca, na hora e sem deploy, quem consome as filas: ligado, os workers
queue:workparam e o Horizon assume; desligado, o Horizon para e os workers voltam. Precisa de Redis no site e do pacotelaravel/horizonna versão no ar — sem ele o painel recusa e explica. -
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). Ao trocar de servidor, o site sai do registro do Reverb do servidor anterior.
-
Armazenamento (S3) — provisiona ou remove o bucket S3 (no SeaweedFS do servidor escolhido) 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. -
IA Local (Ollama) — Habilitar/Desabilitar no menu Ações da linha dá ao site acesso ao Ollama de um servidor da organização, e Alterar troca o servidor — veja IA Local (Ollama).
Os workers de fila aparecem aqui apenas como resumo — quem os gerencia é a página Processos (Gerenciar em Processos).

Deploy: script e hooks
Estes ajustes ficam na seção recolhida Configurações e script de deploy, no rodapé da página Deployments:
- Script de deploy — o
deploy.shé o build do site:composer install,npm ci/build e os comandosartisan(storage:link,migrate --force,optimize) ficam nele, e o painel não os roda por conta própria. O primeiro deploy grava um script padrão a partir do repositório; depois ele é seu para editar. As migrações rodam porque o script tem a linha$PF_PHP artisan migrate --force— remova-a se você roda as migrações por fora (um runner separado, releases controladas); a partir daí, você é o dono das migrações. Veja O script de deploy e os hooks. - Hooks de deploy — além do
deploy.sh, você tem um Hook Pré-Deploy (hooks/pre-deploy.sh, roda logo antes dodeploy.sh, dentro da nova release; 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. - 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
.envestorage/).

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:
| Status | Sites novos | Sites existentes |
|---|---|---|
| Estável | Oferecida no seletor | Totalmente suportada |
| Beta | Oferecida, marcada como beta | Totalmente suportada |
| Descontinuada | Oculta do seletor de novos sites | Continua funcionando; ainda listada na página Runtime do site para você migrar no seu ritmo |
| Fim de vida | Bloqueada | Bloqueada — uma versão não pode ir a fim de vida enquanto algum site ainda a usa, então sempre há uma janela de descontinuação antes |
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,composere./vendor/bin/*— nos sites que rodam PHP;npm,npx,node,yarnepnpm— 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.

Aba Scripts
A página tem duas abas: Comandos, descrita acima, e Scripts. A aba Scripts lista as execuções dos scripts de site da organização neste site. Para rodar um, use Executar script no cabeçalho (Developer ou acima): escolha o script e confira o usuário, a pasta e o conteúdo antes de confirmar. O script roda como o usuário Linux do site, na release ativa, com as variáveis PF_PHP, PF_SITE_PATH, PF_RELEASE_PATH, PF_SHARED_PATH, PF_DOMAIN e PF_SITE_USER definidas. Diferente da aba Comandos, um script é bash completo: pipes, laços e vários comandos são permitidos. Os scripts são escritos em Operações › Scripts — veja Scripts.
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:
| Aba | O que contém |
|---|---|
| Site | O journal do processo do site (php-fpm ou a unidade Node) — não existe em sites HTML Estático |
| Horizon | Os workers de fila do Horizon, quando ele está ligado |
| Reverb | O servidor WebSocket, quando o site usa Reverb |
| Nginx (acesso) e Nginx (erros) | Os logs de acesso e de erro do vhost do site |
| Arquivos de log | Cada arquivo .log das pastas de logs do site — em sites Laravel, o laravel.log |
| Processos | Uma aba por processo supervisionado do site — worker, pool, daemon, unidade Node — também alcançável pelo Ver logs da página Processos |

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:
- Clique em Novo heartbeat.
- Dê um Nome, escolha Esperado a cada (de um minuto a um mês) e a Tolerância (de 1 minuto a 1 hora).
- 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