Instalação completa em uma VPS

Este procedimento parte de uma VPS nova e termina com painel, HTTPS, bancos, Redis, tempo real e worker de runtimes verificados. Substitua os domínios de exemplo pelos seus.

1. Planejar a VPS e a rede

• Use uma imagem de sistema homologada e um usuário com sudo.
• Reserve IPv4 público estável e disco compatível com bancos, releases, logs e backups.
• Libere 80 e 443 para a Internet; restrinja 22 ao seu IP sempre que possível.
• Não publique portas de PostgreSQL, Redis, Docker, Ollama ou serviços internos.
• Para vários projetos ou IA local, aumente CPU, memória e swap antes de instalar.

2. Configurar o DNS

Crie registros A apontando para o IPv4 da VPS:

O domínio curinga completo dos projetos segue o formato *.apps.seudominio.com.

Não coloque https:// no nome do registro. Crie AAAA somente se IPv6 estiver configurado. Na Cloudflare, comece com DNS only para emissão dos certificados; depois use Full (strict), nunca Flexible.

curl -4 -fsS https://api.ipify.org
getent ahostsv4 painel.seudominio.com
getent ahostsv4 realtime.seudominio.com
getent ahostsv4 teste.apps.seudominio.com

Todos os resultados devem apontar para o IPv4 público da VPS antes da validação HTTPS.

3. Acessar e preparar a VPS

ssh ubuntu@IP_DA_VPS
sudo apt update
sudo apt install -y git openssh-client
sudo mkdir -p /var/www/vupi
sudo chown "$USER":"$USER" /var/www/vupi

Se o sistema informar atualização de kernel, conclua a instalação e reinicie em uma janela apropriada. Confirme que o SSH volta a funcionar antes de alterar firewall.

4. Criar uma Deploy Key

Uma Deploy Key dá acesso somente ao repositório escolhido. Gere uma chave exclusiva para esta VPS; não reutilize sua chave pessoal.

install -d -m 0700 "$HOME/.ssh"
ssh-keygen -t ed25519 -C "vupi-vps" -f "$HOME/.ssh/vupi_deploy" -N ""
chmod 600 "$HOME/.ssh/vupi_deploy"
chmod 644 "$HOME/.ssh/vupi_deploy.pub"
cat "$HOME/.ssh/vupi_deploy.pub"

Copie a linha pública completa, iniciada por ssh-ed25519. Nunca copie nem compartilhe o arquivo vupi_deploy sem a extensão .pub.

Cadastrar no GitHub

1. Abra o repositório no GitHub.
2. Acesse Settings → Deploy keys → Add deploy key.
3. Informe um título que identifique a VPS.
4. Cole o conteúdo de vupi_deploy.pub.
5. Deixe Allow write access desmarcado para servidores que apenas recebem atualizações.
6. Confirme em Add key.

Cadastrar no GitLab

1. Abra o projeto no GitLab.
2. Acesse Settings → Repository → Deploy keys.
3. Expanda a seção, informe título e cole a chave pública.
4. Não conceda escrita se a VPS apenas fará clone e pull.
5. Adicione ou habilite a chave para o projeto.

Verificar a chave cadastrada

# GitHub
ssh -i "$HOME/.ssh/vupi_deploy" -o IdentitiesOnly=yes -T [email protected]

# GitLab
ssh -i "$HOME/.ssh/vupi_deploy" -o IdentitiesOnly=yes -T [email protected]

Na primeira conexão, confira a fingerprint exibida pelo provedor antes de aceitar. Uma mensagem informando autenticação bem-sucedida, mesmo sem acesso a shell, confirma a chave. Permission denied (publickey) significa que o arquivo, permissão, usuário SSH ou cadastro está incorreto.

5. Clonar o repositório privado

GitHub

GIT_SSH_COMMAND="ssh -i $HOME/.ssh/vupi_deploy -o IdentitiesOnly=yes" \
git clone --branch main \
  [email protected]:sweflow/api_sweflow_php.git \
  /var/www/vupi

GitLab

GIT_SSH_COMMAND="ssh -i $HOME/.ssh/vupi_deploy -o IdentitiesOnly=yes" \
git clone --branch main \
  [email protected]:SEU_GRUPO/SEU_REPOSITORIO.git \
  /var/www/vupi

Grave a chave no repositório local para que os próximos git pull não dependam de uma variável temporária:

cd /var/www/vupi
git config core.sshCommand "ssh -i $HOME/.ssh/vupi_deploy -o IdentitiesOnly=yes"
git remote -v
git ls-remote --heads origin main

O último comando deve listar o hash da main. Se o diretório já existir e estiver vazio, clone normalmente; se contiver arquivos, não apague sem verificar sua origem.

6. Preparar Turnstile

Crie um widget gerenciado para o hostname do painel. Guarde a Site Key, que pode ir ao navegador, e a Secret Key, que permanece somente no ambiente do servidor. O instalador solicitará ambas em produção.

7. Executar o instalador assistido

cd /var/www/vupi
sudo bash install.sh

O assistente solicita domínio do painel, domínio base dos projetos, domínio de tempo real, e-mail, fuso, administrador, senha e Turnstile. Revise o resumo antes de confirmar.

Ele instala e configura dependências, containers, PHP, Composer, Go, Caddy, Redis, PostgreSQL, migrations, permissões, certificados, worker e serviços de inicialização. Também executa verificações e tentativas seguras de reparo. Uma reexecução preserva dados e segredos existentes sempre que possível.

8. Validar a instalação

cd /var/www/vupi
sudo bash scripts/verify-installation.sh

sudo systemctl is-active \
  docker php-fpm caddy redis-server \
  vupi-realtime vupi-project-runtime-worker

sudo systemctl is-enabled \
  docker php-fpm caddy redis-server \
  vupi-realtime vupi-project-runtime-worker

sudo docker compose ps
curl -sS -o /dev/null -w 'Painel: HTTP %{http_code}\n' https://painel.seudominio.com/
curl -fsS https://realtime.seudominio.com/health

Os serviços devem estar ativos e habilitados, os bancos saudáveis, o painel deve responder por HTTPS e o health de tempo real deve retornar sucesso.

9. Primeiro acesso e primeiro projeto

1. Entre com as credenciais informadas pelo instalador.
2. Ative MFA e confirme o e-mail operacional.
3. Revise domínios, SMTP, CORS e identidade visual.
4. Crie um projeto de teste e confirme o banco individual.
5. Crie uma migration, um seeder e uma rota de status.
6. Execute análise, migration, seeder e teste de rota.
7. Ative o projeto e valide seu domínio externo.
8. Confira logs e monitoramento exclusivos do projeto.

10. Atualizar posteriormente

cd /var/www/vupi
git status --short
git pull --ff-only origin main
composer install --no-dev --no-interaction --prefer-dist --optimize-autoloader
sudo -u www-data php vupi migrate --core
sudo systemctl reload php-fpm
sudo systemctl restart vupi-project-runtime-worker
sudo bash scripts/verify-installation.sh
git log -1 --oneline