Fly Docs

https://github.com/superfly/docs
Admin
Fly.io is a platform that allows developers to deploy and manage applications globally, close to...
Tokens:340,357
Snippets:3,431
Trust Score:9.4
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install dependencies

Source: https://github.com/superfly/docs/blob/main/security/arcjet.html.md

Installs the project dependencies required for the example application.

```cmd
npm ci
```

--------------------------------

### Entrypoint script to start sshd

Source: https://github.com/superfly/docs/blob/main/blueprints/opensshd.html.md

Example entrypoint script that starts sshd and then executes the main command. Must be run as root.

```bash
#!/bin/bash -e

/usr/sbin/sshd

exec "$@"
```

--------------------------------

### Launch Livebook server locally

Source: https://github.com/superfly/docs/blob/main/elixir/advanced-guides/connect-livebook-to-your-app.html.md

Starts the Livebook server locally after installation.

```cmd
livebook server
```

--------------------------------

### Dockerfile caching example for dependency installation

Source: https://github.com/superfly/docs/blob/main/flyctl/integrating.html.md

This Dockerfile example shows the recommended order to maximize cache hits: copy dependency manifests, install them, then copy the rest of the source. If the install runs after copying the full source, any source change invalidates the install layer's cache and forces a reinstall on every build.

```dockerfile
COPY package.json package-lock.json ./
RUN npm install
COPY . .
```

--------------------------------

### Start dev server

Source: https://github.com/superfly/docs/blob/main/security/arcjet.html.md

Starts the development server for local testing.

```cmd
npm run dev
```

--------------------------------

### Install Fly CLI and authenticate

Source: https://github.com/superfly/docs/blob/main/getting-started/migrate-from-heroku.html.md

Install the Fly CLI and log in to both Fly and Heroku. Run these commands in your terminal before starting the migration.

```bash
# Install Fly CLI
curl -fsSL https://fly.io/install.sh | sh

# Sign up / log in to Fly
fly auth signup   # or: fly auth login

# Make sure you're logged into Heroku
heroku login
```

--------------------------------

### Install Livebook as an Escript

Source: https://github.com/superfly/docs/blob/main/elixir/advanced-guides/connect-livebook-to-your-app.html.md

Run these commands to install Livebook as an Escript using mix. Requires local Elixir setup.

```bash
mix do local.rebar --force, local.hex --force
mix escript.install hex livebook
```

--------------------------------

### Enable WireGuard interface on boot

Source: https://github.com/superfly/docs/blob/main/blueprints/bridge-deployments-wireguard.html.md

Connects to the target server via SSH and enables the WireGuard interface to start on boot using systemctl. The example enables 'wg-quick@fly0.service'.

```docker
ssh root@phantoon.local
systemctl enable --now wg-quick@fly0.service
```

--------------------------------

### Install Ruby on Ubuntu

Source: https://github.com/superfly/docs/blob/main/elixir/advanced-guides/sqlite3.html.md

Install Ruby on Ubuntu using apt-get.

```cmd
apt-get install ruby-full
```

--------------------------------

### Launch Desktop Commander MCP server with setup

Source: https://github.com/superfly/docs/blob/main/mcp/examples.html.md

Launches DesktopCommander MCP server with a setup step, configured for Claude.

```sh
fly mcp launch "npx @wonderwhy-er/desktop-commander@latest" \
  --claude --server desktop-commander \
  --setup "RUN npx -y @wonderwhy-er/desktop-commander@latest setup"
```

--------------------------------

### Run Hermes setup wizard

Source: https://github.com/superfly/docs/blob/main/blueprints/hermes-agent-on-fly-io.html.md

Opens a shell on the machine and runs the setup wizard, which walks through model selection, tool configuration, and connecting messaging platforms. Exit the SSH session when done.

```bash
fly ssh console -a <your-hermes-app>
hermes setup
```

--------------------------------

### Test cold start by stopping and starting a machine

Source: https://github.com/superfly/docs/blob/main/reference/suspend-resume.html.md

Stop and then start a machine to test cold start behavior. This can help diagnose unexpected cold starts.

```bash
fly machine stop <machine-id>
fly machine start <machine-id>
```

--------------------------------

### Provisioning response example

Source: https://github.com/superfly/docs/blob/main/reference/extensions_api.html.md

Example response to a provisioning request. Must include a unique id and a config object with environment variables. Optionally include fly_app_name and name.

```javascript
{
  "id": "432cb1c9-4d06-4a91-95dc-bc7aa27b896d",
  "config": {
    "LOGJAM_URL": "https://user:password@test.logjam.io"
  },
  "name": "logjam-1bd03ba",
  "fly_app_name": "logjam-production"
}
```

--------------------------------

### Install flyctl with Homebrew

Source: https://github.com/superfly/docs/blob/main/index.html.md

Installs the Fly.io command-line tool (flyctl) using Homebrew on macOS. This is the first step in the getting started guide.

```cmd
brew install flyctl
```

--------------------------------

### Dockerfile for supervisord

Source: https://github.com/superfly/docs/blob/main/app-guides/multiple-processes.html.md

Dockerfile that installs supervisord, adds its configuration, and starts it. The CMD runs supervisord with the config file.

```Dockerfile
FROM golang

RUN apt-get update && \
    apt-get install -y \
        bash \
        supervisor \
        curl
# ...

ADD supervisor.conf /app/
CMD supervisord -c /app/supervisor.conf

```

--------------------------------

### Test locally with Docker Compose

Source: https://github.com/superfly/docs/blob/main/rails/getting-started/dockerfiles.html.md

Generate a docker-compose setup, set the RAILS_MASTER_KEY environment variable, then build and start the application locally with Docker Compose. This requires Docker to be installed.

```sh
bin/rails generate dockerfile --compose
```

```sh
export RAILS_MASTER_KEY=$(cat config/master.key)
```

```sh
docker compose build
```

```sh
docker compose up
```

--------------------------------

### Example release command

Source: https://github.com/superfly/docs/blob/main/blueprints/autostart-internal-apps.html.md

Example of releasing public IP addresses from an app.

```bash
fly ips release 2a09:8280:1::2d:1111 66.241.124.11
```

--------------------------------

### Generic CI deploy example

Source: https://github.com/superfly/docs/blob/main/flyctl/integrating.html.md

Complete CI workflow: install flyctl, set FLY_API_TOKEN from a CI secret, and deploy with --remote-only. Works in GitLab CI, CircleCI, Jenkins, Buildkite, and others.

```bash
# Install
curl -L https://fly.io/install.sh | sh
export PATH="$HOME/.fly/bin:$PATH"

# Authenticate via environment
export FLY_API_TOKEN="$YOUR_CI_SECRET"

# Deploy
fly deploy --remote-only -a my-app

```

--------------------------------

### Create a new Rails application

Source: https://github.com/superfly/docs/blob/main/rails/getting-started/index.html.md

Verify Rails is installed and create a new application named 'welcome'. Then change into the application directory.

```shell
$ rails --version
$ rails new welcome
$ cd welcome
```

--------------------------------

### Provisioning request example

Source: https://github.com/superfly/docs/blob/main/reference/extensions_api.html.md

Example POST request to provision an extension resource. Includes required and optional parameters. The request must be signed with an X-Signature header containing the HMAC of the request body.

```javascript
POST https://logjam.io/flyio/extensions

{
  name: "test",
  id: "test",
  organization_id: "04La2mblTaz",
  organization_name: "High Flyers",
  user_email: "v9WvKokd@customer.fly.io",
  user_id: "NeBO2G0l0yJ6",
  user_role: "admin",
  primary_region: "mad",
  ip_address: "fdaa:0:47fb:0:1::1d",
  read_regions: ["syd", "scl"],
  url: "https://logjam.io/flyio/extensions",
  nonce: "e3f7b4c8f5ea016d0d2e92048ca0d856",
  timestamp: 1685641159
}
```

--------------------------------

### Start MCP inspector proxy

Source: https://github.com/superfly/docs/blob/main/mcp/deploy-on/fly-machine.html.md

Use this command to start a local proxy for testing your MCP server with the MCP inspector. Requires Node.js installed; then navigate to http://127.0.0.1:6274 to connect and test tools.

```sh
fly mcp proxy -i
```

--------------------------------

### Start IEx to test WxWidgets

Source: https://github.com/superfly/docs/blob/main/elixir/advanced-guides/connect-observer-to-your-app.html.md

Start an IEx shell to verify WxWidgets and Observer are working locally. This is the first step in the WxWidgets support test.

```elixir
iex
```

--------------------------------

### Install wireguard-tools and openresolv on Ubuntu

Source: https://github.com/superfly/docs/blob/main/networking/private-networking.html.md

Install the required WireGuard tools and openresolv on Ubuntu 18.04 to 22.04. Run this command if `wg-quick` is not already installed.

```bash
sudo apt install wireguard-tools openresolv
```

--------------------------------

### Run fly mcp server with MCP inspector

Source: https://github.com/superfly/docs/blob/main/mcp/flyctl-server.html.md

Use this command to start the flyctl MCP server in inspector mode. Requires Node.js to be installed. Then navigate to http://127.0.0.1:6274, click Connect, and list tools like fly-platform-status, fly-orgs-list, fly-apps-list, or fly-machines-list.

```sh
fly mcp server -i
```

--------------------------------

### Install Sequel gem

Source: https://github.com/superfly/docs/blob/main/elixir/advanced-guides/sqlite3.html.md

Install the Ruby database adapter Sequel, which provides a command-line tool for copying databases.

```sh
gem install sequel
```

--------------------------------

### Example release history output

Source: https://github.com/superfly/docs/blob/main/blueprints/rollback-guide.html.md

Example output from the `fly releases` command, showing release versions, timestamps, and image tags.

```text
v42   2025-08-12T16:21Z   registry.fly.io/myapp:deployment-01HXXXXX
v41   2025-08-10T09:14Z   registry.fly.io/myapp:deployment-01HYYYYY
```

--------------------------------

### Install networking tools in the shell Machine

Source: https://github.com/superfly/docs/blob/main/blueprints/private-applications-flycast.html.md

Install `curl`, `ping`, and `dig` in the minimal Ubuntu shell Machine using `apt`.

```bash
# apt update && apt install -y curl iputils-ping dnsutils
```

--------------------------------

### Start Observer to test WxWidgets

Source: https://github.com/superfly/docs/blob/main/elixir/advanced-guides/connect-observer-to-your-app.html.md

Start Observer from IEx to verify WxWidgets support. If it launches successfully, the libraries and dependencies are working, though it won't be connected to anything.

```elixir
:observer.start
```

--------------------------------

### Install Gunicorn

Source: https://github.com/superfly/docs/blob/main/django/getting-started/index.html.md

Installs Gunicorn as the production server for Django.

```cmd
python -m pip install gunicorn
```

--------------------------------

### Set up certificate validation with fly certs setup

Source: https://github.com/superfly/docs/blob/main/networking/understanding-cloudflare.html.md

Initiates certificate setup and displays the required _fly-ownership TXT record. Add the displayed TXT record to Cloudflare DNS to prove domain ownership.

```bash
fly certs setup example.com
```

--------------------------------

### Start Elixir project with IEx and Phoenix server

Source: https://github.com/superfly/docs/blob/main/elixir/advanced-guides/interesting-things-with-livebook.html.md

Starts the local project with a short name 'my_app' and cookie 'secret' for Livebook to attach to. Use the same values when configuring the attached node in Livebook.

```text
iex --sname my_app --cookie secret -S mix phx.server
```

--------------------------------

### Express and Fastify listen on 0.0.0.0

Source: https://github.com/superfly/docs/blob/main/getting-started/troubleshooting.html.md

Node.js examples for Express and Fastify to listen on 0.0.0.0 port 8080. Both are shown together as framework examples.

```javascript
// Express
app.listen(8080, '0.0.0.0')

// Fastify
fastify.listen({ port: 8080, host: '0.0.0.0' })
```

--------------------------------

### Install WireGuard on Ubuntu

Source: https://github.com/superfly/docs/blob/main/blueprints/bridge-deployments-wireguard.html.md

Installs the WireGuard package on an Ubuntu server using apt. This is a prerequisite for setting up the WireGuard tunnel.

```docker
sudo apt -y install wireguard
```

--------------------------------

### Start Django development server

Source: https://github.com/superfly/docs/blob/main/django/getting-started/index.html.md

Starts Django's local web server using the runserver command. After starting, the app is accessible at http://127.0.0.1:8000/.

```cmd
python manage.py runserver
```

--------------------------------

### Dockerfile: Install fly CLI and set environment variables

Source: https://github.com/superfly/docs/blob/main/rails/advanced-guides/machine.html.md

Add these lines to the Dockerfile, ideally before the '# Deploy your application' comment, to install the fly executable and configure its path.

```dockerfile
RUN curl -L https://fly.io/install.sh | sh
ENV FLYCTL_INSTALL="/root/.fly"
ENV PATH="$FLYCTL_INSTALL/bin:$PATH"
```

--------------------------------

### Livebook startup link

Source: https://github.com/superfly/docs/blob/main/elixir/advanced-guides/connect-livebook-to-your-app.html.md

When Livebook starts, it prints a link in the console with a token for connecting. Use this URL to access the Livebook interface.

```text
[Livebook] Application running at http://localhost:8080/?token=uzbwvvpexj7mdftwjilezi4qaygt2bfc
```

--------------------------------

### Clone Arcjet example Next.js repository

Source: https://github.com/superfly/docs/blob/main/security/arcjet.html.md

Clones the Arcjet example Next.js app from GitHub to get started quickly.

```cmd
git clone git@github.com:arcjet/arcjet-example-nextjs-fly.git
```

--------------------------------

### Create project folder and enter it

Source: https://github.com/superfly/docs/blob/main/django/getting-started/index.html.md

Creates a directory named 'hello-django' and changes into it. This is the first step in setting up the project locally.

```cmd
mkdir hello-django && cd hello-django
```

--------------------------------

### Dockerfile: Install SqlServer drivers before COPY

Source: https://github.com/superfly/docs/blob/main/laravel/advanced-guides/customizing-dockerfile.html.md

Add this section to the Dockerfile before the COPY instruction to install SqlServer drivers (sqlsrv, pdo_sqlsrv) and related packages. Installing before COPY allows Docker to cache the work and avoid re-running on each deployment. Uses a single RUN command to reduce image layers.

```Dockerfile
# Things above this omitted

LABEL fly_launch_runtime="laravel"

###
## NEW STUFF HERE
#
ENV ACCEPT_EULA=Y

# Note we specify version 18 of SqlServer via package msodbcsql18
RUN curl https://packages.microsoft.com/keys/microsoft.asc | apt-key add - \
    && curl https://packages.microsoft.com/config/ubuntu/20.04/prod.list > /etc/apt/sources.list.d/mssql-release.list \
    && apt-get update \
    && apt-get install --no-install-recommends -y php${PHP_VERSION}-dev php-pear \
       g++ make msodbcsql18 unixodbc-dev mssql-tools \
    && pecl install sqlsrv \
    && pecl install pdo_sqlsrv \
    && printf "; priority=20\nextension=sqlsrv.so\n" > /etc/php/${PHP_VERSION}/mods-available/sqlsrv.ini \
    && printf "; priority=30\nextension=pdo_sqlsrv.so\n" > /etc/php/${PHP_VERSION}/mods-available/pdo_sqlsrv.ini \
    && phpenmod -v ${PHP_VERSION} sqlsrv pdo_sqlsrv
###
## END NEW STUFF
#

# copy application code, skipping files based on .dockerignore
COPY . /var/www/html

# Things below this omitted
```

--------------------------------

### Install Celery with Redis and Django results

Source: https://github.com/superfly/docs/blob/main/blueprints/work-queues.html.md

Install Celery with Redis support and django-celery-results using pip.

```bash
pip install "celery[redis]" django-celery-results
```

--------------------------------

### Dockerfile for overmind

Source: https://github.com/superfly/docs/blob/main/app-guides/multiple-processes.html.md

Dockerfile that installs overmind, adds a Procfile, and starts overmind. It installs bash, tmux, and curl, and fetches overmind via go get.

```Dockerfile
FROM golang

RUN apt-get update && \
    apt-get install -y \
        bash \
        tmux \
        curl
# ...

RUN GO111MODULE=on go get -u github.com/DarthSim/overmind/v2
ADD Procfile /app/
CMD ["overmind", "start"]

```

--------------------------------

### Install pg gem for Postgres adapter

Source: https://github.com/superfly/docs/blob/main/elixir/advanced-guides/sqlite3.html.md

Install the pg gem to use the Postgres adapter with Sequel.

```cmd
gem install pg
```

--------------------------------

### Dockerfile for base image with Go installed

Source: https://github.com/superfly/docs/blob/main/blueprints/using-base-images-for-faster-deployments.html.md

Base Dockerfile based on debian:12 that installs Go. Uses sleep infinity as the CMD to allow SSH inspection. Save as base.Dockerfile.

```Dockerfile
FROM debian:12

# Install Go
RUN apt-get update; apt-get upgrade; apt-get -y install golang

CMD [ "sleep", "inf" ]
```

--------------------------------

### Initialize git and add remote

Source: https://github.com/superfly/docs/blob/main/laravel/advanced-guides/github-actions.html.md

Set up git in the project directory and point the remote origin to your new GitHub repository using SSH.

```cmd
git init
git remote add origin git@github.com:<username>/<repository-name>.git
```

--------------------------------

### Use an existing Docker image

Source: https://github.com/superfly/docs/blob/main/machines/flyctl/fly-machine-run.html.md

Runs a Machine from a prebuilt image by passing the image reference as the `<image>` argument. Example uses `ghcr.io/livebook-dev/livebook:0.11.4`.

```cmd
fly machine run ghcr.io/livebook-dev/livebook:0.11.4
```

--------------------------------

### Example .cursor/mcp.json configuration

Source: https://github.com/superfly/docs/blob/main/mcp/deploy-on/your-app.html.md

Configures the Tidewave MCP server URL for Cursor. For Claude and others, an mcp-proxy is recommended.

```json
{
  "mcpServers": {
    "tidewave": {
      "url": "http://localhost:4000/tidewave/mcp"
    }
  }
}
```

--------------------------------

### Launch and deploy your app to Fly

Source: https://github.com/superfly/docs/blob/main/blueprints/n-tier-architecture.html.md

Deploy your app to Fly to create the web tier. Run these commands in your project directory.

```bash
fly launch
fly deploy
```

--------------------------------

### Set up a new Fly app

Source: https://github.com/superfly/docs/blob/main/security/arcjet.html.md

Initializes a new Fly app without deploying, generating a Dockerfile and fly.toml.

```cmd
fly launch --no-deploy
```

--------------------------------

### Install supercronic in Dockerfile

Source: https://github.com/superfly/docs/blob/main/blueprints/supercronic.html.md

Dockerfile instructions to download, verify, and install supercronic v0.2.29. Includes setting environment variables, downloading the binary, checking its SHA1 checksum, making it executable, and copying the crontab file.

```dockerfile
# Latest releases available at https://github.com/aptible/supercronic/releases
ENV SUPERCRONIC_URL=https://github.com/aptible/supercronic/releases/download/v0.2.29/supercronic-linux-amd64 \
    SUPERCRONIC=supercronic-linux-amd64 \
    SUPERCRONIC_SHA1SUM=cd48d45c4b10f3f0bfdd3a57d054cd05ac96812b

RUN curl -fsSLO "$SUPERCRONIC_URL" \
 && echo "${SUPERCRONIC_SHA1SUM}  ${SUPERCRONIC}" | sha1sum -c - \
 && chmod +x "$SUPERCRONIC" \
 && mv "$SUPERCRONIC" "/usr/local/bin/${SUPERCRONIC}" \
 && ln -s "/usr/local/bin/${SUPERCRONIC}" /usr/local/bin/supercronic

# You might need to change this depending on where your crontab is located
COPY crontab crontab
```

--------------------------------

### SSO GET request to extension endpoint

Source: https://github.com/superfly/docs/blob/main/reference/extensions_api.html.md

GET request sent by the CLI to initiate SSO. If the user is already logged in, redirect to the extension detail screen; otherwise start OAuth authorization.

```http
GET {base_url}/extensions/{extension_id}/sso
```

--------------------------------

### Example output of fly ips list

Source: https://github.com/superfly/docs/blob/main/blueprints/autostart-internal-apps.html.md

Example output showing public and private IP addresses. Public addresses are automatically assigned to apps with services on first deploy.

```text
VERSION	IP                  	TYPE              	REGION	CREATED AT
v6     	2a09:8280:1::2d:1111	public (dedicated)	global	Sep 1 2023 19:47
v6     	fdaa:2:45b:0:1::11  	private           	global	Mar 16 2024 18:20
v4     	66.241.124.11       	public (shared)   	      	Jan 1 0001 00:00
```

--------------------------------

### Remove multi-stage build setup when Node is installed

Source: https://github.com/superfly/docs/blob/main/laravel/advanced-guides/using-inertia-ssr.html.md

Remove these lines from the Dockerfile when using Option 2 (installing Node in the final image). This eliminates the separate Node build stage and the asset copy step.

```dockerfile
# Remove the "multi stage build setup" lines below:
- FROM node:${NODE_VERSION} as node_modules_go_brrr
- RUN mkdir /app

- RUN mkdir -p  /app
- WORKDIR /app
- COPY . .
- COPY --from=base /var/www/html/vendor /app/vendor

# Remove the "set up to copy asset folder from node image to fly-laravel image"
# lines below:
- COPY --from=node_modules_go_brrr /app/public /var/www/html/public-npm
- RUN rsync -ar /var/www/html/public-npm/ /var/www/html/public/ && rm -rf /var/www/html/public-npm
```

--------------------------------

### Example http_service configuration with processes

Source: https://github.com/superfly/docs/blob/main/laravel/the-basics/cron-and-queues.html.md

Shows the `[http_service]` section with `processes = ["app"]` to apply service config only to the web-serving VM. Queue and cron instances do not need services.

```toml
[http_service]
  internal_port = 8080
  force_https = true
  auto_stop_machines = true
  auto_start_machines = true
  min_machines_running = 0
  processes = ["app"]
```

--------------------------------

### WireGuard configuration file example

Source: https://github.com/superfly/docs/blob/main/networking/private-networking.html.md

Example of a WireGuard configuration file generated by the `fly wireguard create` command. The DNS line shows the DNS server address, which follows the pattern of the organization prefix plus `::3`.

```yaml
[Interface]
PrivateKey = [redacted]
Address = fdaa:0:18:a7b:d6b:0:a:2/120
DNS = fdaa:0:18::3
```

--------------------------------

### Create a Redis database with flyctl redis create

Source: https://github.com/superfly/docs/blob/main/upstash/redis.html.md

Runs the interactive creation wizard. Prompts for organization, primary region (cannot be changed later), and optional replica regions (can be changed later). Consider a fixed price plan if using Sidekiq, BullMQ, or similar software to avoid high pay-as-you-go costs.

```cmd
flyctl redis create
```

```output
? Select Organization: fly-apps (fly-apps)
? Choose a primary region (can't be changed later) Madrid, Spain (mad)
? Optionally, choose one or more replica regions (can be changed later): Amsterdam, Netherlands (ams)
```

--------------------------------

### Connection String Output

Source: https://github.com/superfly/docs/blob/main/getting-started/migrate-from-heroku.html.md

Example output from the create command showing the connection string format. The cluster ID is the part after 'pgbouncer.' and before '.flympg.net'.

```text
Connection string: postgresql://fly-user:PASSWORD@pgbouncer.CLUSTER_ID.flympg.net/fly-db
```

--------------------------------

### Configure autostop/autostart in fly.toml

Source: https://github.com/superfly/docs/blob/main/blueprints/resilient-apps-multiple-machines.html.md

Example fly.toml configuration for enabling Fly Proxy autostop/autostart on an HTTP service. Includes optional min_machines_running and concurrency settings. Use soft_limit to determine Machine excess capacity.

```TOML
[http_service]
  internal_port = 8080
  force_https = true
  auto_stop_machines = "stop" # Fly Proxy stops Machines based on traffic
  auto_start_machines = true # Fly Proxy starts Machines based on traffic 
  min_machines_running = 0 # No. of Machines to keep running in primary region
  [http_service.concurrency]
    type = "requests"
    soft_limit = 200 # Used by Fly Proxy to determine Machine excess capacity
```

--------------------------------

### Set SUBJECT environment variable for log shipper

Source: https://github.com/superfly/docs/blob/main/monitoring/logs-api-options.html.md

Set the `SUBJECT` environment variable when deploying the log shipper to control which logs get forwarded. This example forwards logs for all instances of the `my-app` app.

```bash
SUBJECT="logs.my-app.*.*"
```

--------------------------------

### Install Node and build assets in final image

Source: https://github.com/superfly/docs/blob/main/laravel/advanced-guides/using-inertia-ssr.html.md

Add these instructions to the Dockerfile to install Node.js and build the necessary assets and node_modules directly in the final fly-laravel image. The snippet includes the existing asset build commands that should already be present.

```dockerfile
# Install node in fly-laravel image
RUN cd ~ \
    && curl -sL https://deb.nodesource.com/setup_18.x -o nodesource_setup.sh \
    && bash nodesource_setup.sh \ 
    && apt install nodejs \ 
    && cd /var/www/html

# The snippet below already exists in the Dockerfile btw,
# In the multi-stage build set up:
RUN if [ -f "vite.config.js" ]; then \
        ASSET_CMD="build"; \
    else \
        ASSET_CMD="production"; \
    fi; \
    if [ -f "yarn.lock" ]; then \
        yarn install --frozen-lockfile; \
        yarn $ASSET_CMD; \
    elif [ -f "pnpm-lock.yaml" ]; then \
        corepack enable && corepack prepare pnpm@latest-8 --activate; \
        pnpm install --frozen-lockfile; \
        pnpm run $ASSET_CMD; \
    elif [ -f "package-lock.json" ]; then \
        npm ci --no-audit; \
        npm run $ASSET_CMD; \
    else \
        npm install; \
        npm run $ASSET_CMD; \
    fi;

RUN  chown -R www-data:www-data /var/www/html/public

EXPOSE 8080

ENTRYPOINT ["/entrypoint"]
```

--------------------------------

### Sample webhook payload for machine event

Source: https://github.com/superfly/docs/blob/main/reference/extensions_api.html.md

Example payload sent to your webhook endpoint when a machine event occurs, such as a stop or start. The payload includes machine_id, status, and data with error details. The Type header follows the format io.fly.machine.starting.

```http
POST https://logjam.io/flyio/extensions/events
{
  "machine_id": "5683977ad31768",
  "status": "failed",
  "data": {
    "Error": "image not found",
    "Transition": "prepareImage"
  }
}
```

--------------------------------

### Launch and Configure Django App with fly launch

Source: https://github.com/superfly/docs/blob/main/django/getting-started/index.html.md

Run `fly launch` to start the wizard. It scans source code, detects a Django app, creates the app, writes fly.toml, and sets a SECRET_KEY. The output shows the detected settings and confirmation that the app is ready to deploy.

```cmd
fly launch
```

```output
Scanning source code
Detected a Django app
Creating app in /flyio/hello-django
We're about to launch your Django app on Fly.io. Here's what you're getting:

Organization: Joe Doe                (fly launch defaults to the personal org)
Name:         hello-django           (derived from your directory name)
Region:       Amsterdam, Netherlands (this is the fastest region for you)
App Machines: shared-cpu-1x, 1GB RAM (most apps need about 1GB of RAM)
Postgres:     <none>                 (not requested)
Redis:        <none>                 (not requested)

? Do you want to tweak these settings before proceeding? Yes
Opening https://fly.io/cli/launch/mo1ootho9ualooghoch3iih6cha2shah ...

Waiting for launch data... Done
Created app 'hello-django' in organization 'personal'
Admin URL: https://fly.io/apps/hello-django
Hostname: hello-django.fly.dev
Set secrets on hello-django: SECRET_KEY
Wrote config file fly.toml

[INFO] Python 3.10.12 was detected. 'python:3.10-slim-bullseye' image will be set in the Dockerfile.

Validating /flyio/hello-django/fly.toml
Platform: machines
✓ Configuration is valid
Your app is ready! Deploy with `flyctl deploy`
```

--------------------------------

### Execute observer script

Source: https://github.com/superfly/docs/blob/main/elixir/advanced-guides/connect-observer-to-your-app.html.md

Run the observer script to connect to the remote cluster and start Observer.

```cmd
./observer
```

--------------------------------

### Options: -h, --help for create

Source: https://github.com/superfly/docs/blob/main/flyctl/cmd/fly_tokens_create.md

Displays the help option for the 'create' command.

```plaintext
  -h, --help   help for create
```

--------------------------------

### Graceful shutdown in Node.js

Source: https://github.com/superfly/docs/blob/main/blueprints/long-running-tasks.html.md

Node.js example that tracks active jobs, sets a shuttingDown flag on SIGTERM, and polls every 200ms to exit when no jobs remain or after 25 seconds (5s under kill_timeout). New work is rejected once shutdown starts.

```javascript
let activeJobs = 0
let shuttingDown = false

async function runJob(payload) {
  if (shuttingDown) throw new Error("shutting down")
  activeJobs++
  try {
    await doWork(payload)
  } finally {
    activeJobs--
  }
}

process.on("SIGTERM", () => {
  shuttingDown = true
  const start = Date.now()
  const deadline = 25_000 // 5s under kill_timeout
  const tick = setInterval(() => {
    if (activeJobs === 0 || Date.now() - start > deadline) {
      clearInterval(tick)
      process.exit(0)
    }
  }, 200)
})
```

--------------------------------

### Deploy the app

Source: https://github.com/superfly/docs/blob/main/blueprints/autostart-internal-apps.html.md

Run `fly deploy` for the configuration changes to take effect.

```bash
fly deploy
```

--------------------------------

### Fly::Machines.create_and_start_machine

Source: https://github.com/superfly/docs/blob/main/rails/advanced-guides/machine.html.md

Starts a new Fly machine with the given configuration and returns the machine details. This method is used to launch a machine for the job.

```APIDOC
## Fly::Machines.create_and_start_machine

### Description
Starts a new Fly machine with the given configuration and returns the machine details. This method is used to launch a machine for the job.

### Method
POST

### Endpoint
/machines

### Parameters
#### Request Body
- **app** (string) - Required - The name of the Fly application.
- **config** (object) - Required - Machine configuration object.
  - **image** (string) - Required - The Docker image reference to use.
  - **guest** (object) - Required - Guest configuration.
    - **cpus** (integer) - Required - Number of CPUs.
    - **memory_mb** (integer) - Required - Memory in megabytes.
    - **cpu_kind** (string) - Required - CPU kind (e.g., "shared").
  - **env** (object) - Required - Environment variables to set.

### Request Example
{
  "app": "my-app",
  "config": {
    "image": "registry.fly.io/my-app:latest",
    "guest": {
      "cpus": 1,
      "memory_mb": 256,
      "cpu_kind": "shared"
    },
    "env": {
      "SERVER_COMMAND": "curl https://example.com"
    }
  }
}

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created machine.

#### Response Example
{
  "id": "machine_123"
}
```

--------------------------------

### Service Configuration with Management and Public Services

Source: https://github.com/superfly/docs/blob/main/blueprints/connecting-to-user-machines.html.md

Example service configuration for a machine with a management service (internal port 9090, exposed on 9090) and a public HTTP service (internal port 8080, exposed on 80). Both services automatically start when needed and stop when idle.

```json
{
  "services": [
    {
      "name": "management",
      "internal_port": 9090,
      "ports": [
        {
          "port": 9090,
          "handlers": ["http"]
        }
      ]
    },
    {
      "name": "public",
      "internal_port": 8080,
      "ports": [
        {
          "port": 80,
          "handlers": ["http"]
        }
      ]
    }
  ]
}
```

--------------------------------

### Initialize Laravel project and launch Fly app (flyctl)

Source: https://github.com/superfly/docs/blob/main/laravel/advanced-guides/github-actions.html.md

Use composer to create a Laravel project, then run flyctl launch with --region ams and --now to auto-generate fly.toml and deploy immediately.

```cmd
composer create-project laravel/laravel fly-laravel
cd fly-laravel

# Auto generate your `fly.toml` configuration file:
# Add in the ams region with --region
# Auto deploy using --now while your at it!
flyctl launch --region ams --now
```

--------------------------------

### Run Machine with Metadata Flags

Source: https://github.com/superfly/docs/blob/main/machines/flyctl/fly-machine-run.html.md

Starts a Machine that the fly deploy command will manage as part of the app process group, replacing its image and config with the working directory's setup. Uses --metadata flags to set fly_platform_version, fly_process_group, and custom metadata.

```bash
fly machine run . --metadata fly_platform_version=v2 \
                  --metadata fly_process_group=app \
                  --metadata my_metadata=mineallmine
```

--------------------------------

### Deploy and open app with fly deploy and fly apps open

Source: https://github.com/superfly/docs/blob/main/rails/getting-started/existing.html.md

Deploy the application to Fly.io using `fly deploy`, then open it in the browser with `fly apps open`. The deploy command uploads the app, builds a machine image, deploys it, and monitors startup.

```cmd
fly deploy
```

```cmd
fly apps open
```

--------------------------------

### Access Rails console via fly ssh console

Source: https://github.com/superfly/docs/blob/main/rails/the-basics/run-tasks-and-consoles.html.md

Opens an interactive Rails console in the production environment. The `--pty` flag is required for interactive commands. Be careful as you are in production. If you get a 'no such file or directory' error, your app may not be installed in `/rails`; adjust the path accordingly.

```cmd
fly ssh console --pty -C "/rails/bin/rails console"

```

```output
Loading production environment (Rails 7.0.4.2)
irb(main):001:0>

```

--------------------------------

### fly services list output

Source: https://github.com/superfly/docs/blob/main/apps/info.html.md

Example output from the `fly services list` command, showing the configured services with their ports and HTTPS settings.

```out
Services
PROTOCOL        PORTS                   FORCE HTTPS 
TCP             80 => 8080 [HTTP]       True       
                443 => 8080 [TLS,HTTP]  False 
```

--------------------------------

### Create volume and Machine, then wait for boot

Source: https://github.com/superfly/docs/blob/main/blueprints/warm-pool-user-machines.html.md

Creates a volume and a Machine in the same region, then waits for the VM to boot. The volume must be created first and the Machine must mount that volume to land on the same host. The wait endpoint has a timeout default of 60s, which is also the max.

```bash
curl -X POST "https://api.machines.dev/v1/apps/pool-x7f3k2/volumes" \
  -H "Authorization: Bearer ${FLY_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"name": "user_data", "region": "iad", "size_gb": 1}'

# Create the Machine in the *volume's* region
curl -X POST "https://api.machines.dev/v1/apps/pool-x7f3k2/machines" \
  -H "Authorization: Bearer ${FLY_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pool",
    "region": "iad",
    "config": {
      "image": "registry.fly.io/my-user-app@sha256:...",
      "guest": {"cpu_kind": "shared", "cpus": 1, "memory_mb": 2048},
      "init": {"swap_size_mb": 2048},
      "mounts": [{"volume": "vol_abc123", "path": "/data"}],
      "services": [{
        "internal_port": 8080,
        "ports": [{"port": 80, "handlers": ["http"]}],
        "autostart": true,
        "autostop": "off"
      }],
      "checks": {
        "health": {"type": "tcp", "port": 8080, "interval": "15s",
                   "timeout": "5s", "grace_period": "120s"}
      },
      "restart": {"policy": "on-failure", "max_retries": 3},
      "metadata": {"pool_entry": "fp_abc123"}
    }
  }'

# Wait for the VM to boot (timeout defaults to 60s, which is also the max)
curl "https://api.machines.dev/v1/apps/pool-x7f3k2/machines/${MACHINE_ID}/wait?state=started&timeout=60" \
  -H "Authorization: Bearer ${FLY_API_TOKEN}"
```

--------------------------------

### Install flyctl in CI

Source: https://github.com/superfly/docs/blob/main/flyctl/integrating.html.md

Installs flyctl on any Linux-based CI runner. The script detects the architecture and installs the latest release.

```bash
curl -L https://fly.io/install.sh | sh
export PATH="$HOME/.fly/bin:$PATH"

```

--------------------------------

### Dockerfile: Use phusion/passenger-full image

Source: https://github.com/superfly/docs/blob/main/rails/advanced-guides/phusion-passenger.html.md

Replace the default Dockerfile with this one to use the phusion/passenger-full image. It removes default nginx and redis services, adds custom nginx configuration files, sets environment variables, installs gems, precompiles assets, and starts with /sbin/my_init. The image is based on Ruby 3.1 by default, but you can adjust the passenger_ruby line in the nginx config.

```Dockerfile
FROM phusion/passenger-full:2.3.0
RUN rm -f /etc/service/nginx/down
RUN rm -f /etc/service/redis/down

RUN rm /etc/nginx/sites-enabled/default
ADD config/fly/rails.conf /etc/nginx/sites-enabled/rails.conf
ADD config/fly/envvars.conf /etc/nginx/main.d/envvars.conf

ENV RAILS_LOG_TO_STDOUT true

ARG BUNDLE_WITHOUT=development:test
ENV BUNDLE_WITHOUT ${BUNDLE_WITHOUT}

RUN mkdir /app
WORKDIR /app
RUN mkdir -p tmp/pids

COPY Gemfile* ./
RUN bundle install

ENV SECRET_KEY_BASE 1

COPY . .

RUN bundle exec rails assets:precompile

CMD ["/sbin/my_init"]
```

--------------------------------

### Build WireGuard create command step-by-step

Source: https://github.com/superfly/docs/blob/main/blueprints/connect-private-network-wireguard/index.html.md

These commands progressively build the `fly wireguard create` command. Start with the base command and add the organization, region, peer name, and configuration filename in sequence. Do not press enter until the final command is complete.

```shell
$ fly wireguard create

```

```shell
$ fly wireguard create personal

```

```shell
$ fly wireguard create personal yul

```

```shell
$ fly wireguard create personal yul camellia

```

```shell
$ fly wireguard create personal yul camellia camellia.conf

```

--------------------------------

### Check Rails version and create new app

Source: https://github.com/superfly/docs/blob/main/rails/the-basics/active-record.html.md

Verify Rails is installed, then create a new Rails application configured for Postgres and change into its directory.

```shell
$ rails --version
$ rails new list --database postgresql
$ cd list
```

--------------------------------

### Install Ruby on macOS

Source: https://github.com/superfly/docs/blob/main/elixir/advanced-guides/sqlite3.html.md

Install Ruby on macOS using Homebrew.

```cmd
brew install ruby
```

--------------------------------

### Create staging directory and copy fly.toml

Source: https://github.com/superfly/docs/blob/main/django/advanced-guides/staging-environments-with-github-actions.html.md

Commands to create a staging directory and copy the existing fly.toml configuration to staging/fly_staging.toml.

```cmd
mkdir staging

```

```cmd
cp fly.toml staging/fly_staging.toml

```

--------------------------------

### Launch base app with fly launch

Source: https://github.com/superfly/docs/blob/main/blueprints/using-base-images-for-faster-deployments.html.md

Command to create the base app, using --ha=false to use a single Machine and --config to point to the correct config file. Shows expected interaction and output, including the image URL for later use.

```bash
$ fly launch --ha=false --config base.fly.toml
An existing fly.toml file was found for app go-fly-a-site-base
? Would you like to copy its configuration to the new app? Yes
Using build strategies '[the "base.Dockerfile" dockerfile]'. Remove [build] from fly.toml to force a rescan
Creating app in /Users/fly/Code/go-fly-a-site
We're about to launch your app on Fly.io. Here's what you're getting:

...
Region:       Los Angeles, California (US) (from your fly.toml)
App Machines: shared-cpu-1x, 256MB RAM     (from your fly.toml)
...

? Do you want to tweak these settings before proceeding? (y/N)
Created app 'go-fly-a-site-base' in organization 'personal'
Admin URL: https://fly.io/apps/go-fly-a-site-base
Hostname: go-fly-a-site-base.fly.dev
Wrote config file base.fly.toml
...
--> build:
--> Building image done
image: registry.fly.io/go-fly-a-site-base:deployment-01JTKF7JXJ1ZGMA76GCJ5WGZQZ
image size: 233 MB
```

--------------------------------

### Example query result

Source: https://github.com/superfly/docs/blob/main/elixir/advanced-guides/interesting-things-with-livebook.html.md

Example output of the personality_counts query, showing the distribution of personality types.

```elixir
%{any: 77, extrovert: 10, introvert: 13}
```

--------------------------------

### Modify Dockerfile to install foreman, anycable-go, and nginx

Source: https://github.com/superfly/docs/blob/main/rails/advanced-guides/anycable.html.md

This diff shows the changes to the Dockerfile: add lines to install foreman, download Go, install anycable-go, add nginx to the PROD_PACKAGES, and copy the nginx configuration file.

```diff
 FROM base
 
+RUN gem install foreman
+RUN curl -L https://go.dev/dl/go1.19.linux-amd64.tar.gz | tar xz -C /opt
+RUN GOBIN=/usr/local/bin /opt/go/bin/go install github.com/anycable/anycable-go/cmd/anycable-go@latest
+
-ARG PROD_PACKAGES="postgresql-client file vim curl gzip libsqlite3-0"
+ARG PROD_PACKAGES="postgresql-client file vim curl gzip libsqlite3-0 nginx"
 ENV PROD_PACKAGES=${PROD_PACKAGES}
 
 RUN --mount=type=cache,id=prod-apt-cache,sharing=locked,target=/var/cache/apt \
     --mount=type=cache,id=prod-apt-lib,sharing=locked,target=/var/lib/apt \
     apt-get update -qq && \
     apt-get install --no-install-recommends -y \
     ${PROD_PACKAGES} \
     && rm -rf /var/lib/apt/lists /var/cache/apt/archives
+
+ADD config/nginx.conf /etc/nginx/sites-available/default
 
 COPY --from=gems /app /app
 COPY --from=node_modules /app/node_modules /app/node_modules
```

--------------------------------

### Install Arcjet Node SDK

Source: https://github.com/superfly/docs/blob/main/security/arcjet.html.md

Installs the @arcjet/node package to add Arcjet protection to a Node.js application.

```cmd
npm i @arcjet/node
```

--------------------------------

### Install Arcjet SDK and FastAPI dependencies

Source: https://github.com/superfly/docs/blob/main/security/arcjet.html.md

Commands to create a new FastAPI project directory, initialize it with uv, and add the Arcjet SDK along with FastAPI and Uvicorn.

```cmd
mkdir arcjet-fastapi
cd arcjet-fastapi
uv init
uv add arcjet "fastapi[standard]" uvicorn
```

--------------------------------

### Install Django with pip

Source: https://github.com/superfly/docs/blob/main/django/getting-started/index.html.md

Installs the latest version of Django using pip. This should be run with the virtual environment activated.

```cmd
python -m pip install Django
```

--------------------------------

### All-at-once rollback with --strategy immediate

Source: https://github.com/superfly/docs/blob/main/blueprints/rollback-guide.html.md

Use this command to stop old machines and boot the rollback image as quickly as possible. Choose this strategy when speed matters more than downtime.

```bash
fly deploy --image registry.fly.io/myapp:v1.2.3 --strategy immediate
```

--------------------------------

### Generate JobController with start, complete, status actions

Source: https://github.com/superfly/docs/blob/main/rails/advanced-guides/machine.html.md

Generates a Rails controller with three actions: start, complete, and status.

```cmd
bin/rails generate controller job start complete status
```

--------------------------------

### Deploy a subdirectory

Source: https://github.com/superfly/docs/blob/main/launch/monorepo.html.md

Deploy an app from a subdirectory by passing its path as the working directory.

```cmd
fly deploy ./apps/api
```

--------------------------------

### Bring up WireGuard tunnel with wg-quick

Source: https://github.com/superfly/docs/blob/main/networking/private-networking.html.md

Run `wg-quick up mypeer` to activate the tunnel by name (without the .conf extension). The output shows the commands executed to set up the interface and routes.

```cmd
wg-quick up mypeer
```

```output
[#] ip link add mypeer type wireguard
[#] wg setconf mypeer /dev/fd/63
[#] ip -6 address add fdaa:0:4:a7b:ab6:0:a:102/120 dev mypeer
[#] ip link set mtu 1420 up dev mypeer
[#] resolvconf -a tun.mypeer -m 0 -x
[#] ip -6 route add fdaa:0:4::/48 dev mypeer
```

--------------------------------

### Launch Fetch MCP server

Source: https://github.com/superfly/docs/blob/main/mcp/examples.html.md

Launches the Fetch MCP server using uvx, configured for Claude.

```sh
fly mcp launch "uvx mcp-server-fetch" --claude --server fetch
```

--------------------------------

### Generate Dockerfile with Fly Launch

Source: https://github.com/superfly/docs/blob/main/js/the-basics/dockerfiles.html.md

Run 'fly launch' to automatically generate a Dockerfile for your application. This is the recommended starting point for deploying Bun, Deno, and Node.js apps on Fly.io.

```cmd
fly launch
```

--------------------------------

### Example NATS subject with wildcard

Source: https://github.com/superfly/docs/blob/main/monitoring/logs-api-options.html.md

This example shows a NATS subject with a wildcard for the instance, allowing subscription to all instances of an app in a region.

```text
logs.my-app.lhr.*
```

--------------------------------

### Deploy a prebuilt image

Source: https://github.com/superfly/docs/blob/main/blueprints/working-with-docker.html.md

Deploys a previously built image from the Fly.io registry. Replace the tag with the actual image tag from the build step.

```bash
fly deploy --image registry.fly.io/myapp:your-tag-here
```

--------------------------------

### Show WireGuard create command help

Source: https://github.com/superfly/docs/blob/main/blueprints/connect-private-network-wireguard/index.html.md

Displays the usage and flags for the `fly wireguard create` command. Run this to see the expected arguments: [org] [region] [name] [file].

```shell
$ fly wg create --help
Add a WireGuard peer connection to an organization

Usage:
  fly wireguard create [org] [region] [name] [file] [flags]

```

--------------------------------

### Network error message example

Source: https://github.com/superfly/docs/blob/main/elixir/the-basics/clustering.html.md

Example error message indicating a node connection failure, possibly due to missing IPv6 settings.

```text
Could not contact remote node my-app@fdaa:0:31d4:a5b:9d36:7c1e:f284:2, reason: :nodedown. Aborting...
```

--------------------------------

### Launch Fly app and generate Dockerfile with LiteFS

Source: https://github.com/superfly/docs/blob/main/rails/advanced-guides/litefs.html.md

Run 'fly launch' to initialize the Fly app, then generate a Dockerfile with LiteFS support. The generator prompts for acceptance of changes; use --force to skip prompts.

```sh
fly launch
bin/rails generate dockerfile --litefs
```

--------------------------------

### Region preference examples

Source: https://github.com/superfly/docs/blob/main/machines/guides-examples/machine-placement.html.md

These are example region preference strings for use with machine operations. They show how to combine specific regions and geographic aliases to control placement.

```text
lhr,eu
```

```text
us,eu
```

```text
na,sa
```
Tokens:
Raw