5-Minute Quickstart

In this tutorial, you will create a simple HTTP application, configure its app.toml manifest, deploy it to MicroFly, and verify features like automated blue/green activation and scale-to-zero.

---

Step 1: Create a Sample Application

MicroFly runs native Linux binaries (written in Go, Rust, C, C++, Zig, or packaged with tools like PyInstaller / Bun) as well as standalone executable Java .jar files.

Let's create a minimal Go web server as an example:

mkdir -p my-sample-app
cd my-sample-app

Create main.go:

package main

import (
	"flag"
	"fmt"
	"net/http"
	"os"
)

func main() {
	port := flag.String("port", "3000", "Port to listen on")
	flag.Parse()

	// MicroFly injects PORT and metadata via environment variables
	if envPort := os.Getenv("PORT"); envPort != "" {
		*port = envPort
	}

	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		app := os.Getenv("MICROFLY_APP")
		rel := os.Getenv("MICROFLY_RELEASE")
		fmt.Fprintf(w, "Hello from %s (release: %s)!\n", app, rel)
	})

	http.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
		w.WriteHeader(http.StatusOK)
		w.Write([]byte("ok\n"))
	})

	fmt.Printf("Server listening on port %s\n", *port)
	if err := http.ListenAndServe(":"+*port, nil); err != nil {
		fmt.Fprintf(os.Stderr, "Server failed: %v\n", err)
		os.Exit(1)
	}
}

Compile the binary:

go build -o web-server main.go
chmod +x web-server

---

Step 2: Create the app.toml Manifest

In the root of your application directory (my-sample-app), create app.toml:

schema_version = 1
name = "my-sample-app"
type = "binary"
domain = ["mysite.local", "api.mysite.local"]

[runtime]
args = ["./web-server", "--port", "{PORT}"]

[scale]
scale_to_zero = true
idle_timeout = "30s"

[health_check]
path = "/healthz"
expected_status = 200
interval = "100ms"
timeout = "3s"

[resources]
memory_limit = "256MB"
cpu_quota = 1.0

Key manifest details:

• domain: Hostnames routed to this application by the MicroFly ingress layer.
• args: The command to execute. {PORT} is replaced with an assigned unprivileged port.
• scale_to_zero = true: Automatically stops the workload when no HTTP requests are received for idle_timeout.
• health_check: Pre-flight verification required before a candidate release receives traffic.

---

Step 3: Deploy the Application

Deploy your application directory to MicroFly:

sudo microfly deploy --dir . my-sample-app

Output:

deployed my-sample-app release 20260903T100000.123456789Z-000001

What Happened Behind the Scenes?

1. Archive & Verification: The directory was packed and safely extracted into an immutable release directory: /var/lib/microfly/apps/my-sample-app/releases/<timestamp>-000001
2. Hardened Transient Unit: MicroFly generated a transient systemd service unit running as the microfly-app user with an empty capability set and read-only filesystem mounts.
3. Health Check: MicroFly performed HTTP GET requests against http://127.0.0.1:<port>/healthz to confirm the app was healthy.
4. Blue/Green Activation: Once healthy, the ingress router atomically cut over traffic to the new release.
5. Scale to Zero: Because scale_to_zero = true was set, the process was then scaled down to 0 to conserve resources until the first request arrived.

---

Step 4: Test Ingress Routing and Cold Start

Test your application by sending an HTTP request to MicroFly's ingress listener (127.0.0.1:8000) specifying the Host header configured in app.toml:

curl -i -H "Host: mysite.local" http://127.0.0.1:8000/

Response:

HTTP/1.1 200 OK
Date: Thu, 03 Sep 2026 10:00:05 GMT
Content-Length: 64
Content-Type: text/plain; charset=utf-8

Hello from my-sample-app (release: 20260903T100000.123456789Z-000001)!

Notice the fast response: even when cold-starting from zero processes, MicroFly's systemd transient unit booted, bound its listening socket, and served the request in under 250 milliseconds.

---

Step 5: Inspect Application Status and Metrics

Check the live status of the application:

sudo microfly status my-sample-app

Output:

App Name:       my-sample-app
Type:           binary
Status:         running
Active Release: 20260903T100000.123456789Z-000001
Assigned Port:  3000
Process PID:    78912
Memory (RSS):   4.82 MB
Domains:        mysite.local, api.mysite.local
Restart Count:  0
Restart Policy: on-failure
Scale to Zero:  true (min instances: 0)

List all managed applications:

sudo microfly apps list

Stream live application logs:

sudo microfly logs -f my-sample-app

---

Step 6: Next Steps

• Setup Reverse Proxy Integration (Caddy / Nginx) to serve public traffic with automatic HTTPS.
• Configure Encrypted Secrets and Dynamic Environment Variables.
• Enable Push-to-Deploy via Git.
• Learn about Persistent Storage Mounts and Cron Jobs.