Instalação¶

Requisitos¶

Docker >= 20
Docker Compose >= 2
Python >= 3.10
Invoke >= 2.0

Instalar Invoke¶

Com venv (recomendado):

python3 -m venv .venv
source .venv/bin/activate
pip install invoke

Com sistema (Debian/Ubuntu):

sudo apt install python3-invoke

Instalação Local¶

git clone https://codeberg.org/Tekopora/speco.git
cd speco
git checkout main
cp backend/env_sample backend/.env
inv up
inv init

Acesso ao SAO: http://localhost:28086/ (admin / adminspeco / banco: speco)

Comandos Principais¶

Comando	Descrição
`inv up`	Inicia containers (backend + frontend)
`inv init`	Popula banco — OBRIGATÓRIO na primeira vez
`inv down`	Para containers
`inv sh`	Terminal no container de teste

Desenvolvimento¶

inv dev.trytond                          # Trytond com banco existente
inv dev.trytond-fresh                    # Banco novo (sem populate)
inv dev.trytond-fresh-populated          # Banco novo e populado

Portas¶

Porta	Serviço
28086	Trytond SAO + RPC
3000	Frontend React
8080	Dashboard Streamlit

Instalação na Nuvem¶

O Speco pode ser implantado em qualquer VPS ou servidor baremetal com acesso SSH. Os provedores Hetzner, Linode e Vultr possuem comandos de provisionamento automático, mas qualquer servidor com Docker funciona.

SSH Agent¶

Todos os comandos inv cloud usam SSH agent forwarding para autenticação no VPS. Isso evita copiar chaves privadas para o servidor e permite usar git clone via SSH no VPS sem senha.

Antes de executar qualquer comando cloud, inicie o agent e adicione sua chave:

eval $(ssh-agent -s)
ssh-add ~/.ssh/id_ed25519

O comando inv cloud.dev.up verifica automaticamente se o agent está rodando. Se não estiver, ele inicia um agent e adiciona as chaves encontradas em ~/.ssh/.

Provisionar VPS (Hetzner, Linode ou Vultr)¶

Se estiver usando Hetzner, Linode ou Vultr, pode provisionar automaticamente:

# Hetzner (requer HCLOUD_TOKEN no .env)
inv cloud.provision-hetzner

# Linode (requer LINODE_TOKEN no .env)
inv cloud.provision-linode

# Vultr (requer VULTR_API_KEY no .env)
inv cloud.provision-vultr

O comando cria o VPS, aguarda SSH disponível e mostra o IP.

Para outros provedores ou baremetal, basta ter um servidor com Docker e acesso SSH root.

Implantar no VPS¶

Após provisionar, implante o ambiente de desenvolvimento:

inv cloud.dev.up --host <IP_DO_VPS>

Este comando executa, no VPS:

git clone do repositório (via SSH agent forwarding)
Copia .env com configurações para o VPS
bash setup_deploy.sh — instala dependências e configura Docker
inv up — inicia containers
inv init — popula banco

Métodos de clone¶

Por padrão, usa SSH agent forwarding:

inv cloud.dev.up --host <IP>

Com token pessoal (HTTPS):

inv cloud.dev.up --host <IP> --method https --token <SEU_TOKEN>

Comandos de Gerenciamento¶

Comando	Descrição
`inv cloud.dev.status --host <IP>`	Status dos containers no VPS
`inv cloud.dev.logs --host <IP>`	Logs dos containers no VPS
`inv cloud.dev.restart --host <IP>`	Reiniciar containers no VPS
`inv cloud.dev.down --host <IP>`	Parar containers no VPS
`inv cloud.dev.sh --host <IP>`	Shell interativo no container
`inv cloud.ssh --host <IP>`	Shell SSH no VPS
`inv cloud.dev.caddy --host <IP> --backend-domain speco.exemplo.com`	Instalar Caddy e configurar reverse proxy com HTTPS

Reverse Proxy com Caddy¶

Para expor o Speco com HTTPS:

inv cloud.dev.caddy --host <IP> --backend-domain speco.exemplo.com

Isso instala o Caddy e configura automaticamente certificado Let’s Encrypt.

Destruir VPS¶

inv cloud.destroy-hetzner       # ou destroy-linode / destroy-vultr