Resso Server

Standalone remote database server for the Resso app. Stores information about infrastructure and assets in a shared database accessible by multiple users.

This server implements the Remote Database API and can be used as a production backend or as a reference for custom implementations.

Requirements

• Python 3.12+
• (Optional) Docker

Quick Start

Local Setup

# Clone and enter the directory
git clone <repo-url>
cd resso-server

# Create a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure at least one auth token
export RESSO_TOKENS="your-secret-token:admin"

# Run
python main.py

The server starts on http://0.0.0.0:5445 by default.

Docker

# Build and run with Docker Compose
RESSO_TOKENS="your-secret-token:admin" docker compose up --build

Or set the token in a .env file (never commit this):

RESSO_TOKENS=your-secret-token:admin

Then run:

docker compose up --build

Configuration

All configuration is done via environment variables. Copy .env.example to .env and edit it.

Variable	Default	Description
HOST	0.0.0.0	Bind address
PORT	5445	Listen port
DATABASE_URL	sqlite+aiosqlite:///./resso.db	Database connection string
RESSO_TOKENS	(none)	Auth tokens, format: token1:user1,token2:user2
CORS_ORIGINS	*	Allowed CORS origins (comma-separated)
LOG_LEVEL	INFO	Logging verbosity (DEBUG, INFO, WARNING, ERROR)

At least one token must be configured. If no tokens are set, all requests are rejected.

Token Format

Multiple tokens:

RESSO_TOKENS=abc123:alice,def456:bob

Single token (alternative syntax):

RESSO_TOKEN=my-secret-token
RESSO_USERNAME=admin

API

All endpoints except /health require a Bearer token in the Authorization header.

Authorization: Bearer your-secret-token

Health

Method	Endpoint	Description
GET	/health	Returns {"status": "ok"}

Assets

Method	Endpoint	Description
GET	/assets	List assets
POST	/assets	Create an asset
GET	/assets/{id}	Get asset details
PUT	/assets/{id}	Update an asset
DELETE	/assets/{id}?cascade=false	Delete an asset

Query Parameters for GET /assets

Parameter	Type	Description
name	string	Filter by name (substring match)
tags	string	Comma-separated tags to filter by
query	string	Resso Query Language expression

Resso Query Language

The query parameter supports a DSL for filtering assets:

name = 'My Server'
provider contains 'aws'
monthlyCost > 100
renewalDate before '2026-01-01'
status = 'active' AND tags contains 'production'
NOT provider = 'gcp'
(tags = 'web' OR tags = 'api') AND name contains 'prod'

Supported operators: =, !=, contains, not contains, <, >, before, after, match wildcard.

Templates

Method	Endpoint	Description
GET	/templates	List templates
POST	/templates	Create a template
PUT	/templates/{id}	Update a template
DELETE	/templates/{id}	Delete a template (assets are unlinked, not deleted)

Tags

Method	Endpoint	Description
GET	/tags	List all tags used across assets

Project Structure

resso-server/
  main.py            # FastAPI app, lifespan, CORS, exception handler
  config.py          # Environment variable loading
  auth.py            # Bearer token verification
  database.py        # SQLAlchemy async engine and session
  models.py          # ORM models (Asset, Template, FieldValue, Dependency)
  schemas.py         # Pydantic DTOs (camelCase JSON)
  query_parser.py    # Resso Query Language parser
  seed.py            # Default templates seeded on first run
  routers/
    assets.py        # Asset CRUD + query filtering
    templates.py     # Template CRUD
    tags.py          # Tag listing
  Dockerfile         # Container image definition
  docker-compose.yml # Docker Compose config
  requirements.txt   # Python dependencies
  .env.example       # Sample environment configuration

License

See repository root for license information.