Installation Guide

This guide covers installing and configuring the MicroFly daemon and CLI on Linux systems.

---

System Requirements

• Operating System: Linux with systemd and systemd-run (Debian 11+, Ubuntu 20.04+, Debian 13 "trixie", or any systemd-based Linux distribution).
• Architecture: amd64 (x86_64) or arm64 (aarch64).
• Kernel Version: Linux kernel 5.10 or newer (with cgroups v2 recommended).
• Dependencies:
  • git (for Git-push deployment workflows)
  • curl (for health checks and administrative scripts)
  • A reverse proxy: Caddy (recommended), Nginx, or Apache2 (responsible for public TLS and ports 80/443)
  • default-jre-headless (optional, only required if deploying executable Java .jar files)

---

Method 1: Install from Debian Package (Recommended)

MicroFly provides production .deb packages for both amd64 and arm64 architectures. The package automatically sets up directory trees, generates systemd service units, and configures the unprivileged microfly-app execution account.

1. Download or Build the Debian Package

On x86_64 / amd64:

sudo dpkg -i microfly_0.1.0_amd64.deb

On ARM64 (aarch64):

sudo dpkg -i microfly_0.1.0_arm64.deb

(If dependencies such as caddy or git are missing, run sudo apt-get install -f to complete installation).

2. What the Package Configures

The package installer executes a secured postinst script that:

1. Creates directory hierarchies with restrictive POSIX permissions:
   • /var/lib/microfly/apps: Application releases and shared storage (mode 0711)
   • /var/lib/microfly/repos: Bare Git repositories (mode 0700)
   • /var/log/microfly: Daemon and application operational logs (mode 0750)
   • /etc/microfly: Encryption keys and configuration (mode 0700)
2. Creates an unprivileged system user microfly-app (/usr/sbin/nologin).
3. Generates a 256-bit AES-GCM master key at /etc/microfly/master.key (mode 0400) if not present.
4. Deploys the hardened systemd service unit to /lib/systemd/system/microfly.service.

3. Enable and Start the Service

sudo systemctl daemon-reload
sudo systemctl enable --now microfly

Check the service status:

sudo systemctl status microfly

Expected output:

● microfly.service - MicroFly low-overhead binary and Java PaaS
     Loaded: loaded (/usr/lib/systemd/system/microfly.service; enabled; preset: enabled)
     Active: active (running)
   Main PID: 12345 (microfly)
      Tasks: 8 (limit: 4096)
        CPU: 45ms
     CGroup: /system.slice/microfly.service
             └─12345 /usr/bin/microfly daemon --config /etc/microfly/config.toml

Sep 03 08:44:08 host microfly[12345]: microfly daemon listening ingress=127.0.0.1:8000 admin=/run/microfly/admin.sock webhook=127.0.0.1:8082 metrics=127.0.0.1:9090 data=/var/lib/microfly/apps

---

Method 2: Build and Install from Source

If you prefer compiling from source or running the latest development branch:

1. Prerequisites

Ensure Go (version 1.27 or newer), make, and git are installed:

go version

2. Clone and Compile

git clone https://git.larandj.com/zhair/larandj/microfly.git
cd microfly

# Run tests and security verification
make test
make security

# Build binary
make build

# Install binary and systemd service
sudo ./scripts/install.sh

Alternatively, you can build release Debian packages locally:

make deb          # Builds both amd64 and arm64 packages in dist/
make deb-arm64    # Builds only arm64 package
make deb-amd64    # Builds only amd64 package

---

Verifying the Installation

Check the CLI Version

microfly version

Output:

MicroFly v0.1.0 (linux/amd64 go1.27.0)

Check the Daemon Health (Admin Unix Socket)

The MicroFly admin API communicates exclusively over a root-only Unix domain socket:

sudo curl --unix-socket /run/microfly/admin.sock http://microfly/healthz

Output:

ok

Check Prometheus Metrics

MicroFly exposes Prometheus metrics bound to loopback:

curl -s http://127.0.0.1:9090/metrics | grep microfly_

You are now ready to set up your Reverse Proxy and deploy your first application with the Quickstart Guide!