# Inicio Rapido

Este guia te leva do zero ate ter um agent enrolado e operacional. Pressupoe que voce ja tem:

• Docker + Docker Compose instalado no hub
• Acesso SSH a um VPS de teste
• Dominio publico apontando pro hub (ex: tatuzim.dev.borlot.com.br)
• Traefik (ou outro reverse proxy) com Let's Encrypt configurado

# 1. Subir o Tatuzim Server

No hub:

git clone https://github.com/devborlot/tatuzim
cd tatuzim

cat > .env << 'EOFENV'
STEP_CA_PASSWORD=sua-senha-step-ca
TATUZIM_MASTER_PASSPHRASE=sua-senha-vault-MUITO-FORTE
EOFENV

docker compose up -d step-ca
sleep 10

# Capturar provisioner kid + key (necessario pro server)
PROV_KID=$(docker exec dev_stepca_tatuzim step ca provisioner list | jq -r '.[0].key.kid')
ENC_KEY=$(docker exec dev_stepca_tatuzim step ca provisioner list | jq -r '.[0].encryptedKey')
PROV_KEY=$(docker exec -i dev_stepca_tatuzim sh -c "echo '$ENC_KEY' | step crypto jwe decrypt --password-file /run/secrets/ca_password")

cat >> .env << EOFENV2
TATUZIM_STEPCA_PROVISIONER_KID=$PROV_KID
TATUZIM_STEPCA_PROVISIONER_KEY=$(echo "$PROV_KEY" | jq -c .)
EOFENV2

# Extrair root CA pra montar no server container
mkdir -p certs
docker exec dev_stepca_tatuzim cat /home/step/certs/root_ca.crt > certs/root_ca.pem

docker compose up -d tatuzim-server
docker logs -f dev_tatuzim_server

Voce deve ver:

INFO tatuzim_server: vault unsealed
INFO tatuzim_server: schema verified
INFO tatuzim_server: stepca client ready
INFO tatuzim_server::server_identity: requesting fresh server cert from step-ca
INFO tatuzim_server: enroll endpoint listening
INFO tatuzim_server: mTLS endpoint listening (strict)

Verifique health publicamente:

curl https://tatuzim.SEUDOMINIO.com/v1/enroll -X POST -d '{}'
# Esperado: 401 {"error":"token_not_found"} — server respondendo

# 2. Criar um Enrollment Token

O server precisa ser parado para o CLI offline acessar o vault (lock exclusivo):

docker stop dev_tatuzim_server

TOKEN=$(docker run --rm --entrypoint /usr/local/bin/tatuzim \
    -v tatuzim_tatuzim_vault:/var/lib/tatuzim \
    -e TATUZIM_MASTER_PASSPHRASE="$TATUZIM_MASTER_PASSPHRASE" \
    tatuzim-server:dev \
    token create --root /var/lib/tatuzim \
        --hostname meu-vps-01 --role mautic --ttl 1h \
    | awk '/^    [A-Za-z0-9_-]{20,}$/ { print $1; exit }')

echo "Token gerado: $TOKEN"
docker start dev_tatuzim_server

Esse token e single-use e valido por 1h.

# 3. Instalar o Agent no VPS

A partir da v0.1.0, o agent esta publicado em https://get.tatuzim.com:

ssh root@meu-vps-01 << 'EOF'
ARCH=$(uname -m)
curl -fsSLo /usr/local/bin/tatuzim-agent https://get.tatuzim.com/$ARCH/tatuzim-agent
chmod +x /usr/local/bin/tatuzim-agent

# Para systemd unit + user "tatuzim" + diretorios, instale tambem o .deb
# (build local: cd /proj/tatuzim/server && cargo deb -p tatuzim-agent)
EOF

Apos a instalacao com .deb:

• Binario em /usr/local/bin/tatuzim-agent
• User tatuzim criado (uid 999)
• Diretorios em /var/lib/tatuzim-agent/ (0750, tatuzim:tatuzim)
• systemd unit em /etc/systemd/system/tatuzim-agent.service (disabled)

Detalhes em Instalar o Tatuzim Agent e Distribuicao.

# 4. Enroll do Agent

Voce precisa do root CA do step-ca pra o agent confiar no server (mTLS):

# No hub
docker exec dev_stepca_tatuzim cat /home/step/certs/root_ca.crt > /tmp/stepca-root.pem
scp /tmp/stepca-root.pem root@meu-vps-01:/etc/tatuzim-agent/

No VPS:

sudo -u tatuzim \
    TATUZIM_SERVER_URL="https://tatuzim.SEUDOMINIO.com" \
    TATUZIM_SERVER_MTLS_URL="https://tatuzim.SEUDOMINIO.com:8443" \
    TATUZIM_SERVER_CA_PATH="/etc/tatuzim-agent/stepca-root.pem" \
    TATUZIM_AGENT_HOSTNAME="meu-vps-01" \
    TATUZIM_AGENT_ROLE="mautic" \
    TATUZIM_AGENT_DATA_DIR="/var/lib/tatuzim-agent" \
    TATUZIM_ENROLL_TOKEN="$TOKEN" \
    /usr/local/bin/tatuzim-agent enroll

Saida esperada:

INFO starting enrollment hostname=meu-vps-01 role=mautic
INFO calling enrollment endpoint url=https://.../v1/enroll

Enrolled successfully!
  agent_id: 00000000-0000-...
  hostname: meu-vps-01
  identity: /var/lib/tatuzim-agent/identity

You may now remove TATUZIM_ENROLL_TOKEN from the environment.

# 5. Validar

No VPS:

sudo -u tatuzim TATUZIM_SERVER_URL=https://tatuzim.SEUDOMINIO.com \
    TATUZIM_AGENT_HOSTNAME=meu-vps-01 \
    TATUZIM_AGENT_DATA_DIR=/var/lib/tatuzim-agent \
    /usr/local/bin/tatuzim-agent identity

Mostra:

Tatuzim Agent identity:
  hostname:    meu-vps-01
  cert CN:     meu-vps-01
  cert serial: ...
  not_before:  May 23 ...
  not_after:   May 24 ...
  data_dir:    /var/lib/tatuzim-agent

# 6. Habilitar o Daemon

Crie um arquivo de env pra systemd:

sudo tee /etc/tatuzim-agent/env << EOF
TATUZIM_SERVER_URL=https://tatuzim.SEUDOMINIO.com
TATUZIM_SERVER_MTLS_URL=https://tatuzim.SEUDOMINIO.com:8443
TATUZIM_SERVER_CA_PATH=/etc/tatuzim-agent/stepca-root.pem
TATUZIM_AGENT_HOSTNAME=meu-vps-01
TATUZIM_AGENT_ROLE=mautic
TATUZIM_AGENT_DATA_DIR=/var/lib/tatuzim-agent
TATUZIM_AGENT_POLL_INTERVAL=30s
TATUZIM_AGENT_RENEWAL_THRESHOLD=6h
RUST_LOG=info