Skip to content
rusthacks.dev
DevOps

Deploying a Rust Service to Fly io Step by Step From Scratch

Deploy a Rust web service to Fly.io from scratch: Dockerfile, fly launch, fly.toml with health checks, secrets, a Postgres attachment, scaling and rollbacks.

14 min read
Summarize in AI
Flat illustration for the post “Deploying a Rust Service to Fly io Step by Step From Scratch”, composed around web.

Fly.io runs your container image as a small virtual machine near your users, puts a TLS-terminating proxy in front of it, and restarts it when it fails. For a Rust service that means three artifacts: a program that behaves well inside a container, a Dockerfile that produces a small image, and a fly.toml that tells the platform how to run it. The first two decide whether the deploy works at all, and they can be tested on a laptop with Docker before any account is involved.

That is how this guide is organized. The service and the image were built and run with Docker 29 on macOS, Rust 1.99, edition 2024 and axum 0.8, and every output below is from those runs. The flyctl commands and fly.toml are the documented flow, but they were not run: no Fly account or flyctl was available, so those sections say what to expect without claiming results. The pieces most likely to break a Fly deploy, which are the bind address, the port, signal handling, configuration errors and the image itself, are all covered by the local part.

A service that behaves inside a container

A container is a process that the platform starts, stops and restarts. Five behaviors make a Rust service easy to run in that setting: it reads its configuration from environment variables, validates it at startup, binds to all interfaces, answers a cheap health check, and shuts down cleanly on SIGTERM.

src/main.rsrust
use std::net::SocketAddr;
use std::process::ExitCode;
use std::time::Duration;

use axum::{Router, routing::get};
use tokio::signal::unix::{SignalKind, signal};

struct Config {
    addr: SocketAddr,
    greeting: String,
}

impl Config {
    /// Read and validate everything at startup. A service that starts with bad configuration
    /// and fails on the first request is harder to diagnose than one that refuses to start.
    fn from_env() -> Result<Config, String> {
        let port = std::env::var("PORT").unwrap_or_else(|_| "8080".into());
        let port: u16 = port.parse().map_err(|_| format!("PORT must be a number between 1 and 65535, got {port:?}"))?;
        let greeting = std::env::var("GREETING").map_err(|_| "GREETING is required".to_string())?;
        if greeting.trim().is_empty() {
            return Err("GREETING must not be empty".into());
        }
        Ok(Config { addr: SocketAddr::from(([0, 0, 0, 0], port)), greeting })
    }
}

async fn shutdown_signal() {
    let mut term = signal(SignalKind::terminate()).expect("install SIGTERM handler");
    let mut int = signal(SignalKind::interrupt()).expect("install SIGINT handler");
    tokio::select! {
        _ = term.recv() => println!("got SIGTERM, draining"),
        _ = int.recv() => println!("got SIGINT, draining"),
    }
}

#[tokio::main]
async fn main() -> ExitCode {
    let config = match Config::from_env() {
        Ok(c) => c,
        Err(e) => {
            eprintln!("config error: {e}");
            return ExitCode::from(78); // EX_CONFIG, so supervisors can tell it from a crash
        }
    };
    let greeting = config.greeting.clone();
    let app = Router::new()
        .route("/healthz", get(|| async { "ok" }))
        .route("/", get(move || async move { greeting.clone() }))
        .route("/slow", get(|| async {
            tokio::time::sleep(Duration::from_secs(2)).await;
            "finished the slow request"
        }));
    let listener = match tokio::net::TcpListener::bind(config.addr).await {
        Ok(l) => l,
        Err(e) => {
            eprintln!("cannot bind {}: {e}", config.addr);
            return ExitCode::from(1);
        }
    };
    println!("listening on {}", config.addr);
    if let Err(e) = axum::serve(listener, app).with_graceful_shutdown(shutdown_signal()).await {
        eprintln!("server error: {e}");
        return ExitCode::from(1);
    }
    println!("clean exit");
    ExitCode::SUCCESS
}

Walk through the choices. Config::from_env reads PORT and GREETING, parses the port into a u16, and returns an error string for anything wrong. The error is printed and the process exits with status 78, EX_CONFIG from sysexits.h. A distinct exit code lets whoever reads the deploy logs tell "misconfigured" from "crashed". The service binds 0.0.0.0, not 127.0.0.1: the proxy reaches your process over the VM's network interface, so a loopback-only listener looks like a dead service. There is a /healthz route that does no work, a / route that returns the configured greeting, and a /slow route that sleeps two seconds, which exists to test shutdown. Finally with_graceful_shutdown waits on a future that completes when SIGTERM or SIGINT arrives, and axum then stops accepting connections and finishes in-flight requests before serve returns.

Configuration errors fail fast and say why

Run the image with nothing set, and then with a bad port:

Text
$ docker run --rm rh-svc:v3
config error: GREETING is required
exit=78

$ docker run --rm -e GREETING=x -e PORT=abc rh-svc:v3
config error: PORT must be a number between 1 and 65535, got "abc"
exit=78

On Fly a process that exits immediately is restarted a few times and then marked as failed, and the message above is what appears in fly logs. Compare that to a service that starts, accepts traffic and fails on the first request that touches a missing setting: the deploy looks healthy until a user finds the problem. Validating at startup moves every configuration mistake to the deploy, where it is cheap.

The Dockerfile

A Rust release build is a large pile of toolchain that production does not need, so the standard shape is a multi-stage build: compile in a Rust image, then copy only the executable into a minimal one. For a service with no C dependencies, the target can be musl, which produces a fully static binary that runs on scratch, an image with nothing in it:

DockerfileDockerfile
FROM rust:1-alpine AS build
RUN apk add --no-cache musl-dev
WORKDIR /app
COPY Cargo.toml Cargo.lock ./
COPY src ./src
RUN cargo build --release --locked

FROM scratch
COPY --from=build /app/target/release/svc /svc
EXPOSE 8080
ENTRYPOINT ["/svc"]

Three details matter. COPY Cargo.toml Cargo.lock first and --locked on the build make the dependency versions the ones you tested, and failing if the lock file is out of date. The rust:1-alpine image uses musl by default, so cargo build --release already targets it, with no target flag or cross toolchain. And a .dockerignore containing target stops the host's build directory from being sent to the daemon as context, which would otherwise copy hundreds of megabytes on every build.

The release profile in Cargo.toml shrinks the result:

Cargo.tomlTOML
[profile.release]
lto = true
codegen-units = 1
strip = true
panic = "abort"

Building from a cold cache took 44 seconds, and the finished image is tiny:

Text
$ docker build -f Dockerfile.multi -t rh-svc:multi .
...
$ docker images rh-svc:multi
IMAGE          ID             DISK USAGE   CONTENT SIZE   EXTRA
rh-svc:multi   b1c3445c94a0        856kB             0B
$ docker run --rm -d -p 18081:8080 -e GREETING=hi rh-svc:multi
$ curl -s localhost:18081/
hi

An 856 KB image holding one static executable. It starts in milliseconds, uploads to Fly's registry quickly, and has no shell, package manager or libc for an attacker to use. The same tradeoffs as in shipping Rust to production apply to musl: its memory allocator is slower under heavy multi-threaded allocation than glibc's, so a service that allocates heavily should benchmark with mimalloc before choosing it. If you need glibc, switch the final stage to debian:bookworm-slim and expect an image in the tens of megabytes, still small.

One scratch-image consequence deserves a warning: there is no curl, no sh and no CA certificate bundle. A service that makes outbound HTTPS calls must either bundle the roots, for example with the webpki-roots crate used by rustls, or copy /etc/ssl/certs/ca-certificates.crt from the build stage. A missing bundle shows up as a TLS error on the first outbound call, not at startup.

SIGTERM, and why PID 1 matters

When Fly stops a machine, for a deploy, a scale-down or a restart, it sends a signal to the main process (SIGINT by default for Fly, configurable with kill_signal) and waits for kill_timeout seconds before killing it. Your program has that window to finish its work.

Inside a container, your executable is usually PID 1, and the Linux kernel treats PID 1 specially: a signal that has no handler installed is ignored rather than terminating the process. To see it, here is the smallest possible service with no signal handling at all:

src/main.rsrust
use axum::{Router, routing::get};

#[tokio::main]
async fn main() {
    let app = Router::new().route("/", get(|| async { "no handler" }));
    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

Built with the same Dockerfile and stopped with docker stop:

Text
$ docker run -d --name n1 rh-svc:nohandler
$ time docker stop n1
real 3.12
$ docker inspect n1 --format 'exit={{.State.ExitCode}}'
exit=137

SIGTERM did nothing. Docker waited through its grace period and sent SIGKILL, and the exit code is 137, which is 128 plus signal 9. The wait is Docker's stop grace period before it escalates; on Fly the equivalent is kill_timeout. Now the same image with --init, which puts a tiny init process in front as PID 1:

Text
$ docker run -d --init --name n2 rh-svc:nohandler
$ time docker stop n2
real 0.09
$ docker inspect n2 --format 'exit={{.State.ExitCode}}'
exit=143

With an init process as PID 1, the program is no longer PID 1, so the kernel applies the default action to SIGTERM and the process dies at once, in 0.09 seconds, with exit code 143 (128 plus 15). That is fast, but it is an abrupt death: no draining, and any in-flight request is cut. Both results are wrong for a service that cares about its requests, and the cure is the explicit handler in the full program, so the same behavior holds whether or not there is an init process.

With the handler in the code above, the behavior is different. Start a slow request, then stop the container while it is in flight:

Text
$ curl -s -m 10 localhost:18080/slow &
$ time docker stop s1
s1
real 1.61
$ wait
finished the slow request
$ docker logs s1
listening on 0.0.0.0:8080
got SIGTERM, draining
clean exit
$ docker inspect s1 --format 'exit={{.State.ExitCode}}'
exit=0

The stop returned after 1.6 seconds, not ten: the container exited as soon as the in-flight request finished. The request completed with its full response instead of a broken connection, and the exit code is 0. That is a zero-downtime deploy at the process level. The new machine starts, the proxy sends it traffic, and the old one finishes what it was doing before it goes away.

Match the budget to the work. If your longest request takes 20 seconds, kill_timeout must exceed 20, or the platform kills the process in the middle of a request, and your drain code will not have run to completion. Also make sure the drain has an upper bound of its own: a client that holds a connection open forever would otherwise keep a graceful shutdown waiting until the platform's kill.

The Fly configuration

fly launch inspects the directory, asks for an app name and region, and writes a fly.toml. The generated file is a starting point, and for this service the finished version looks like this (not run against Fly):

fly.tomlTOML
app = "rusthacks-demo"
primary_region = "iad"
kill_signal = "SIGTERM"
kill_timeout = 30

[build]
  dockerfile = "Dockerfile"

[env]
  PORT = "8080"

[http_service]
  internal_port = 8080
  force_https = true
  auto_stop_machines = "stop"
  auto_start_machines = true
  min_machines_running = 1

  [[http_service.checks]]
    method = "GET"
    path = "/healthz"
    interval = "10s"
    timeout = "2s"
    grace_period = "5s"

[[vm]]
  size = "shared-cpu-1x"
  memory = "256mb"

Read it against the service. internal_port is the port the program listens on, and has to equal what the code binds; it is the most common mismatch. kill_signal = "SIGTERM" matches the handler, and kill_timeout = 30 gives the drain thirty seconds. The [env] table holds non-secret settings. The health check is a plain GET to /healthz, the cheap route, with a grace period so a slow start is not counted as a failure; the proxy only sends traffic to machines whose checks pass, and that is what turns a rolling deploy into a safe one. auto_stop_machines and min_machines_running control cost: with a minimum of one, the app is always warm; with zero, machines stop when idle and start on the next request, trading a cold-start delay for a lower bill. A 256 MB shared CPU is ample for a service this size, since it uses a few megabytes.

Secrets

GREETING is not a secret, but a database URL or an API key is. Fly keeps secrets out of fly.toml and out of the image, and injects them as environment variables at start:

Shell
fly secrets set DATABASE_URL='postgres://app:[email protected]:5432/app'
fly secrets list

fly secrets list shows names and digests but never values. Setting a secret restarts the machines so they pick it up. The program reads it exactly as it reads GREETING, through std::env::var at startup, which means a missing secret is a configuration error with exit code 78 and a clear message, and not a runtime surprise. Never bake a secret into the image or commit it into fly.toml: the image is pushed to a registry and the file is in version control.

Deploying, and what to expect

The commands, documented but not run here:

Shell
fly launch --no-deploy        # writes fly.toml, creates the app
fly secrets set GREETING='hello from fly'
fly deploy                    # builds the image, pushes it, rolls out
fly status
fly logs
curl https://rusthacks-demo.fly.dev/healthz

fly deploy builds the Dockerfile on Fly's remote builder (or locally with --local-only), pushes the image, and starts new machines, waiting for their health checks to pass before stopping the old ones. If the new image fails its checks, the rollout stops and the old version keeps serving. Release history lives in fly releases, and rolling back is a redeploy of the previous image with fly deploy --image <ref>. A failed deploy is therefore usually a matter of reading fly logs for the first error, which with the startup validation above is a one-line message.

Restart policy and exit codes

The exit codes seen so far form a small vocabulary that is worth treating as part of the service's interface. 0 is a clean exit after a drain. 78 means configuration is wrong, and restarting will not help. 1 is a runtime failure such as a bind error. 137 and 143 mean the process was killed by a signal. A supervisor can act on these differences: Fly restarts a machine that exits, with a limited number of attempts, and fly logs shows the last lines it wrote before dying. If configuration errors exit 78 within a few milliseconds and print one line, the log answers the question without any further digging. If they instead panic with a backtrace from an unwrap on a missing variable, the same information is buried in noise.

A panic in a request handler is a related case. Tokio catches a panic in a spawned task and the connection fails, but the process lives. Setting panic = "abort" in the release profile, as above, changes that: any panic ends the process, the platform restarts it, and the service comes back in a known state. That is a defensible choice for a stateless service, but know that one panicking request then takes down every request in flight on that machine, so keep panics out of request paths by returning errors, and keep at least two machines running if availability matters.

Scaling and rollouts

Fly scales by machine count, not by threads inside one process, so horizontal scale is fly scale count 3 and the proxy spreads requests across healthy machines. Because the service keeps no per-machine state, any machine can answer any request, and that is the property worth protecting: if you add an in-process cache or a counter, a second machine will disagree with the first. Roll out with the default rolling strategy and watch the health checks. If a deploy needs a risky migration, run it as a separate release step before the new code starts, and write the migration so the old version still works against the new schema, since for a few seconds both versions run at once.

Logs and metrics

Write logs to standard output and standard error, one event per line, and let the platform collect them. Fly streams them through fly logs and can ship them elsewhere. Use the tracing crate with a JSON formatter in production so fields such as request ID, route and latency are queryable rather than embedded in sentences. Do not write log files: a container filesystem is discarded on restart, and a log file inside a scratch image has nowhere to go. Expose a /metrics route if you use Prometheus, and keep it off the public listener or protect it, since metrics reveal traffic patterns and internal names.

A deploy checklist from the local run

Everything in this list can be checked on your own machine before fly deploy, and each item corresponds to a failure that actually happens on the platform:

  • The image runs with docker run -e ... and answers on the port in fly.toml.
  • A missing or invalid setting produces exit code 78 and a message, not a hang.
  • The service binds 0.0.0.0; curl from the host works through a published port.
  • docker stop returns in about the length of your slowest request, with exit code 0.
  • The health route is cheap and independent of the database, so a database blip does not take every machine out of rotation. Use a separate readiness route if you want that distinction, as described in health checks.
  • Outbound HTTPS works from the final image, which on scratch means certificates are bundled.

Databases, volumes and regions

A stateless service is the simple case. State changes the picture in three ways. A Postgres database, managed by Fly or external, is reached through a connection string that arrives as a secret, and the app should create its connection pool once at startup, with a size below the database's connection limit multiplied by the number of machines. A volume attaches persistent disk to a single machine in a single region, which suits SQLite or an on-disk cache but ties that machine to the disk: it cannot move, and scaling out means separate volumes with separate data. And multiple regions put copies of the service near users while the database stays in one place, so a request in Singapore that writes to a primary in Virginia is slower than a request in Virginia. Decide where the writes live before deciding where the machines go.

When Fly is not the right fit

Fly suits small to medium services that benefit from a global footprint and a simple deploy. It is a weaker fit when you need the surrounding services of a large cloud, such as managed queues and identity, when compliance requires a particular provider, or when you already run Kubernetes and want one control plane. For event-driven functions, AWS Lambda can be cheaper at low volume. For fleets that already have a cluster, Kubernetes is the more consistent choice. The service and the image in this guide move between all three unchanged, because they depend only on environment variables, a port and a signal, and that portability is the real reward for writing the service this way.

Taggedfly
Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.