tana-engine

Backend service orchestrator for the Tana blockchain. Manages Docker containers for all backend services.

Quick Start

# Install and link globally
bun install
bun link

# Interactive first-run setup
tana-engine setup

# Check status
tana-engine status

Services

| Service | Port | Description | |---------------|------|--------------------------------| | postgres | 5432 | PostgreSQL database | | redis | 6379 | Queue backend | | api | 8080 | Public API gateway | | ledger | 8501 | Blockchain state | | queue | 8502 | Transaction ingestion | | mesh | 8503 | Network coordination | | identity | 8504 | QR authentication | | consensus | 8505 | Validator coordination (HTTP) | | edge | 8506 | Contract execution | | t4 | 8507 | Content-addressable storage | | notifications | 8091 | Push notifications |

Usage

Setup (First Run)

Interactive setup for new servers:

tana-engine setup

The setup wizard asks:

1. Infrastructure - Which databases to run (postgres, redis)
2. Services - Which Tana services to run on this server
3. Genesis - Whether to initialize the genesis block (if postgres + ledger selected)

This pulls required images, starts selected services, and optionally initializes genesis.

Start

# Start all services
tana-engine start

# Start with genesis block initialization (first run)
tana-engine start --genesis

Stop

# Stop specific services
tana-engine stop postgres
tana-engine stop ledger consensus

# Stop all services
tana-engine stop all

# Stop all and remove data
tana-engine stop all --volumes

Restart

# Restart specific services
tana-engine restart ledger
tana-engine restart mesh t4

# Restart everything
tana-engine restart all

Status

tana-engine status

Output:

● [postgres] healthy :5432
● [redis] healthy :6379
● [api] healthy :8080
● [ledger] healthy :8501
...
● [summary] all 11 services running

Logs

# All logs
tana-engine logs

# Specific service
tana-engine logs ledger

# Follow in real-time
tana-engine logs -f ledger

# Last 50 lines
tana-engine logs -n 50 ledger

Genesis

# Initialize genesis block (requires ledger running)
tana-engine genesis

Check for Updates

# Scan for outdated images
tana-engine check

Output:

○ [postgres] 79c06d285ed9 → 46258a3eb38a (update available)
○ [redis] ee64a64eaab6 → 4706ecab5371 (update available)
● [ledger] 6fba971d70d1 :8501
...
○ [summary] 5 updates available

Update Images

# Pull latest images (without restarting)
tana-engine update

# Pull all images, not just outdated
tana-engine update --all

Upgrade Containers

# Stop, pull new image, restart, cleanup old images
tana-engine upgrade

This performs a graceful upgrade:

1. Stop the container with 30s timeout
2. Pull the new image
3. Remove the old container
4. Start with new image
5. Wait for health check
6. Prune unused images

Monitor (Automatic Updates)

# Start automatic update checking (every 5 minutes)
tana-engine monitor

# Monitor with auto-upgrade (restarts containers)
tana-engine monitor --upgrade

# Check monitor status
tana-engine monitor status

# Stop automatic monitoring
tana-engine monitor stop

Platform support:

• macOS: Uses launchd (plist in ~/Library/LaunchAgents)
• Linux: Uses cron (crontab entry)
• Windows: Uses Task Scheduler (schtasks.exe)

Logs are written to ~/.tana-engine-monitor.log.

Development Setup

Prerequisites

• Bun runtime
• Docker Desktop

Install

bun install
bun link  # Makes tana-engine available globally

Project Structure

The engine expects sibling service directories:

tana/
├── engine/        # This repo
├── api/           # API gateway
├── ledger/        # Blockchain state
├── queue/         # Transaction queue
├── mesh/          # Network coordination
├── identity/      # Authentication
├── consensus/     # Validator coordination
├── edge/          # Contract execution
├── t4/            # Static assets
└── notifications/ # Push notifications

Each service must have a Dockerfile at its root.

Configuration

cp .env.example .env

Key variables:

• VALIDATOR_ID - Unique validator identifier
• VALIDATOR_PUBLIC_KEY - Validator's public key
• SOVEREIGN_PUBLIC_KEY - Network sovereign key
• CHAIN_NAME - Blockchain name (default: "local")
• PEERS - JSON array of peer WebSocket URLs

Building

# Compile to standalone binary
bun run build
# Output: dist/tana-engine

Troubleshooting

Port conflicts:

# Check what's using a port
lsof -i :8501

# Kill process on port
lsof -ti :8501 | xargs kill

Service won't start:

# Check logs
tana-engine logs <service>

# Rebuild image
docker compose build <service>

Reset everything:

tana-engine stop all --volumes
tana-engine start --genesis