ofelia-template

ofelia-template is the reference production application template and starter scaffold for Project Ofelia. Built under strict Ponytail/KISS principles, it demonstrates a complete, zero-extra-infrastructure SaaS application powered by Crystal v1.20+, PostgreSQL 18, Blueprint HTML views, Pico CSS, Datastar reactive SSE streams, and dual-target Cloud Run / Bare-Metal Podman Quadlet deployment.

Features & Architectural Stack

• Zero-Extra-Infrastructure: PostgreSQL 18 handles domain data, user sessions (kemal-session-postgres), and background job queues (crystal-pg-queue). No Redis, Valkey, or RabbitMQ required.
• No Heavy ORMs: Raw SQL migrations (db/migrations/), micrate, and strongly-typed DB::Serializable domain models.
• No Asset Pipelines: Zero Node.js, Webpack, Vite, or Tailwind dependencies. UI components use stephannv/blueprint compiled HTML, Pico CSS classless styling, and watzon/datastar.cr hypermedia streams.
• Modular Bootloader: Initializers in src/config/initializers/ construct 12-Factor strongly-typed Crystal configuration structs (Ofelia::Core::Config).
• Dual-Target Deployment:
  • Serverless: GCP Cloud Run via deploy/cloud-run.sh with dynamic PORT binding.
  • Bare-Metal: Podman Quadlet systemd units (deploy/bare-metal/*.container) using SELinux :Z volume flags and Red Hat Project Hummingbird PostgreSQL 18 runtime images.
• GPLv3 Licensed: Released under the GNU General Public License v3.0.

Official Repository

The official repository for ofelia-template is hosted on GitLab: https://gitlab.com/renich/ofelia-template

Project Structure

ofelia-template/
├── Containerfile                  # Production multi-stage OCI Containerfile
├── compose.yaml                   # 3-tier local Podman Compose topology
├── db/
│   └── migrations/                # Raw SQL database schema migrations
├── deploy/
│   ├── cloud-run.sh               # GCP Cloud Run deployment script
│   └── bare-metal/                # Podman Quadlet systemd units & README
├── docs/
│   ├── agent-handbook.rst         # Project Ofelia Agent Handbook & Ethos
│   ├── technical/specs/           # Technical specifications
│   └── project/roadmaps/          # Sequenced project roadmaps
├── src/
│   ├── config/initializers/       # Modular config initializers (core, jobs)
│   ├── controllers/               # Kemal route handlers & Datastar SSE endpoints
│   ├── jobs/                      # Background jobs (WelcomeEmailJob)
│   ├── models/                    # DB::Serializable domain models (User)
│   ├── views/                     # Blueprint type-safe HTML components
│   └── main.cr                    # Application entrypoint & worker CLI parser
└── spec/                          # Unit and integration spec test suite

Quickstart & Local Orchestration

1. Start Local Container Stack

Run the PostgreSQL 18 database, Kemal web application, and background worker loop simultaneously via Podman Compose:

podman compose up -d

2. Run Database Migrations

make db:migrate

3. Run Dedicated Worker Process

./bin/ofelia --worker

4. Run Test Suite

crystal spec

Documentation

Full architectural specifications and agent development guidelines are documented in:

• Agent Handbook & Architectural Ethos
• Deployment Topology Spec
• Local Orchestration Spec

License

GNU General Public License v3.0 (GPL-3.0-or-later). See LICENSE for details.

Author

Created and maintained by Rénich Bon Ćirić (renich@woralelandia.com).