flynn

README

Flynn

Flynn is an open source platform as a service. It runs anything that runs on Linux: 12-factor web apps, background workers, and stateful services.

This repository is a community fork of flynn/flynn. The original project is unmaintained. The goal of this fork is to keep Flynn running on modern Linux, with current language stacks, current database versions, and the operational features people actually use.

Discord · GitHub · Releases

What Flynn does

A Flynn cluster is a set of Ubuntu hosts. You deploy apps with git push or Docker, attach managed datastores, and the platform handles scheduling, routing, logs, TLS, and rolling updates.

Area	What you get
Deploy	git push with Heroku-24 buildpacks, git push from a Dockerfile (container stack), or flynn docker:push of a local image
Runtime	Process types from a Procfile, scale with flynn scale, named runtimes (small / medium / large), zero-downtime deploys with automatic rollback
Routing	HTTP/HTTPS and TCP routes, custom domains, path-based HTTP routes (flynn-host route:add), HTTP/2, automatic Let's Encrypt certificates
Datastores	PostgreSQL 16, MariaDB 10.11, MongoDB 7.0, Redis, Kafka 3.9 (KRaft), ClickHouse
Ops	Dashboard, CLI, ZFS volumes, clustered log aggregation, app export/import, host firewall (flynn-host firewall)
Isolation	User jobs cannot reach other jobs or internal APIs on the overlay; they use routes and injected datastore URLs

A feature comparison with Heroku, Vercel, Fly.io, Render, Canine, and Railway is in docs/content/comparison.md.

Flynn components (controller, router, scheduler, appliances, …) are themselves apps on the cluster. You scale and update the platform with the same APIs you use for your own software.

Status

This fork is a work in progress. It targets Ubuntu 24.04 LTS (amd64) as the host OS and Go 1.24 as the compiler.

It is suitable for development, staging, and small production workloads. Read Security and Production before putting sensitive data on a cluster. Database appliances are not yet tuned for very large datasets or high write volume.

Requirements

• OS: Ubuntu 24.04 LTS amd64
• Hosts: 2 GB RAM, 40 GB disk, and 2 CPU cores per node as a minimum; more for appliances and builds
• HA: three or more nodes. A single node (SINGLETON) is fine for trying Flynn; do not use it as production
• Network: all UDP and TCP between cluster members; externally, open 80, 443, and optionally 3000–3500 for user TCP routes. Internal Flynn ports must not be on the public internet. After install, flynn-host firewall manages peer IPs and extra TCP ports on the host UFW rules.
• Storage: ZFS. The installer can create a zpool on a dedicated disk (--zpool-create-device); a sparse file is the default and is not recommended for production

Install the CLI

The flynn CLI runs on 64-bit Linux, macOS (Intel and Apple Silicon), and Windows. 32-bit x86 is not supported.

curl -fsSL https://github.com/randy-girard/flynn/releases/latest/download/install-flynn-cli | sudo bash

Pin a version with --version, or set FLYNN_GITHUB_REPO / --repo if you are installing from a different fork.

After you bootstrap a cluster, add it:

flynn cluster:add -p <tls-pin> <name> <domain>
flynn login --email <admin@domain>
# or, on a host in the cluster:
sudo flynn-host cli-add-command

Log in with the administrator created at bootstrap (--admin-email / --admin-password, or a TTY prompt). Run flynn help for the full command list.

Install a cluster

On each Ubuntu 24.04 host:

curl -fsSL https://github.com/randy-girard/flynn/releases/latest/download/install-flynn | sudo bash

That installs flynn-host, container images, and a systemd unit.

Three-node cluster using a discovery API you run (there is no public hosted service). --init-discovery requires DISCOVERY_SERVER:

# first node (example URL; use your own discovery API)
sudo DISCOVERY_SERVER=https://discovery.example.com flynn-host init --init-discovery
# prints https://discovery.example.com/clusters/<id>

# other nodes
sudo flynn-host init --discovery https://discovery.example.com/clusters/<id>

sudo systemctl start flynn-host

On one node, point DNS (CLUSTER_DOMAIN A records to every host, plus a wildcard CNAME) and bootstrap:

sudo \
  CLUSTER_DOMAIN=example.com \
  flynn-host bootstrap \
  --min-hosts 3 \
  --discovery https://discovery.example.com/clusters/<id>

flynn-host presents that cluster id as a bearer token when talking to the discovery API. GET /.well-known/cluster is not a public join URL. Combine --discovery with --peer-ips so bootstrap only contacts those hosts.

You can skip discovery and pass --peer-ips 10.0.0.1,10.0.0.2,10.0.0.3 instead. To run discovery on the cluster itself, bootstrap one node with --peer-ips, install the discovery plugin, then join extra nodes with that token. Step-by-step instructions are in Manual installation. Production notes (dedicated ZFS, blobstore backends, backups) are in Production.

Bootstrap uses a self-signed certificate. Configure ACME/Let's Encrypt next so the dashboard, controller, and app routes can get trusted TLS:

sudo flynn-host acme:configure --email=admin@example.com --agree-tos
sudo flynn-host acme:enable-system-routes

CLUSTER_DOMAIN and *.CLUSTER_DOMAIN must resolve to the cluster (HTTP-01). Use --staging while testing (untrusted certs). More detail is in HTTPS and Let's Encrypt.

Local development cluster

The root Vagrantfile uses the bento/ubuntu-24.04 box.

• vagrant up builder — build VM (setup.sh installs Go, Docker, ZFS, and appliance test deps)
• vagrant up node1 node2 node3 — a three-node cluster on a host-only network
• script/vagrant-smoke.sh / make vagrant-smoke — acceptance suite (--item quick); also status / ssh / up / reload / stop / destroy for .vagrant (aliases restart / halt / teardown)
• script/vagrant.sh / make vagrant-setup — laptop loop in .vagrant-dev (dev-builder at 192.168.57.10 and dev-node1 at 192.168.57.20 by default); artifacts in ./build-dev so they do not overwrite smoke’s ./build; reload / stop / destroy (aliases restart / halt / teardown). Shared code is under script/vagrant/.

See Vagrant and Development.

Deploy an app

flynn apps:create myapp
# after: sudo flynn-host plugin:install postgres
# this does not provision on the platform appliance
flynn addons:create postgres
git push flynn main            # or: master

git push uses the heroku-24 stack by default (buildpacks). To build a Dockerfile on the cluster with BuildKit:

flynn stack:set container
git push flynn main

To push an image you already built locally:

flynn -a myapp docker:push myimage:tag
flynn -a myapp scale app=1

Apps bind HTTP on $PORT (8080 for the default web process, not a random port). Flynn adds https://$APP.$CLUSTER_DOMAIN automatically. Custom domains, process types, logs, named runtimes (flynn limit:runtime), and Let's Encrypt are covered in Apps and Basics.

Buildpacks (heroku-24)

These buildpacks ship in slugbuilder and are auto-detected:

Go, Node.js, Python, Ruby, PHP, Java (Maven), Gradle, Scala, Clojure, and static files. Custom buildpacks: BUILDPACK_URL or a .buildpacks file (multi-buildpack).

Language notes live under docs/content/languages.

Datastores

The built-in Postgres appliance is the platform database (controller, blobstore). Tenant databases do not live on it. flynn addons:create postgres uses flynn-plugin-postgres (one app, one volume, one node per resource) and does not create a role on the platform appliance. Other engines are plugins (flynn-host plugin:install; see Plugins). Provision those from an app with flynn addons:create <provider>. Connection URLs are injected as environment variables (DATABASE_URL, REDIS_URL, KAFKA_URL, …). User jobs reach appliances at the leader hostname Flynn put in those URLs, not at internal *.discoverd names.

Provider	Engine	Default topology	Notes
platform postgres app	PostgreSQL 16	HA (primary + sync + async)	Platform appliance. Not addons:create postgres. PostGIS, pgRouting, TimescaleDB. System apps only
postgres	PostgreSQL 16	One node, own app and volume	Plugin flynn-plugin-postgres. flynn addons:create postgres. Not the platform appliance. Resize by follow, wait, promote. Instance volumes are not in flynn-host backup
mysql	MariaDB 10.11	HA, started on first provision	Plugin. flynn-host plugin:install mysql
mongodb	MongoDB 7.0	Replica set, started on first provision	Plugin. flynn-host plugin:install mongodb. Resize with flynn mongodb:scale <n> (no followers)
redis	Redis (Ubuntu 24.04 package)	Single process, AOF on a volume	Plugin. flynn-host plugin:install redis. Followers via flynn redis:follow. Not in flynn-host backup; caching and development
kafka	Apache Kafka 3.9 (KRaft, no ZooKeeper)	3 brokers (1 on singleton)	Plugin. flynn-host plugin:install kafka. Resize with flynn kafka:scale <n> (no followers)
clickhouse	ClickHouse + Keeper	3 replicas (1 on singleton)	Plugin. flynn-host plugin:install clickhouse. Resize with flynn clickhouse:scale <n> (no followers)

The platform Postgres appliance, MariaDB, and MongoDB use the sirenia/replica-set state machines so a primary failure can promote a replica without split-brain. Tenant Postgres from the plugin is one node (follow, wait, promote). Redis does not replicate. Details: Databases.

HTTPS and Let's Encrypt

Install the Let's Encrypt plugin, register an ACME account, then turn HTTPS on for hostnames:

sudo flynn-host plugin:install letsencrypt
sudo flynn-host letsencrypt:configure --email=admin@example.com --agree-tos
sudo flynn-host letsencrypt:status
sudo flynn-host letsencrypt:enable-system-routes   # controller, dashboard, …
flynn route:add http www.example.com
flynn letsencrypt:enable www.example.com

Useful flags on configure: --staging (Let's Encrypt staging, untrusted certs) and --directory-url (another ACME CA). Check flynn-host letsencrypt:status anytime.

The name on the certificate must resolve to the cluster and pass HTTP-01 (ports 80/443 open). You can still attach your own cert with --tls-cert / --tls-key. After system routes have a public cert, clear the bootstrap TLS pin: flynn cluster:refresh --clear. See Apps — HTTPS.

Architecture (short)

┌─────────────┐     HTTPS/TCP      ┌────────────┐
│   clients   │ ─────────────────► │   router   │  (every host)
└─────────────┘                    └─────┬──────┘
                                         │ discoverd
     git push / docker push              ▼
┌─────────────┐                    ┌────────────┐     ┌──────────────┐
│     CLI     │ ─────────────────► │ controller │────►│  scheduler   │
│  dashboard  │                    └────────────┘     └──────┬───────┘
└─────────────┘                                              │
                                                             ▼
                                                   ┌─────────────────┐
                                                   │   flynn-host    │  libcontainer jobs
                                                   │  ZFS · flannel  │  overlay VXLAN
                                                   └─────────────────┘

• flynn-host is the only process that does not run in a container. It starts jobs, owns volumes, and speaks to the rest of the cluster
• discoverd is Raft-backed service discovery and leader election
• flannel gives every job an overlay IP
• controller is the app/release/formation API (Heroku-inspired)
• blobstore holds slugs, git caches, and image layers (Postgres by default; S3, GCS, or Azure for production)

Longer write-up: Architecture.

Documentation

Topic	Page
Install a cluster	Installation · Manual · Vagrant
First deploy	Basics · Apps · Docker
Datastores	PostgreSQL · MariaDB · MongoDB · Redis · Kafka · ClickHouse
Operate	Production · Security · Stability · HTTPS / ACME
Develop	Development · Contributing
CLI	CLI · cli/README.md
Docs index	docs/README.md

Develop

Needs Ubuntu 24.04 with Docker, ZFS, and the packages in setup.sh (the Vagrant builder VM installs them).

git clone https://github.com/randy-girard/flynn.git
cd flynn
vagrant up builder            # Ubuntu 24.04 build VM
make help                     # list Makefile targets
make                          # script/build-flynn (host binaries)
script/bootstrap-flynn        # single-node cluster from local images
make test-unit                # go test; uses Docker on macOS/Windows

make test-integration boots a nested cluster. For most cluster/docs/CLI changes run script/vagrant-smoke.sh --item quick (1-node boot, git-push, docker-push; no tenant database, no plugin install). Upgrade, backup, HA, and plugin changes should use singleton/ha; the pre-release gate is the enabled matrix (singleton then ha). See Development and AGENTS.md.

License

BSD 3-Clause. Copyright (c) 2013–2018 Prime Directive, Inc. and contributors.

The Flynn name and logo are trademarks of Prime Directive, Inc. See Trademark guidelines.