Add volume storage to a Fly Launch app

Fly Volumes are local persistent storage for Fly Machines.

Learn more:

Launch a new app with a Fly Volume

Use Fly Launch to create a new app with one Machine and an attached volume, and then clone the Machine to scale out.

  1. Launch a new app from your project source directory with the --no-deploy option so it doesn’t deploy automatically. Include any required options for deploying your app, like --image or --dockerfile.

    fly launch --no-deploy

    fly launch creates a fly.toml app configuration file in your project source directory.

  2. After the app is created, add a [mounts] section in the fly.toml, where source is the volume name and destination is the directory where the volume should be mounted on the Machine file system. For example:

    [mounts]
  source = "myapp_data"
  destination = "/data"

    Note: You can’t mount a volume with destination="/" since / is used for the root file system.

  3. Deploy the app:

    fly deploy

  4. Confirm that the volume is attached to a Machine.

  5. (Recommended only if your app handles replication) Clone the first Machine to scale out to two Machines with volumes:

    fly machine clone <machine id>

    List volumes to check the result:

    fly volumes list

    Example output showing two volumes with attached Machines:

    ID                      STATE   NAME    SIZE    REGION  ZONE    ENCRYPTED       ATTACHED VM     CREATED AT     
vol_ez1nvxkwl3jrmxl7    created data    1GB     lhr     4de2    true            91851edb6ee983  39 seconds ago
vol_zmjnv8m81p5rywgx    created data    1GB     lhr     b6a7    true            5683606c41098e  7 minutes ago

Warning: fly machine clone doesn’t write data into the new volume.

Add volumes to an existing app

Add a volume to an app created with Fly Launch.

  1. Add a [mounts] section in the app’s fly.toml, where source is the volume name and destination is the directory where the volume should be mounted on the Machine file system. For example:

    [mounts]
  source = "myapp_data"
  destination = "/data"

  2. Run fly status to check the regions of the Machines and then create the volume in the same regions as your app’s Machines. For example:

    fly volumes create <volume name> -r <region code>

  3. Repeat step 2 for each Machine in the process group. If you create an app using the fly launch command, then the app will usually have two Machines in the app process by default.

    Note: If you have multiple Machines, then you need to create an equal number of volumes with the same name. For example, your app’s [mounts] config specifies source="myapp_data" and you have three Machines in bos (Boston), then you need to create three volumes named myapp_data in bos. Every volume has a unique ID to allow for multiple volumes with the same name.

  4. Deploy the app:

    fly deploy

  5. Confirm that the volume is attached to a Machine.

Confirm the volume is attached to a Machine

Use flyctl to check the status of volumes and Machines.

List the Machines

List Machines to check attached volumes:

fly machine list

Example output:

1 machines have been retrieved from app my-app-name.
View them in the UI here

my-app-name
ID              NAME        STATE   REGION   IMAGE                  IP ADDRESS                      VOLUME                  CREATED                 LAST UPDATED            APP PLATFORM    PROCESS GROUP   SIZE
328773d3c47d85  my-app-name stopped yul     flyio/myimageex:latest  fdaa:2:45b:a7b:19c:bbd4:95bb:2  vol_6vjywx86ym8mq3xv    2023-08-20T23:09:24Z    2023-08-20T23:16:15Z    v2              app             shared-cpu-1x:256MB

List the volumes

List volumes to check attached Machines:

fly volumes list

Example output:

ID                      STATE   NAME    SIZE    REGION  ZONE    ENCRYPTED       ATTACHED VM     CREATED AT    
vol_zmjnv8m81p5rywgx    created data    1GB     lhr     b6a7    true            5683606c41098e  3 minutes ago

SSH into the Machine

View the volume in the Machine file system:

fly ssh console -s -C df

Example output showing a 1GB volume mounted at /data:

? Select VM: lhr: 5683606c41098e fdaa:0:3b99:a7b:7e:3155:9844:2 nameless-feather-6339
Connecting to fdaa:0:3b99:a7b:7e:3155:9844:2... complete
Filesystem     1K-blocks   Used Available Use% Mounted on
devtmpfs          103068      0    103068   0% /dev
/dev/vda         8191416 172748   7582856   3% /
shm               113224      0    113224   0% /dev/shm
tmpfs             113224      0    113224   0% /sys/fs/cgroup
/dev/vdb         1011672   2564    940500   1% /data

The volume is mounted in the directory specified by the destination field in the [mounts] section of the fly.toml file, or the attach-volume option for cloned Machines.

Access a volume

Access and write to a volume on a Machine just like a regular directory.

For Machines managed with Fly Launch, the destination under [mounts] in fly.toml is the path for the mounted volumes.

For unmanaged Machines, you specify the mount path when you add a volume to a cloned Machine or create a Machine and attach a volume.

Related topics

Report an issue or edit this page on GitHub