Manual completo: do Termux à hospedagem VPS

Instalação simplificada em uma VPS nova

Após baixar o ZIP e configurar a chave SSH no Termux, o assistente transfere o pacote, verifica o plano e instala com confirmação. Não altera as verificações de segurança nem exige domínio.

pkg install -y openssh unzip
termux-setup-storage
mkdir -p ~/als-instalador
unzip -oq ~/storage/downloads/AL-Sistemas-v2.0.5-VPS.zip inicio-termux.sh bootstrap-vps.sh -d ~/als-instalador

Execute do Termux local (troque IP e chave pelos seus dados):

bash ~/als-instalador/inicio-termux.sh --host IP_DA_VPS --key ~/.ssh/minha-chave.pem

O assistente pede confirmação antes de executar sudo instalar.sh. Para VPS com sites existentes, acrescente --existing; PHP/MariaDB opcionais usam --with-php e --with-mariadb. O SSH continua obrigatório e a porta 8181 não é exposta.

A versão 2.0.5 ainda não automatiza autenticação inicial do provedor nem criação de chaves SSH. O atalho é para um Ubuntu 24.04 com SSH funcional; ele não migra sites ou bancos.

1. Preparar a VPS

1. Crie uma VPS com Ubuntu Server 24.04 LTS, arquitetura amd64 ou arm64.
2. Configure acesso SSH com chave pública. Na AWS, verifique o Security Group: libere sua porta SSH, mas não exponha 8181.
3. Recomenda-se no mínimo 1 GiB de RAM e 4 GiB livres; a instalação recusa menos de 1 GiB livres. Uma EC2 de 2 GiB pode rodar o núcleo leve.
4. Para servidores existentes, gere snapshot/backup antes da instalação. Bancos em atividade exigem backup consistente, não apenas cópia a quente.

O AL Sistemas é para uma VPS por instalação. A instalação com --allow-existing-host aceita sites existentes, mas pode alterar componentes do sistema. O projeto IguatamaOnline não é alterado diretamente pelo instalador.

2. Preparar o Termux no Android

Abra Termux e conceda permissão ao armazenamento compartilhado.

termux-setup-storage
pkg install openssh -y

Confirme que o ZIP está em Downloads. Se o nome da Release mudou, ajuste-o.

ls -lh ~/storage/downloads/AL-Sistemas-v2.0.5-VPS.zip

3. Chave SSH e primeiro acesso

Confirme os nomes das chaves disponíveis sem mostrar o conteúdo.

ls -lah ~/.ssh/

Exemplo com chave guardada no Termux:

chmod 600 ~/.ssh/minha-chave.pem
ssh -i ~/.ssh/minha-chave.pem ubuntu@IP_DA_VPS

Permission denied (publickey) significa que a VPS não aceitou a chave oferecida. Verifique usuário, chave, IP e configuração do SSH. Não crie ou substitua chaves indiscriminadamente.

4. Enviar o ZIP por SCP

Este comando roda no Termux local, não na VPS.

scp -i ~/.ssh/minha-chave.pem \
  ~/storage/downloads/AL-Sistemas-v2.0.5-VPS.zip \
  ubuntu@IP_DA_VPS:~/

Depois conecte via SSH e confirme o arquivo.

ssh -i ~/.ssh/minha-chave.pem ubuntu@IP_DA_VPS
ls -lh ~/AL-Sistemas-v2.0.5-VPS.zip

5. Extrair, planejar e instalar

Com o prompt ubuntu@..., os comandos a seguir serão executados dentro da VPS.

sudo apt-get update
sudo apt-get install -y unzip
mkdir -p ~/al-sistemas-instalar
unzip -q ~/AL-Sistemas-v2.0.5-VPS.zip -d ~/al-sistemas-instalar
cd ~/al-sistemas-instalar
bash instalar.sh --plan

Revise a saída. Em VPS com projetos existentes, use:

sudo bash instalar.sh --allow-existing-host

Para um servidor novo, pode omitir --allow-existing-host. Para instalação opcional de PHP e MariaDB, acrescente --with-php e --with-mariadb, respectivamente. Não habilite firewall automaticamente sem verificar SSH.

Sem domínio, o processo inicia o painel apenas em 127.0.0.1:8181. O navegador acessará pelo túnel SSH, sem abrir a porta 8181 à internet.

6. Abrir o painel pelo Chrome

Crie outra sessão do Termux, mantendo a VPS em execução. Nessa nova sessão, que deve estar fora do SSH, abra o túnel:

ssh -i ~/.ssh/minha-chave.pem -N \
  -o ExitOnForwardFailure=yes \
  -L 8181:127.0.0.1:8181 \
  ubuntu@IP_DA_VPS

Mantenha a conexão aberta. No Chrome, acesse http://localhost:8181. Se o terminal ficar parado sem mostrar saída, é normal: o túnel está ativo.

7. Configuração da conta e autenticador

1. Na VPS, consulte o código inicial com sudo cat /var/lib/alsistemas/bootstrap-token, sem divulgá-lo.
2. Digite-o na tela de configuração do painel.
3. Cadastre a chave TOTP no Google Authenticator, Aegis ou outro autenticador compatível. Guarde backup criptografado da chave.
4. Crie uma senha forte, confirme o código de seis dígitos e faça login.
5. Para acessar mais facilmente, marque Confiar neste dispositivo por 30 dias. No mesmo navegador e enquanto o cookie existir, precisará normalmente apenas da senha.

A confiança não ignora a senha e não permite alterar configurações sensíveis sem TOTP. Se o celular for perdido, use Segurança → Revogar todos os dispositivos. Se perder senha e TOTP, não há reset remoto por e-mail na versão atual.

8. Confirmar instalação e funcionamento

sudo systemctl is-active alsistemas-vps
curl -i http://127.0.0.1:8181/api/health
sudo nginx -t
sudo systemctl cat alsistemas-vps --no-pager

O endpoint de saúde deve retornar HTTP 200 e "ok":true. O dashboard deverá mostrar métricas reais e listar projetos. Projetos não criados pelo painel são somente leitura.

9. Configurar subdomínio e HTTPS, quando desejar

1. No DNS do provedor (por exemplo, Spaceship), crie um registro A para painel apontando ao IPv4 da VPS.
2. Verifique a propagação com getent ahostsv4 painel.exemplo.com.
3. Garanta portas públicas TCP 80 e 443 e preserve acesso SSH.
4. Execute a atualização do instalador com --domain e --email.

cd ~/al-sistemas-instalar
sudo bash instalar.sh --allow-existing-host \
  --domain painel.exemplo.com \
  --email voce@exemplo.com

Se não houver domínio, continue usando o túnel SSH. Não use HTTPS fictício nem publique diretamente a porta 8181.

10. Atualizações pelo GitHub, com assinatura obrigatória

A partir da 2.0.5, o painel possui a aba Atualizações. É necessário configurar o repositório e uma chave pública de assinatura Ed25519. Não existe repositório ou chave pré-configurados.

Preparar chave fora da VPS (uma vez)

Em um ambiente seguro, gere o par de chaves. A privada deve ficar em local criptografado, fora da VPS e fora do repositório.

openssl genpkey -algorithm ED25519 -out signing-private.pem
openssl pkey -in signing-private.pem -pubout -out update-public-key.pem
chmod 600 signing-private.pem

Envie apenas a pública para a VPS e rode novamente o instalador, sem apagar dados:

# No Termux, com o arquivo público em ~/:
scp -i ~/.ssh/minha-chave.pem ~/update-public-key.pem ubuntu@IP_DA_VPS:~/
# Na VPS:
cd ~/al-sistemas-instalar
sudo bash instalar.sh --allow-existing-host \
  --update-key-file /home/ubuntu/update-public-key.pem

Na aba Atualizações do painel, salve proprietario/repositorio com senha e um TOTP novo. Você pode manter o repositório público; não precisa configurar token GitHub para consulta de Releases públicas.

Publicar uma versão nova

1. Gere o ZIP completo com nome AL-Sistemas-vX.Y.Z-VPS.zip, e teste-o.
2. Execute, fora da VPS, o script tools/assinar-release.sh usando a chave privada.
3. No GitHub, crie uma Release com a tag vX.Y.Z e anexe três arquivos: ZIP, update-manifest.json e update-manifest.json.sig.
4. No painel, toque em Verificar GitHub, confira a versão e use Instalar versão assinada, confirmando senha e TOTP.

./tools/assinar-release.sh \
  /caminho/seguro/signing-private.pem \
  AL-Sistemas-v2.0.5-VPS.zip

O atualizador rejeita releases sem assinatura válida, hash incompatível ou versão não superior. Ele cria backup de código, usa o instalador, verifica o serviço e tenta rollback quando falha. Não realiza backup de sites ou bancos. O recurso exige testes numa VPS de homologação antes de ser usado em produção.

11. Backups e proteção de dados

• O backup do painel na 2.0.5 ainda cobre somente a pasta public/ de sites criados pelo próprio AL Sistemas, com GPG AES-256.
• A frase de criptografia não é armazenada. Sem ela, o backup é irrecuperável.
• Faça exportações separadas de bancos MariaDB, configurações Nginx, certificados, arquivos privados e dados do painel.
• Leve os backups para armazenamento externo e teste restauração regularmente.
• Para AWS, snapshots EBS ajudam na recuperação, mas exigem atenção à consistência do banco de dados.

12. Solução de problemas observados

13. Instalar numa nova VPS ou migrar

1. Faça backup consistente dos sites, bancos, configurações, dados do painel e certificados. Guarde fora da VPS anterior.
2. Crie uma nova VPS e siga as seções 1–8 com o ZIP correspondente.
3. Transfira os projetos e bancos somente após verificar compatibilidade, usuários, permissões e versões PHP/MariaDB.
4. Configure Nginx e certificados para o novo IP. Atualize DNS no seu provedor, mantendo a VPS antiga operante durante a transição.
5. Teste DNS, HTTPS, logs, backups e integridade. Somente então desligue a VPS antiga.

A restauração completa automática entre VPS ainda não está implementada. Não suponha que copiar apenas o ZIP do AL Sistemas migra seus sites e bancos.

14. Recuperar acesso e verificar erros

Com acesso SSH funcional, o painel pode ser diagnosticado mesmo sem domínio:

sudo systemctl status alsistemas-vps --no-pager
sudo journalctl -u alsistemas-vps -n 80 --no-pager
sudo journalctl -u alsistemas-updater -n 80 --no-pager
curl -i http://127.0.0.1:8181/api/health

Não apague /var/lib/alsistemas/admin.json nem as chaves TOTP para tentar resolver erro de login: isso pode causar perda de acesso. Mantenha o SSH e backups de credenciais disponíveis e evite registrar segredos em screenshots.