Backend Documentation

Welcome to the ContainerPub backend documentation. The platform runs two backend servers that serve different purposes.

Backend Servers

Dart Cloud Backend (dart_cloud_backend)

The core platform that:

Hosts Functions - Execute Dart functions in isolated containers
Manages Containers - Podman-based container orchestration
Provides APIs - RESTful HTTP endpoints for function management
Handles Authentication - Keycloak OIDC with legacy JWT fallback
Stores Data - PostgreSQL for metadata
Monitors Performance - Metrics collection and logging

Admin Backend (admin_backend_api)

The administrative management server that:

Manages Users - Soft-delete, disable/enable, temporary passwords
Handles Auth - Keycloak OIDC with role-based access (full_admin, viewer)
Manages Feature Roles - Grant/remove per-user feature roles via Keycloak
Administers Early Access - Request review, approval, capacity management
Manages Organizations - Org CRUD, tier assignment, membership
Provides Observability - System-wide logs, errors, load monitoring

Quick Links

Core Documentation

Authentication System - Keycloak OIDC auth with legacy JWT fallback
Admin Authentication - Keycloak OIDC auth system for admin backend
Email Verification System - Email OTP verification (deprecated, migrating to Keycloak)
API Keys & Signing - Secure function invocations with HMAC signatures
Input Validation Middleware - Schema-based request validation with Zard
Statistics & Monitoring - Dashboard metrics and performance tracking
Architecture Overview - System design and components
Function Execution - How functions are executed
API Reference - Platform API endpoint documentation

Admin Backend Documentation

Admin Backend Overview - Admin server architecture and components
Admin API Reference - Complete admin API endpoint documentation
User Management - Users, organizations, tiers, and feature roles
Early Access Admin - Early access request management
Keycloak Authentication - Keycloak OIDC integration details

New Features

Function Initialization - Separate init step before deployment with UUID generation
Deletion Management - Cancel pending deletions, view deletion status and scheduled deletions
Versioning & Rollback - View deployment history and rollback to previous versions
Enhanced API Keys - Roll, update, enable/disable API keys with pagination support
Execution Details - Get detailed execution information with linked invocations and logs

Key Features

Statistics & Monitoring

User Overview Stats - Aggregated metrics across all user's functions
Per-Function Stats - Detailed metrics for individual functions
Hourly Charts - Request distribution by hour (up to 168 hours)
Daily Charts - Request distribution by day (up to 90 days)
Real-time Metrics - Invocation counts, success/error rates, latency tracking

Authentication System

Keycloak OIDC — Industry-standard authentication provider
Token Introspection — Server-side validation on every request
Legacy JWT Fallback — Backward compatibility during migration
Auto-Migration — Legacy BCrypt users auto-migrated to Keycloak on login
Bi-Directional Sync — User data synchronized between PostgreSQL and Keycloak
User Status Check — Blocked/deleted users rejected on login

Admin Authentication (Keycloak OIDC)

Keycloak Integration - Industry-standard OpenID Connect provider
Token Introspection - Validate tokens via Keycloak introspection endpoint
Role-Based Access - Two admin roles: full_admin (write) and viewer (read)
Two-Layer Middleware - Authentication + authorization guards per route
JWT Claims Parsing - Extract roles from realm_access, resource_access, and scope claims

User Management (Admin)

Soft-Delete - Users marked as deleted instead of physically removed
Status Management - Users can be active, blocked, or deleted
Temporary Passwords - Generate and email one-time passwords for new users
Feature Roles - Grant/remove per-user feature roles via Keycloak
Organizations - Create and manage organizations with member assignments
Tiers - Define service tiers and assign users to them

Container Management

Rootless Podman - Secure container execution without root
Resource Isolation - CPU, memory, and disk limits
Network Isolation - Isolated container networks
Image Building - Automatic function containerization

Data Storage

PostgreSQL - Function metadata, user data, execution history
File System - Function archives and build artifacts

Security

Keycloak OIDC - Industry-standard token-based auth with introspection
API Key Signing - HMAC-SHA256 signatures for function invocations
Container Sandboxing - Isolated execution environments
Replay Protection - 5-minute timestamp window for signed requests
Audit Logging - Complete request and authentication logging

Architecture Overview

System Components

Diagram

┌─────────────────────────────────────────────┐
│    ContainerPub Backend Server              │
│  ┌──────────────────────────────────────┐  │
│  │  API Server (Shelf)                  │  │
│  │  - Function deployment               │  │
│  │  - Function execution                │  │
│  │  - Keycloak OIDC authentication       │  │
│  └──────────────────────────────────────┘  │
│  ┌──────────────────────────────────────┐  │
│  │  Keycloak Client                     │  │
│  │  - Token introspection               │  │
│  │  - User management                   │  │
│  │  - Legacy JWT fallback               │  │
│  └──────────────────────────────────────┘  │
│  ┌──────────────────────────────────────┐  │
│  │  Container Runtime (Podman)          │  │
│  │  - Build images                      │  │
│  │  - Run containers                    │  │
│  │  - Manage resources                  │  │
│  └──────────────────────────────────────┘  │
│  ┌──────────────────────────────────────┐  │
│  │  Database (PostgreSQL)               │  │
│  │  - Function metadata                 │  │
│  │  - User data                         │  │
│  │  - Execution history                 │  │
│  └──────────────────────────────────────┘  │
└─────────────────────────────────────────────┘

Authentication Architecture

Token Flow

dart

Register → Create in Keycloak + PostgreSQL
  ↓
Login → Keycloak Direct Grant (or BCrypt fallback for legacy)
  ↓
API Requests → Token Introspection (Keycloak) → Lookup by keycloak_user_id
  ↓
Token Refresh → Keycloak refresh_token grant
  ↓
Logout → Keycloak session invalidation

Authentication Endpoints

POST /api/auth/register — Create new user account
POST /api/auth/login — Authenticate and receive tokens
POST /api/auth/refresh — Get new access token via refresh_token grant
POST /api/auth/logout — Invalidate session
POST /api/auth/reset-password — Keycloak forgot password flow

API Endpoints

Authentication

POST /api/auth/register - Register new user (Keycloak + PostgreSQL)
POST /api/auth/login - Login with auto-migration support
POST /api/auth/refresh - Refresh access token (Keycloak grant)
POST /api/auth/logout - Logout and invalidate session
POST /api/auth/reset-password - Keycloak forgot password flow

Email Verification (Deprecated)

⚠

Migrating to Keycloak native email verification. These endpoints are retained for backward compatibility.

POST /api/email-verification/send - Send verification OTP
POST /api/email-verification/verify - Verify OTP code
POST /api/email-verification/resend - Resend verification OTP

Functions

POST /api/functions/init - Initialize new function (get UUID)
POST /api/functions/deploy - Deploy function
GET /api/functions - List functions
GET /api/functions/:id - Get function details
DELETE /api/functions/:id - Delete function

Execution

POST /api/functions/:id/invoke - Invoke function
GET /api/functions/:id/executions - Get execution history (paginated)
GET /api/functions/:id/executions/:executionUuid - Get execution details

Versioning & Rollback

GET /api/functions/:id/deployments - Get deployment history (paginated)
POST /api/functions/:id/rollback - Rollback to previous version

Deletion Management

POST /api/functions/:uuid/cancel-deletion - Cancel pending deletion
GET /api/functions/pending-deletions - List all pending deletions
GET /api/functions/:uuid/deletion-status - Get deletion status

API Keys

POST /api/apikey/generate - Generate new API key
GET /api/apikey/:function_id - Get API key info
GET /api/apikey/:function_id/list - List all API keys (paginated)
PUT /api/apikey/:api_key_uuid/roll - Extend expiration
PUT /api/apikey/:api_key_uuid/update - Update validity/name
PUT /api/apikey/:api_key_uuid/enable - Re-enable revoked key
DELETE /api/apikey/:api_key_uuid/revoke - Revoke key (keep history)
DELETE /api/apikey/:api_key_uuid - Delete key permanently

Statistics

GET /api/stats/overview - User overview stats
GET /api/stats/overview/hourly - User hourly chart data
GET /api/stats/overview/daily - User daily chart data
GET /api/functions/:id/stats - Function stats
GET /api/functions/:id/stats/hourly - Function hourly chart data
GET /api/functions/:id/stats/daily - Function daily chart data

Logs

GET /api/functions/:id/logs - Get function logs

Health

GET /health - Server health check

Technology Stack

Language: Dart 3.x
HTTP Server: Shelf
Database: PostgreSQL
Authentication: Keycloak OIDC (legacy JWT fallback)
Container Runtime: Podman (rootless)

Security Model

Container Security

Rootless Execution - No root privileges required
User Namespaces - Isolated user spaces per container
Resource Limits - CPU, memory, disk constraints
Network Isolation - Containers on isolated networks

API Security

Keycloak OIDC - Industry-standard token-based auth
Token Introspection - Server-side validation on every request
HTTPS - Encrypted communications
User Status Check - Blocked/deleted users rejected
Audit Logging - Complete request logging

Users Table

sql

CREATE TABLE users (
  uuid UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  email VARCHAR(255) UNIQUE NOT NULL,
  password_hash VARCHAR(255),           -- Nullable (legacy), managed by Keycloak
  first_name VARCHAR(100),
  last_name VARCHAR(100),
  status VARCHAR(20) DEFAULT 'active'
    CHECK (status IN ('active', 'blocked', 'deleted')),
  temporary_password BOOLEAN DEFAULT false,
  keycloak_user_id VARCHAR(255),        -- Links to Keycloak user
  is_email_verified BOOLEAN DEFAULT false,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

Functions Table

sql

CREATE TABLE functions (
  uuid UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  name VARCHAR(255),
  owner_id UUID REFERENCES users(uuid),
  created_at TIMESTAMP,
  updated_at TIMESTAMP,
  status VARCHAR(50),
  metadata JSONB
);

Executions Table

sql

CREATE TABLE executions (
  uuid UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  function_uuid UUID REFERENCES functions(uuid),
  started_at TIMESTAMP,
  completed_at TIMESTAMP,
  status VARCHAR(50),
  logs TEXT,
  result JSONB
);

Technology Stack

Language: Dart 3.x
HTTP Server: Shelf
Database: PostgreSQL
Authentication: Keycloak OIDC (legacy JWT fallback)
Container Runtime: Podman (rootless)

Security Model

Container Security

Rootless Execution - No root privileges required
User Namespaces - Isolated user spaces per container
Resource Limits - CPU, memory, disk constraints
Network Isolation - Containers on isolated networks

API Security

Keycloak OIDC - Industry-standard token-based auth
HTTPS - Encrypted communications
Token Introspection - Server-side validation on every request
User Status Check - Blocked/deleted users rejected
Audit Logging - Complete request logging

Performance

Cold Start Optimization

Optimized base images
Minimal dependencies
Fast container startup
Cached image layers

Warm Execution

Container reuse
Memory caching
Connection pooling
Optimized runtime

Monitoring

Metrics

Function execution time
Memory usage
CPU usage
Error rates
Request count

Logging

Function stdout/stderr
API request logs
Authentication events
System events
Audit trail

Deployment

Requirements

Dart 3.x SDK
PostgreSQL database
Podman container runtime
Keycloak server (for auth)
Linux/macOS (Podman support)

Configuration

Keycloak environment variables (URL, realm, client)
Database connection string
JWT secret (legacy fallback)

Running

dart

cd dart_cloud_backend
dart pub get
dart run bin/server.dart

Development

Project Structure

Diagram

dart_cloud_backend/
├── bin/
│   └── server.dart          # Entry point
├── lib/
│   ├── router.dart          # Route definitions
│   ├── handlers/
│   │   └── auth_handler.dart # Auth endpoints (Keycloak)
│   ├── middleware/
│   │   └── auth_middleware.dart # Keycloak introspection + legacy JWT
│   └── services/
│       ├── user_sync_service.dart # Bi-directional Keycloak ↔ PostgreSQL sync
│       └── token_service.dart # Legacy Hive token storage (deprecated)
├── packages/
│   ├── database/            # PostgreSQL entity layer
│   ├── email_service/       # Email sending
│   ├── otp_service/         # OTP generation (deprecated, migrating to Keycloak)
│   ├── name_generator/      # Random name generation
│   ├── cleanup_worker/      # Background cleanup
│   └── authentication/      # Auth utilities
└── pubspec.yaml

Key Files

router.dart - Route configuration
auth_handler.dart - Authentication logic (Keycloak + legacy fallback)
auth_middleware.dart - Token introspection and validation
token_service.dart - Legacy Hive token storage (deprecated)
user_sync_service.dart - Bi-directional Keycloak ↔ PostgreSQL sync

Next Steps

Read Statistics & Monitoring for dashboard metrics documentation
Read Authentication System for complete JWT auth flow documentation
Read Admin Authentication for Keycloak OIDC auth documentation
Read Admin Backend Overview for admin server architecture
Read Admin API Reference for complete admin API documentation
Read Architecture Overview for detailed system design
Check API Reference for complete platform API documentation
Explore CLI Documentation for client-side tools
Review Development Guide for contributing

Support

For issues, questions, or contributions:

GitHub: liodali/ContainerPub
Documentation: ContainerPub Docs