DigitalOcean Terraform Module

The terraform-digitalocean-flo module provisions a production-ready Flo node on DigitalOcean. It handles the droplet, firewall, cloud-init installation, and optional cluster formation in a single terraform apply.

Registry: floruntime/flo/digitalocean

Quick Start

module "flo" {
  source  = "floruntime/flo/digitalocean"
  version = "~> 0.0.1"
 
  ssh_key_ids = [data.digitalocean_ssh_key.main.id]
  flo_version = "v0.1.0" # pin in production
}
 
output "endpoint"  { value = module.flo.listen_endpoint }
output "dashboard" { value = module.flo.dashboard_url }

terraform init
terraform apply
 
# Point the CLI at your new node
flo --server "$(terraform output -raw listen_endpoint)" kv set hello world

What It Provisions

The cloud-init script runs once per droplet. It:

1. Installs curl and ca-certificates if needed
2. Downloads and installs flo via the install script (optionally pinned to a version)
3. Creates a flo system user
4. Writes /etc/flo/flo.toml from the module inputs
5. Creates and chowns the data directory
6. Writes and enables a systemd unit (flo.service)

Port Layout

Flo derives all secondary ports from listen_port:

The firewall automatically opens the correct ports based on your settings:

• Wire protocol — always open, gated by api_allowed_cidrs
• Dashboard — open when enable_dashboard = true, gated by dashboard_allowed_cidrs
• Metrics — open only when expose_metrics = true
• Raft + Gossip — open when cluster_enabled = true, gated by cluster_allowed_cidrs

Single Node

The simplest deployment — one droplet with all defaults:

terraform {
  required_version = ">= 1.5.0"
  required_providers {
    digitalocean = { source = "digitalocean/digitalocean", version = ">= 2.40" }
  }
}
 
provider "digitalocean" {
  token = var.do_token
}
 
data "digitalocean_ssh_key" "main" {
  name = var.ssh_key_name
}
 
module "flo" {
  source  = "floruntime/flo/digitalocean"
  version = "~> 0.0.1"
 
  ssh_key_ids = [data.digitalocean_ssh_key.main.id]
 
  environment = "prod"
  region      = "lon1"
  flo_version = "v0.1.0"
}
 
output "ipv4_address"  { value = module.flo.ipv4_address }
output "listen_endpoint" { value = module.flo.listen_endpoint }
output "dashboard_url"   { value = module.flo.dashboard_url }

terraform apply -var-file=variables.tfvars
 
flo --server "$(terraform output -raw listen_endpoint)" kv set hello world
open "$(terraform output -raw dashboard_url)"

3-Node Cluster

Provision three droplets wired together via reserved IPs so the gossip seed list is stable from the first apply:

locals {
  node_ids    = [1, 2, 3]
  listen_port = 9000
  gossip_port = local.listen_port + 600
}
 
# Reserve stable IPs for each node
resource "digitalocean_reserved_ip" "node" {
  for_each = toset([for id in local.node_ids : tostring(id)])
  region   = "lon1"
}
 
# Build the seed list from those IPs
locals {
  seeds = [
    for id in local.node_ids :
    "${digitalocean_reserved_ip.node[tostring(id)].ip_address}:${local.gossip_port}"
  ]
}
 
module "flo" {
  for_each = toset([for id in local.node_ids : tostring(id)])
  source   = "floruntime/flo/digitalocean"
  version  = "~> 0.0.1"
 
  ssh_key_ids = [data.digitalocean_ssh_key.main.id]
 
  environment = "prod"
  region      = "lon1"
  flo_version = "v0.1.0"
  listen_port = local.listen_port
 
  cluster_enabled = true
  cluster_node_id = tonumber(each.key)
  cluster_seeds   = local.seeds
}
 
# Attach each reserved IP to its droplet
resource "digitalocean_reserved_ip_assignment" "node" {
  for_each   = module.flo
  ip_address = digitalocean_reserved_ip.node[each.key].ip_address
  droplet_id = each.value.droplet_id
}

After apply, point your CLI at any node:

flo --server "$(terraform output -json listen_endpoints | jq -r '."1"')" \
  kv set cluster ok

The cluster bootstraps automatically — the first node to come up forms the cluster, and the rest join via the seed list.

Configuration Reference

Required

Naming & Placement

Droplet Features

Firewall

Flo Installation

Flo Runtime

Cluster

Persistent Storage

By default Flo writes to the droplet's root disk, which means a terraform apply -replace=... wipes all data. Set volume_size > 0 to provision a DigitalOcean block-storage volume, attach it at boot, and mount it at data_dir. The volume carries prevent_destroy = true, so it survives droplet replacement.

module "flo" {
  source  = "floruntime/flo/digitalocean"
  version = "~> 0.0.2"
 
  ssh_key_ids = [data.digitalocean_ssh_key.me.id]
  flo_version = "v0.1.0"
 
  volume_size = 50  # GB — survives droplet replacement
}

Outputs

Operational Notes

Service management

Flo runs as the flo system user under systemd:

ssh root@$(terraform output -raw ipv4_address)
 
# View logs
journalctl -u flo -f
 
# Restart
systemctl restart flo
 
# Check status
systemctl status flo

Data directory

Data lives in /var/lib/flo (owned by flo:flo, mode 0750). The systemd unit has ProtectSystem=strict with only ReadWritePaths=<data_dir> — Flo cannot write elsewhere on the filesystem. When volume_size > 0, that path is the mount point for the attached block-storage volume; cloud-init formats blank volumes and adds an /etc/fstab entry with nofail,discard so the mount survives reboots.

Rolling config changes

Cloud-init runs only on first boot. To roll a new config:

In-place (no droplet replacement):

ssh root@<ip> 'vim /etc/flo/flo.toml && systemctl restart flo'

Immutable (replace the droplet):

terraform apply -replace=module.flo.digitalocean_droplet.this

Resizing

To resize a running droplet:

terraform apply -var="droplet_size=s-4vcpu-8gb"

This triggers a DO resize (which power-cycles the droplet). No data loss — Flo replays its log on restart.

Dashboard security

The dashboard exposes administrative APIs. Never leave dashboard_allowed_cidrs open to 0.0.0.0/0 in production. Use one of:

# Option 1: Restrict to your office/home IP
dashboard_allowed_cidrs = ["203.0.113.5/32"]
 
# Option 2: Bind to private interface, access via SSH tunnel
dashboard_bind_address = "10.0.0.2"  # private VPC IP
 
# Then: ssh -L 9002:localhost:9002 root@<ip>

Metrics scraping

The metrics port is not opened on the firewall by default. To scrape Prometheus metrics externally:

expose_metrics         = true
metrics_allowed_cidrs  = ["10.0.0.0/16"] # only your VPC

Or scrape locally via the DigitalOcean monitoring agent (which runs on-loopback).

Upgrading Flo

To upgrade Flo on an existing droplet:

# SSH in and run the installer with the new version
ssh root@<ip> 'curl -fsSL https://raw.githubusercontent.com/floruntime/flo/master/scripts/install.sh | sh -s -- --version v0.2.0'
 
# Restart
ssh root@<ip> 'systemctl restart flo'

For a clean rebuild, bump flo_version and replace the droplet:

terraform apply -var="flo_version=v0.2.0" -replace=module.flo.digitalocean_droplet.this

Publishing to the Terraform Registry

The module is designed for the public Terraform Registry. It lives in its own repo at github.com/floruntime/terraform-digitalocean-flo and follows the terraform-<PROVIDER>-<NAME> naming convention. Once pushed and tagged, the registry discovers it automatically — consumers reference it as:

source  = "floruntime/flo/digitalocean"
version = "~> 0.0.1"

Next Steps

• Configuration reference — understand flo.toml
• Clustering deep-dive — SWIM gossip and Raft consensus internals
• Docker deployment — run Flo with Docker Compose