Ports, Storage & Health — Learn Launchfile

The `provides` field

Your app listens on a port. But the world outside your container doesn't know which one, what protocol it speaks, or whether it should be reachable from the internet. The provides field makes all of that explicit.

Each entry in provides declares a single endpoint. The key properties are:

protocol — What the endpoint speaks: http, https, tcp, or grpc.
port — The port number your app listens on inside the container.
bind — Optional. The address to bind to (defaults to 0.0.0.0).
exposed — When true, this port is meant to be reachable from outside the deployment — your app's public entry point. When false (the default), it's only reachable by other components in the same deployment.

Build it up

Start with a single HTTP endpoint on port 3000, publicly accessible.

provides:
  - protocol: http
    port: 3000
    exposed: true

Add persistent storage. The data volume mounts at the given path and survives container restarts.

provides:
  - protocol: http
    port: 3000
    exposed: true

storage:
  data:
    path: /var/lib/app/data
    persistent: true

Add a health check using shorthand. An HTTP GET to this path is expected to return a 2xx response.

provides:
  - protocol: http
    port: 3000
    exposed: true

storage:
  data:
    path: /var/lib/app/data
    persistent: true

health: /health

Switch to the expanded health check form for full control over timing, retries, and startup grace period.

provides:
  - protocol: http
    port: 3000
    exposed: true

storage:
  data:
    path: /var/lib/app/data
    persistent: true

health:
  path: /api/health
  interval: 30s
  timeout: 5s
  retries: 3
  start_period: 60s

Referencing the path

Declaring a volume gives it a path — but you rarely want to hardcode that path into your app's configuration. The volume may live at a different real path depending on where you deploy. Reference the path it was actually provisioned at with the $storage.<name>.path expression instead of repeating the literal path.

Hardcoded — brittle

storage:
  data:
    path: /var/lib/app/data

env:
  DATA_DIR: /var/lib/app/data

Expression — portable

storage:
  data:
    path: /var/lib/app/data

env:
  DATA_DIR: $storage.data.path

Why not just repeat the path?

The two copies can drift. Change storage.data.path but forget the duplicate in env, and your app reads from the wrong directory — silently. $storage.<name>.path always resolves to wherever your volume was actually provisioned, so the same Launchfile runs correctly anywhere with no edits. Under the hood: where the volume actually lives differs by deployment — a container provider bind-mounts it at the declared path, while a native dev provider provisions a separate host directory — and the expression hides that difference. Catalog apps like Mailpit and AnythingLLM use it to wire their data paths into the environment.

Health check deep dive

The shorthand form covers most cases: give it a path and the rest is handled for you. When you need more control, expand it into an object.

Shorthand

health: /health

Expanded

health:
  path: /api/health
  interval: 30s
  timeout: 5s
  retries: 3
  start_period: 60s

Slow starters

The start_period field gives your app time to boot before failed health checks start counting against it. A Java app loading Spring context or a Rails app compiling assets might need 60–120 seconds. During the start period, failed health checks don't count toward the retry limit.

If your app has no HTTP endpoint (say, a background worker), you can omit health entirely — with no HTTP check declared, liveness falls back to a simpler signal, like whether the process is still running.

In the wild

Ghost is a professional publishing platform. Its Launchfile declares an HTTP endpoint, persistent storage for uploaded content, and a health check hitting the admin API.

ghost/LaunchfileView on GitHub

version: launch/v1
name: ghost
description: "Professional publishing platform"
repository: https://github.com/TryGhost/Ghost
logo: https://ghost.org/images/logos/ghost-logo-orb.png

image: ghost:5-alpine
provides:
  - protocol: http
    port: 2368
    exposed: true
requires:
  - type: mysql
    set_env:
      database__connection__host: $host
      database__connection__user: $user
      database__connection__password: $password
      database__connection__database: $name
      database__connection__port: $port
env:
  database__client:
    default: "mysql"
  url:
    default: $app.url
    required: true
    description: "Public URL of the Ghost instance"
storage:
  content:
    path: /var/lib/ghost/content
    persistent: true
health: /ghost/api/v4/admin/site/
restart: always

provides:: Declares an HTTP endpoint on port 2368, publicly exposed so readers can reach the blog.
storage:: The content volume at /var/lib/ghost/content holds themes, images, and uploads. Persistent means it survives redeploys.
health:: Hits the Ghost admin site endpoint. A 2xx means the app is ready to serve traffic.

Try it: npx launchfile up ghost to launch this app locally.View in catalog

Check your understanding

What does exposed: true mean on a provides entry?

Key takeaways

provides declares every network endpoint your app exposes, with protocol, port, and visibility.
storage declares named volumes. Set persistent: true for data that must survive restarts.
$storage.<name>.path resolves to the real path the volume was actually provisioned at — reference it in env instead of hardcoding the path in two places.
health describes how your app's readiness is checked. Use the string shorthand for simple cases, the object form for tuning.
exposed: true means "the internet should reach this." Default is false (internal only).