Instalação e Deploy

O Speco usa o Invoke como executor de tarefas — um “Makefile” moderno em Python puro. Todas as operações do sistema — subir o ambiente local, provisionar servidores, fazer deploy, construir a documentação — são tarefas Invoke organizadas em namespaces.

A vantagem: um único comando faz o que antes precisava de vários scripts dispersos. E como é Python puro, funciona sem dependências extras.

Instalação local

O ambiente local roda inteiramente em Docker. Você só precisa de Python e Docker na máquina.

Pré-requisitos

• Python 3.10+

• Docker e docker compose

• Git

Passo a passo

# 1. Clonar o repositório
git clone ssh://git@git.disroot.org/RedEcovida/speco_dev.git
cd speco_dev
git checkout floatv2

# 2. Criar o ambiente virtual e instalar o Invoke
bash setup_deploy.sh

# 3. Ativar o ambiente virtual
source .venv/bin/activate

# 4. Subir o ambiente (backend + frontend)
inv up

# 5. Instalar dependências e módulos
inv init

# 6. (Opcional) Iniciar Trytond com dados de demonstração
inv dev.trytond-fresh-populated --name speco --scale 1

A partir daqui, o sistema está disponível em http://localhost:8001 (backend) e http://localhost:3000 (frontend).

Tarefas locais

inv up                        # Subir backend + frontend
inv down                      # Parar ambiente
inv init                      # Instalar dependências e módulos
inv sh                        # Shell no container
inv dev.trytond               # Iniciar Trytond (reutiliza base)
inv dev.trytond-fresh         # Base nova sem populate
inv dev.trytond-populated     # Base existente + populate
inv dev.trytond-fresh-populated  # Base nova + populate
inv dev.docs                  # Construir documentação Sphinx
inv tests --name speco        # Testes de um módulo
inv bdd.run --name speco      # BDD de um módulo

Deploy na nuvem

O mesmo Invoke que gerencia o ambiente local também provisiona servidores e faz deploy. A diferença é o namespace: cloud.dev.* para operações no VPS, cloud.provision-* para criar o servidor.

Pré-requisitos

• Python 3.10+ com venv — apt install python3-venv

• Chave SSH autorizada no Forgejo (para clone via SSH)

• Token de API do provider de cloud (Hetzner, Linode ou Vultr)

• DNS apontando para o servidor

Token do provider

O token permite que o Invoke crie o servidor no seu nome via API.

Provider	Onde criar o token	Variável
Hetzner	console.hetzner.com → Projects → Access → API Tokens	HETZNER_TOKEN
Linode	cloud.linode.com → Account → API Tokens	LINODE_TOKEN
Vultr	my.vultr.com → Settings → API	VULTR_TOKEN

Exporte o token antes de rodar qualquer comando de provisionamento:

export HETZNER_TOKEN="seu_token"

Provisionar o VPS

inv cloud.provision-hetzner --name meu-servidor --location nbg1
# Anotar o IP retornado

Os providers Linode e Vultr também estão disponíveis com cloud.provision-linode e cloud.provision-vultr.

Deploy com um comando

Com o IP do servidor em mãos:

inv cloud.dev.up --host IP_DO_VPS --allowed-hosts portal.ecovida.org.br,float.ecovida.org.br

Isso faz tudo: clone do repositório, instalação do Docker, configuração do ambiente, subida dos containers e atualização do CORS. Em minutos, o sistema está no ar.

Para atualizar um deploy existente, o mesmo comando faz git pull e reinicia os containers.

HTTPS automático

O Speco usa Caddy como reverse proxy. Caddy obtém e renova certificados TLS via Let’s Encrypt automaticamente — sem certbot, sem cron, sem intervenção manual.

inv cloud.dev.caddy --host IP_DO_VPS \
  --frontend-domain portal.ecovida.org.br \
  --backend-domain float.ecovida.org.br

DNS

Recomendamos usar um único registro A como alias, com CNAMEs apontando para ele. Assim, se o IP mudar, só é preciso atualizar um registro:

devs.ecovida.org.br        A      203.0.113.42   ← só este muda
portal.ecovida.org.br  CNAME  devs.ecovida.org.br
float.ecovida.org.br    CNAME devs.ecovida.org.br

Iniciar o Trytond no VPS

Depois do deploy, entre no container e inicialize o banco:

inv cloud.dev.sh --host IP_DO_VPS
# Dentro do container:
inv dev.trytond-fresh-populated   # Primeiro uso: base nova + dados

Tarefas na nuvem

inv cloud.dev.up --host IP --allowed-hosts DOMINIOS    # Deploy completo
inv cloud.dev.down --host IP                           # Parar ambiente
inv cloud.dev.logs --host IP                           # Ver logs
inv cloud.dev.sh --host IP                             # Shell no container
inv cloud.dev.restart --host IP                        # Reiniciar
inv cloud.dev.status --host IP                         # Status
inv cloud.dev.caddy --host IP --frontend-domain DOM --backend-domain DOM  # HTTPS
inv cloud.ssh --host IP                                # SSH interativo