Add volume storage to a Fly Launch app

Fly Volumes are local persistent storage for Fly Machines.

Learn more:

• How Fly Volumes work
• How to manage volumes with flyctl commands
• How to manage volume snapshots (backups)

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

• Fly Volumes overview
• mounts section in the fly.toml app configuration file
• Create and manage volumes
• Manage volume snapshots
• Scale an app with volumes