Installation¶

Requirements¶

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

Install Invoke¶

Using a virtual environment (recommended):

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

Using the system installation (Debian/Ubuntu):

sudo apt install python3-invoke

Local Installation¶

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

Access SAO at: http://localhost:28086/ (admin / adminspeco / database: speco)

Main Commands¶

Command	Description
`inv up`	Starts the containers (backend + frontend)
`inv init`	Populates the database — REQUIRED the first time
`inv down`	Stops the containers
`inv sh`	Shell inside the test container

Development¶

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

Ports¶

Port	Service
28086	Trytond SAO + RPC
3000	React Frontend
8080	Streamlit Dashboard

Cloud Deployment¶

Speco can be deployed on any VPS or bare-metal server with SSH access. Hetzner, Linode, and Vultr provide automatic provisioning commands, but any server with Docker is supported.

SSH Agent¶

All inv cloud commands use SSH agent forwarding for authentication on the VPS. This avoids copying private keys to the server and allows git clone over SSH on the VPS without requiring a password.

Before running any cloud command, start the SSH agent and add your key:

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

The inv cloud.dev.up command automatically checks whether the SSH agent is running. If not, it starts an agent and adds any keys found in ~/.ssh/.

Provision a VPS (Hetzner, Linode, or Vultr)¶

If you are using Hetzner, Linode, or Vultr, you can provision a VPS automatically:

# 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

The command creates the VPS, waits for SSH to become available, and displays its IP address.

For other providers or bare-metal servers, you only need a server with Docker and root SSH access.

Deploy to the VPS¶

After provisioning, deploy the development environment:

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

This command performs the following on the VPS:

git clone of the repository (using SSH agent forwarding)
Copies the .env configuration file to the VPS
bash setup_deploy.sh — installs dependencies and configures Docker
inv up — starts the containers
inv init — populates the database

Clone Methods¶

By default, SSH agent forwarding is used:

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

Using a personal access token (HTTPS):

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

Management Commands¶

Command	Description
`inv cloud.dev.status --host <IP>`	Container status on the VPS
`inv cloud.dev.logs --host <IP>`	Container logs on the VPS
`inv cloud.dev.restart --host <IP>`	Restart containers on the VPS
`inv cloud.dev.down --host <IP>`	Stop containers on the VPS
`inv cloud.dev.sh --host <IP>`	Interactive shell inside the container
`inv cloud.ssh --host <IP>`	SSH shell on the VPS
`inv cloud.dev.caddy --host <IP> --backend-domain speco.exemplo.com`	Install Caddy and configure an HTTPS reverse proxy

Reverse Proxy with Caddy¶

To expose Speco over HTTPS:

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

This installs Caddy and automatically configures a Let’s Encrypt TLS certificate.

Destroy the VPS¶

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