Deploy — VPS Ubuntu + systemd + Nginx + HTTPS

Guia para publicar o Lernotafiscal em uma VPS Ubuntu (22.04+). O app roda em 127.0.0.1:8000 via Uvicorn sob systemd; o Nginx faz proxy reverso e TLS.

1. Pacotes do sistema

sudo apt update
sudo apt install -y python3-venv python3-pip nginx \
    tesseract-ocr tesseract-ocr-por \
    certbot python3-certbot-nginx

tesseract-ocr-por habilita o OCR em português usado no fallback local. PyMuPDF (render de PDF) vem via pip, não precisa de pacote do sistema.

2. Usuário e código

sudo useradd --system --create-home --home-dir /opt/lernotafiscal lernotafiscal
sudo -u lernotafiscal -H bash
cd /opt/lernotafiscal
git clone <seu-repo> .        # ou copie os arquivos do projeto para cá
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

3. Configuração (`.env`)

cp .env.example .env
# gere um SECRET_KEY forte:
python3 -c "import secrets; print(secrets.token_urlsafe(48))"
nano .env

Defina no mínimo: SECRET_KEY, ADMIN_USERNAME, ADMIN_PASSWORD, SESSION_HTTPS_ONLY=true e, se for usar IA, OPENAI_API_KEY (+ OPENAI_MODEL). Sem OPENAI_API_KEY o app funciona com OCR/heurística local.

4. Dados iniciais (opcional)

Para migrar o histórico existente (21 notas da skill) para o banco do app:

.venv/bin/python scripts/migrate_notas.py

O banco é criado em data/app.sqlite3 na primeira execução do app de qualquer forma.

5. Serviço systemd

sudo cp deploy/lernotafiscal.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now lernotafiscal
sudo systemctl status lernotafiscal
# a senha temporária (se ADMIN_PASSWORD estiver vazio) aparece no log:
sudo journalctl -u lernotafiscal -n 30

6. Nginx + HTTPS

sudo cp deploy/nginx.conf /etc/nginx/sites-available/lernotafiscal
sudo nano /etc/nginx/sites-available/lernotafiscal   # ajuste server_name
sudo ln -s /etc/nginx/sites-available/lernotafiscal /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d seu.dominio.com               # emite e configura o TLS

Após o certbot, confirme que o .env tem SESSION_HTTPS_ONLY=true e reinicie: sudo systemctl restart lernotafiscal.

7. Atualizações

sudo -u lernotafiscal -H bash -c 'cd /opt/lernotafiscal && git pull && .venv/bin/pip install -r requirements.txt'
sudo systemctl restart lernotafiscal

8. Backup

O estado vive em dois lugares — faça backup dos dois (ex.: cron diário):

# banco (checkpoint do WAL antes de copiar)
sqlite3 /opt/lernotafiscal/data/app.sqlite3 "PRAGMA wal_checkpoint(TRUNCATE);"
cp /opt/lernotafiscal/data/app.sqlite3 /backup/app-$(date +%F).sqlite3
# arquivos enviados
tar czf /backup/uploads-$(date +%F).tgz -C /opt/lernotafiscal/data uploads

Notas de segurança

Os arquivos enviados nunca são servidos por static mount; o download passa pela rota autenticada GET /files/{id}.
Segredos ficam só no .env (fora do git via .gitignore).
Rode o Uvicorn apenas em 127.0.0.1 — a exposição pública é só via Nginx/TLS.

3.1 KiB Raw Permalink Blame History