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, the provider should make this port publicly accessible from the internet. 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. The provider will GET this path and expect 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

Health check deep dive

The shorthand form covers most cases: give it a path and the provider does the rest. 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 the provider starts counting failures. 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. The provider will fall back to checking whether the process is 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/Launchfile View 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:
    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.
health tells the provider how to check your app. 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).