cloudillo-action 0.8.9

Federated activity system for Cloudillo: signed posts, comments, reactions, and a declarative Action DSL
Documentation

What is Cloudillo?

Online collaboration platforms typically fall into two categories:

  1. Cloud-based services — convenient but may raise concerns about privacy, data ownership, and censorship.
  2. Self-hosted applications — provide control but are challenging to set up and don't integrate well with each other.

Cloudillo bridges this gap. It is a federated, self-hosted web application platform that gives you the convenience of cloud services without sacrificing privacy or control over your data. Each user runs their own Cloudillo instance and connects with others through open federation protocols — no central server required.

Key Features

  • Federation — Instances communicate using signed activity tokens, so users on different servers can interact seamlessly
  • Real-time collaboration — Collaborative document editing via CRDT (Yjs), plus a Firebase-style real-time database over WebSocket
  • File storage — Content-addressed immutable blob storage with automatic image processing and variant generation
  • Social features — Posts, comments, reactions, and community spaces with role-based access control
  • Identity portability — Your identity is a cryptographic key pair, not an account on someone else's server
  • Self-hosted — Runs on your own hardware with automatic TLS via ACME/Let's Encrypt

Architecture

Cloudillo-RS is a Rust workspace with 20 crates organized into three layers:

Layer Crates Purpose
Feature crates cloudillo-action, cloudillo-auth, cloudillo-file, cloudillo-crdt, cloudillo-rtdb, cloudillo-profile, and more Business logic for each feature area
Core cloudillo, cloudillo-types, cloudillo-core Shared types, middleware, extractors, scheduling, and the application builder
Adapters auth-adapter-sqlite, meta-adapter-sqlite, blob-adapter-fs, rtdb-adapter-redb, crdt-adapter-redb Pluggable storage backends behind trait interfaces

Key technologies: Axum (HTTP), SQLite (metadata and auth), redb (real-time and CRDT storage), Tokio (async runtime), Yrs (Yjs CRDT).

The codebase enforces #![forbid(unsafe_code)] — no unsafe anywhere.

Getting Started

Prerequisites

  • Rust 1.75+ (2021 edition)
  • For production deployment:
    • DNS A (or CNAME) records for your domain and cl-o.<domain> pointing to your server IP
    • Ports 443 (HTTPS) and 80 (HTTP / ACME challenges) open

Build and Run

# Build everything
cargo build

# Build the server binary
cargo build -p cloudillo-server

# Run (see Configuration below for all env vars)
BASE_ID_TAG=dev cargo run -p cloudillo-server

# Optimized release build (LTO, stripped)
cargo build --profile release-lto

Frontend

The server serves a frontend built from the separate cloudillo/cloudillo repository. You need Node.js 22+ and pnpm.

# Clone and build the frontend
git clone https://github.com/cloudillo/cloudillo.git
cd cloudillo
pnpm install --frozen-lockfile
pnpm -r --filter '!@cloudillo/storybook' build

# Assemble into the dist directory (adjust path to your cloudillo-rs checkout)
mkdir -p ../cloudillo-rs/dist/apps
cp -r shell/dist/* ../cloudillo-rs/dist/
for app in apps/*/; do
  name=$(basename "$app")
  if [ -d "$app/dist" ]; then
    cp -r "$app/dist" "../cloudillo-rs/dist/apps/$name"
  fi
done

The server looks for these files in DIST_DIR (./dist by default).

Configuration

The server is configured through environment variables:

Variable Description Default
BASE_ID_TAG Tenant identifier / domain (required) —
LOCAL_ADDRESS Comma-separated server IP(s) for DNS validation —
BASE_APP_DOMAIN App domain for the base tenant BASE_ID_TAG
BASE_PASSWORD Initial admin password —
ACME_EMAIL Email for Let's Encrypt certificates —
MODE standalone, proxy, or stream-proxy standalone
LISTEN HTTPS bind address 127.0.0.1:1443
LISTEN_HTTP HTTP bind address (ACME challenges) 127.0.0.1:1080
DB_DIR Database directory ./data
DATA_DIR Blob storage directory ./data
DIST_DIR Frontend static files directory ./dist
RUST_LOG Log level filter —
DISABLE_CACHE Set to any value to disable HTTP caching —

For Docker deployment instructions, see DOCKER.md.

Development

# Run all tests
cargo test

# Run tests for a specific crate
cargo test -p cloudillo

# Lint (matches CI strictness)
cargo clippy -- -D warnings

# Check formatting (uses hard tabs)
cargo fmt --check

# Apply formatting
cargo fmt

CI runs tests, formatting checks, and Clippy on every push and pull request.

Project Status

Cloudillo is in alpha. The core platform is functional, but APIs may change and some features are still in development. Feedback, bug reports, and contributions are welcome.

License

LGPL-3.0-only

Links