Backend Documentation

Backend server architecture and API reference

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#

┌─────────────────────────────────────────────┐
│    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#

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#

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#

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#

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#

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

Development#

Project Structure#

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

Backend Documentation

Backend Documentation#

Backend Servers#

Dart Cloud Backend (dart_cloud_backend)#

Admin Backend (admin_backend_api)#

Quick Links#

Core Documentation#

Admin Backend Documentation#

New Features#

Key Features#

Statistics & Monitoring#

Authentication System#

Admin Authentication (Keycloak OIDC)#

User Management (Admin)#

Container Management#

Data Storage#

Security#

Architecture Overview#

System Components#

Authentication Architecture#

Token Flow#

Authentication Endpoints#

API Endpoints#

Authentication#

Email Verification (Deprecated)#

Functions#

Execution#

Versioning & Rollback#

Deletion Management#

API Keys#

Statistics#

Logs#

Health#

Technology Stack#

Security Model#

Container Security#

API Security#

Users Table#

Functions Table#

Executions Table#

Technology Stack#

Security Model#

Container Security#

API Security#

Performance#

Cold Start Optimization#

Warm Execution#

Monitoring#

Metrics#

Logging#

Deployment#

Requirements#

Configuration#

Running#

Development#

Project Structure#

Key Files#

Next Steps#

Support#

Dart Cloud Backend (`dart_cloud_backend`)#

Admin Backend (`admin_backend_api`)#