--- title: Add volume storage to a Fly Launch app layout: docs nav: apps redirect_from: /docs/apps/volume-storage/ --- Fly Volumes are local persistent storage for [Fly Machines](/docs/machines/). Learn more: - [How Fly Volumes work](/docs/volumes/overview/) - [How to manage volumes with flyctl commands](/docs/volumes/volume-manage/) - [How to manage volume snapshots (backups)](/docs/volumes/snapshots) ## Launch a new app with a Fly Volume Use [Fly Launch](/docs/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`. ```cmd fly launch --no-deploy ``` `fly launch` creates a `fly.toml` app configuration file in your project source directory. 1. After the app is created, add a [`[mounts]` section](/docs/reference/configuration/#the-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: ```toml [mounts] source = "myapp_data" destination = "/data" ``` <div class="note icon"> <b>Note:</b> You can't mount a volume with `destination="/"` since `/` is used for the root file system. </div> 1. Deploy the app: ```cmd fly deploy ``` 1. [Confirm that the volume is attached to a Machine](#confirm-the-volume-is-attached-to-a-machine). 1. (Recommended only if your app handles replication) Clone the first Machine to scale out to two Machines with volumes: ```cmd fly machine clone <machine id> ``` List volumes to check the result: ```cmd fly volumes list ``` Example output showing two volumes with attached Machines: ```out 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 ``` <div class="warning icon"> <b>Warning:</b> `fly machine clone` doesn't write data into the new volume. </div> ## Add volumes to an existing app Add a volume to an app created with [Fly Launch](/docs/launch/). 1. Add a [`[mounts]` section](/docs/reference/configuration/#the-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: ```toml [mounts] source = "myapp_data" destination = "/data" ``` 2. Run `fly status` to check the [regions](/docs/reference/regions/) of the Machines and then create the volume in the same regions as your app's Machines. For example: ```cmd 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. <div class="note icon"> **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. </div> 4. Deploy the app: ```cmd fly deploy ``` 5. [Confirm that the volume is attached to a Machine](#confirm-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: ```cmd fly machine list ``` Example output: ```out 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: ```cmd fly volumes list ``` Example output: ```out 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: ```cmd fly ssh console -s -C df ``` Example output showing a 1GB volume mounted at `/data`: ```out ? 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 <%= partial "/docs/partials/docs/volumes_access" %> ## Related topics - [Fly Volumes overview](/docs/volumes/overview/) - [`mounts` section](/docs/reference/configuration/#the-mounts-section) in the `fly.toml` app configuration file - [Create and manage volumes](/docs/volumes/volume-manage/) - [Manage volume snapshots](/docs/volumes/snapshots/) - [Scale an app with volumes](/docs/apps/scale-count/#scale-an-app-with-volumes)

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.

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.
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.
Deploy the app:
```
fly deploy 
```
Confirm that the volume is attached to a Machine.

(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.

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"
```
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>
```
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.
Deploy the app:
```
fly deploy 
```
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.

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

or Open in ChatGPT

Report an issue or edit this page on GitHub

On this page

Open in ChatGPT