MicroFly Documentation ​

Welcome to the official technical documentation for MicroFly, a fast, robust, single-host Application Platform-as-a-Service (PaaS) designed specifically for Linux servers, virtual machines, and edge environments.

What is MicroFly? ​

MicroFly bridges the gap between complex container orchestrators (like Kubernetes or Nomad) and simple process supervisors (like systemd or Supervisord). It gives you the developer experience of modern cloud platforms (like Fly.io or Heroku)—Git push deployments, automated blue/green zero-downtime rollouts, scale-to-zero, encrypted secrets, persistent storage, and preview environments—running directly on bare metal or virtual machines with virtually zero overhead.

Unlike Docker-based platforms, MicroFly executes native Linux binaries and executable JARs directly using hardened systemd transient units. This eliminates the memory, filesystem, and networking overhead of container engines while providing rigorous kernel-level isolation.

+-------------------------------------------------------------------------+
|                              INTERNET                                   |
+-------------------------------------------------------------------------+
                                    |
                                    v (ports 80/443, TLS / ACME)
+-------------------------------------------------------------------------+
|                  Reverse Proxy (Caddy / Nginx / Apache)                 |
+-------------------------------------------------------------------------+
                                    |
                                    v (HTTP loopback :8000)
+-------------------------------------------------------------------------+
|                           MicroFly Daemon                               |
|                                                                         |
|  +--------------------+  +--------------------+  +-------------------+  |
|  |  HTTP Router       |  |  Supervisor        |  |  Metrics (:9090)  |  |
|  |  - Host routing    |  |  - Blue/Green      |  |  - Prometheus     |  |
|  |  - Scale-to-zero   |  |  - Crash recovery  |  |  - Cold start     |  |
|  |  - Idle timers     |  |  - Release history |  |  - RSS memory     |  |
|  +--------------------+  +--------------------+  +-------------------+  |
|                                                                         |
|  +--------------------+  +--------------------+  +-------------------+  |
|  |  Admin Socket      |  |  Secrets Engine    |  |  Webhook (:8082)  |  |
|  |  - /run/.../admin  |  |  - AES-GCM-256     |  |  - GitHub HMAC    |  |
|  |  - SO_PEERCRED     |  |  - Online rotation |  |  - GitLab HMAC    |  |
|  +--------------------+  +--------------------+  +-------------------+  |
+-------------------------------------------------------------------------+
                                    |
          +-------------------------+-------------------------+
          | (systemd-run transient services, UID: microfly-app)
          v                                                   v
+-----------------------------------+   +---------------------------------+
| Workload 1: App A (Port 3000)     |   | Workload 2: App B (Port 3001)   |
| - ProtectSystem=strict            |   | - ProtectSystem=strict          |
| - CapabilityBoundingSet=empty     |   | - CapabilityBoundingSet=empty   |
| - PrivateTmp / Invisible Proc     |   | - PrivateTmp / Invisible Proc   |
| - Persistent Volume: data/        |   | - Persistent Volume: data/      |
+-----------------------------------+   +---------------------------------+

Key Highlights ​

• Zero-Overhead Workload Isolation: Runs native binaries and standalone JARs in transient systemd service units with stripped capabilities, read-only root filesystems, private /tmp, and isolated process tables.
• Scale-to-Zero & Fast Cold Starts: Inactive applications automatically stop after an idle timeout. The ingress proxy buffers incoming requests, awakens the service via systemd in ~200ms, and forwards the connection transparently.
• Blue/Green Deployments & Instant Rollbacks: Candidate releases undergo HTTP health checks before traffic shifts. Instant zero-downtime rollbacks return to any previous release in milliseconds.
• Git Push Deployments: Push directly to your server via git push production main or deploy preview feature branches (git push production feature/my-feature).
• Post-Quantum Encrypted Secrets: Secrets are protected using quantum-resistant NIST FIPS 203 ML-KEM-768 key encapsulation combined with AES-256-GCM. Master keys can be rotated online with atomic rollback protection.
• Ephemeral Preview Environments: Deploy branch builds with automated URL generation and TTL-based expiration that automatically sweep inactive test applications.
• Built-in Storage & Cron: Mount persistent storage directories that persist across releases, enforce disk quotas, and schedule UTC cron tasks without external crontab managers.
• Production Observability: Native Prometheus /metrics endpoint, structured disk logging, real-time log streaming (microfly logs -f), and process crash auto-recovery.

Hardened Without Container Engine Overhead ​

Rather than running a bulky Docker daemon (dockerd, containerd, overlayfs, and virtual network bridges) that consumes hundreds of megabytes of RAM, MicroFly instructs systemd to launch each service as a hardened transient unit backed directly by Linux kernel isolation primitives:

Documentation Roadmap ​

1. Getting Started ​

• Installation Guide: Install on Debian, Ubuntu, and Linux distributions (amd64 and arm64) using official .deb packages or compiling from source.
• 5-Minute Quickstart: Build, configure, and deploy your first native web application from scratch.
• Reverse Proxy Setup: Configure Caddy (recommended), Nginx, or Apache for automated HTTPS, Let's Encrypt certificates, and ingress forwarding.

2. Configuration Reference ​

• Application Manifest (app.toml): Complete schema documentation for runtime arguments, scale-to-zero, storage mounts, cron jobs, webhooks, and resource bounds.
• Daemon Configuration (microfly.toml): Global host settings, network listeners, paths, and security limits.

3. Guides & Operational Workflows ​

• Deployments & Blue/Green Releases: CLI directory deployments, pre-deploy release commands, zero-downtime cutover, and instant rollbacks.
• Custom Domains & Ingress Routing: Adding custom domains, DNS setup, automatic Let's Encrypt TLS certificates, and wildcard routing.
• Git Push Deployments: Setting up bare Git repositories, automated post-receive deployments, and branch workflows.
• Branch Preview Environments: Ephemeral staging URLs, preview TTL configuration, sweeper jobs, and preview promotion.
• Continuous Integration & Deployment (CI/CD): Automated deployments with GitHub Actions, GitLab CI, SSH deploy keys, and webhooks.
• Secrets & Environment Management: Post-Quantum ML-KEM-768 hybrid encryption, CLI secret management, environment precedence, and online master key rotation.
• Persistent Storage & Cron: Volume mounts, storage retention across rollbacks, storage limit quotas, and UTC cron execution.
• Monitoring & Logs: Prometheus metrics reference, log streaming, structured disk logs, and process crash auto-recovery.

4. Technical Reference ​

• CLI Reference: Complete command-line reference for all microfly commands, arguments, and flags.
• Admin REST API: Unix-socket HTTP API reference for automated tooling, CI/CD pipelines, and health monitors.
• Security Architecture & Threat Model: Detailed breakdown of sandbox boundaries, systemd restrictions, seccomp filters, and security best practices.