13 |
14 | This guide works through setting up your app for continuous deployment to Fly.io from the app's GitHub repository. You might also like our blueprint on [deploying review apps with GitHub Actions](/docs/blueprints/review-apps-guide/).
15 |
16 | You'll start with an example application called [go-example](https://github.com/fly-apps/go-example+external). It's a simple, lightweight app that displays the Fly.io region that served the request.
17 |
18 | The first section is a speed-run through the steps to make the go-example app automatically deploy to Fly.io from GitHub. The next section loops back for a [longer look at each step](#a-longer-look-at-the-deployment-process).
19 |
20 | ## Speed-run your way to continuous deployment
21 |
22 | 1. Fork the [go-example](https://github.com/fly-apps/go-example+external) repository to your GitHub account.
23 | 2. Clone the new repository to your local machine.
24 | 3. Run `fly launch --no-deploy` from within the project source directory to create a new app and a `fly.toml` configuration file.
25 | 4. Type `y` to when prompted to tweak settings and enter a name for the app. Adjust other settings, such as region, as needed. Then click **Confirm Settings**.
26 | 5. Still in the project source directory, get a Fly API deploy token by running `fly tokens create deploy -x 999999h`. Copy the output, including the `FlyV1` and space at the beginning.
27 | 6. Go to your newly-created repository on GitHub and select **Settings**.
28 | 7. Under **Secrets and variables**, select **Actions**, and then create a new repository secret called `FLY_API_TOKEN` with the value of the token from step 5.
29 | 8. Back in your project source directory, create `.github/workflows/fly.yml` with these contents:
30 |
31 | ```yaml
32 | name: Fly Deploy
33 | on:
34 | push:
35 | branches:
36 | - master # change to main if needed
37 | jobs:
38 | deploy:
39 | name: Deploy app
40 | runs-on: ubuntu-latest
41 | concurrency: deploy-group # optional: ensure only one action runs at a time
42 | steps:
43 | - uses: actions/checkout@v4
44 | - uses: superfly/flyctl-actions/setup-flyctl@master
45 | - run: flyctl deploy --remote-only
46 | env:
47 | FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
48 | ```
49 |
50 |
51 | **Note:** The `go-example`’s default branch is `master`. If you’re using a different app, yours might be `main`. Change the `branches` value in the `fly.yml` file accordingly.
52 |
53 |
54 | 9. Commit your changes and push them up to GitHub. You should be pushing two new files: `fly.toml`, the [Fly Launch](/docs/launch/) configuration file, and `fly.yml`, the GitHub action file.
55 |
56 | Then the magic happens - The push triggers a deploy, and from now on whenever you push a change, the app will automatically be redeployed.
57 |
58 | If you want to watch the process take place, head to the repository and select the **Actions** tab, where you can view live logs of the commands running.
59 |
60 | ## A longer look at the deployment process
61 |
62 | ### `fly.toml` and the repository
63 |
64 | **Step 1** is a simple GitHub Fork; there's not a lot to say about that except that you need to do it, because you want control of the repository that you're deploying from.
65 |
66 | **Step 2** is just cloning the repository to your local system so that you can edit and push changes to it.
67 |
68 | **Steps 3 and 4** create a new app on Fly.io and a `fly.toml` configuration file to go into the repository.
69 |
70 |
71 | A note about `fly.toml` in repositories: Usually, when Fly.io ships examples, we avoid putting the `fly.toml` file in the repository by including `fly.toml` in the `.gitignore` file. And users should be creating their own `fly.toml` with the `fly launch` command. When using GitHub Actions though, you want your `fly.toml` in the repository so that the action can use it in the deployment process.
72 |
73 |
74 | ### API tokens
75 |
76 | **Step 5** is about getting an API token. You can generate a deploy token to use to authorize a specific application. That's what `flyctl tokens create deploy -x 999999h` gives you. Remember to copy the whole token from the output, including the `FlyV1` and space at the beginning.
77 | For a more powerful token that can manage multiple applications, run `flyctl auth token`.
78 |
79 | **Steps 6 and 7** make your new token available to GitHub Actions that run against your repository. You'll add the token as a secret in the repository's settings. Under the **Settings** tab, go to **Secrets and variables** and select **Actions**. Click on the green "New repository secret" button, enter the name as `FLY_API_TOKEN`, and copy the token as the secret.
80 |
81 | If you'd prefer an environment secret instead, then you need to list the environment you selected in your deploy step. For example:
82 |
83 | ```yaml
84 | deploy:
85 | name: Deploy app
86 | runs-on: ubuntu-latest
87 | environment: production
88 | ```
89 |
90 | ### Building the workflow and deployment
91 |
92 | **Step 8** is the heart of the process, where you put in place a workflow. Now, GitHub has a UI which allows you to select and edit workflows, but you can also modify them as part of the repository. So you create `.github/workflows/fly.yml` - you'll likely want to `mkdir -p .github/workflows` to quickly create the directories - and load up the file with a GitHub Action recipe.
93 |
94 | GitHub Action recipe, line by line:
95 |
96 | ```yaml
97 | name: Fly Deploy
98 | ```
99 |
100 | This sets the displayed name for the action.
101 |
102 | ```yaml
103 | on:
104 | push:
105 | branches:
106 | - master
107 | ```
108 |
109 | When should this action be run. There's lots of options but in this case, in response to any `push` to the repository's `master` branch. If your repository uses a default branch other than `master`, such as `main`, then you should change that here.
110 |
111 | ```yaml
112 | jobs:
113 | deploy:
114 | name: Deploy app
115 | runs-on: ubuntu-latest
116 | concurrency: deploy-group
117 | ```
118 |
119 | An action is made up of named jobs, in this case one job to deploy the application. The jobs run on a virtual machine. This section gives the "deploy" job the name "Deploy app" and tells GitHub Actions to run it on a virtual machine with the latest version of Ubuntu on it. Optionally, use the `concurrency` key with a custom group name to ensure that only one action runs at a time for that group.
120 |
121 | The next part is to set up the steps needed to complete this job.
122 |
123 | ```yaml
124 | steps:
125 | - uses: actions/checkout@v4
126 | ```
127 |
128 | The first step is one of the built in Actions steps. The step `uses` the [`checkout@v4` action](https://github.com/marketplace/actions/checkout+external) which checks out the repository into a directory on the virtual machine. You're now ready to deploy.
129 |
130 | ```yaml
131 | - uses: superfly/flyctl-actions/setup-flyctl@master
132 | - run: flyctl deploy --remote-only
133 | ```
134 |
135 | This step `uses` the [superfly/flyctl-actions action](https://github.com/marketplace/actions/github-action-for-flyctl+external). This is a GitHub action created by Fly.io which wraps around the `flyctl` command. The wrapper is invoked with the `deploy` argument which will take over the process of building and moving the application to the Fly.io infrastructure. It uses the settings from the `fly.toml` file to guide it and uses the `FLY_API_TOKEN` to authorize its access to the Fly.io GraphQL API.
136 |
137 | ```yaml
138 | env:
139 | FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
140 | ```
141 |
142 | This pulls the API token from GitHub's secrets engine and puts it into the environmental variables passed to the action.
143 |
144 | **Step 9** pushes your two new files to the repository: `fly.toml`, the app configuration file, and `fly.yml`, the GitHub action file. The push triggers your first automatic deploy. The GitHub action now triggers a redeploy each time you push changes to your repo.
145 |
146 | ## Conclusion and further reading
147 |
148 | And that's the deployment process. You can, of course, leverage the GitHub Actions environment to manage more intricate deployments, interact with other applications—say to send Slack messages on completion—or whatever else you can dream up.
149 |
150 | **Read:**
151 |
152 | * [Blueprint: Deploy review apps with GitHub Actions](/docs/blueprints/review-apps-guide/)
153 | * [Deploy Tokens](/docs/reference/deploy-tokens/)
154 | * [GitHub Actions Documentation](https://docs.github.com/en/actions+external)
155 |
156 | **See:**
157 |
158 | * [GitHub Actions for flyctl](https://github.com/superfly/flyctl-actions+external)
159 |
--------------------------------------------------------------------------------
/launch/create.html.markerb:
--------------------------------------------------------------------------------
1 | ---
2 | title: Create an app with Fly Launch
3 | layout: docs
4 | nav: apps
5 | redirect_from: /docs/apps/launch/
6 | ---
7 |
8 | 
10 | 
10 | 
13 |
50 | **Important:** Make sure processes handle connections on different [external ports](/docs/reference/configuration/#services-ports). Fly Proxy doesn't know about process groups; it load-balances requests among all Machines with a service configured on the requested port.
51 |
52 |
53 | ## Deployment
54 |
55 | `fly deploy` creates at least one Machine for each process group, and destroys all the Machines that belong to any process group that isn't defined, in your app's `fly.toml` file. It also updates the command, services, and health checks for each `fly deploy`-managed Machine on the app; and creates a new app release.
56 |
57 | So on the first deployment (either at the end of `fly launch` or at the first explicit `fly deploy`), flyctl creates and starts at least one Machine for each process group in `fly.toml`.
58 |
59 | If you add new process groups in an app's `[processes]` block, then the next `fly deploy` spins up at least one new Machine to run each new process.
60 |
61 | If you remove any process groups from an app's `[processes]` block, then the next `fly deploy` destroys the Machines that belong to the deleted process.
62 |
63 | For more information about how many Machines are created by `fly launch` and `fly deploy`, refer to [App Availability and Resiliency](/docs/reference/app-availability/).
64 |
65 | ## Scale a process group horizontally
66 |
67 | There are two ways to scale the number of Machines in an app. This section provides a summary of horizontal scaling. For more information, refer to [Scale the Number of Machines](/docs/apps/scale-count/#change-the-number-of-machines-in-a-process-group).
68 |
69 | ### Scale a process group horizontally with `fly scale count`
70 |
71 | You can scale the number of Machines (up or down) per process group with the `fly scale count` command. The following example scales the `web` process group to 8 Machines, and the `cron` process group to 2 Machines:
72 |
73 | ```
74 | fly scale count web=8 cron=2
75 | ```
76 |
77 | You can scale by [region](/docs/reference/regions/) with the `--region` option. Specify multiple regions and the Machines will be distributed as evenly as possible between them. The following command would create 2 Machines in `gru` and 2 Machines in `bog`:
78 |
79 | ```cmd
80 | fly scale count web=4 --region gru,bog
81 | ```
82 |
83 | ### Scale a process group horizontally with `fly machine clone`
84 |
85 | You can also use the `fly machine clone` and `fly machine destroy` commands to scale the number of Machines individually within a process group. When you clone a Machine that belongs to a process group, the new Machine is created with the command, services, and checks that are configured on the app for that process.
86 |
87 | You can add a [region](/docs/reference/regions/) to your app by cloning a Machine into a new region.
88 |
89 | First, run `fly status` to get a list of Machines with IDs and process groups.
90 |
91 | The following example clones a Machine into the `gru` (São Paulo) region:
92 |
93 | ```
94 | fly machine clone --region gru e2865641be9786
95 | ```
96 |
97 | Run the following command to force stop and destroy a Machine:
98 |
99 | ```
100 | fly machine destroy e2865641be9786 --force
101 | ```
102 |
103 | ## Scale a process group vertically
104 |
105 | You can scale Machine CPU and memory settings for an entire process group using the `fly scale vm` and `fly scale memory` commands. This section provides a summary of vertical scaling. For more information, refer to [Scale Machine CPU and RAM](/docs/apps/scale-machine/#scale-by-process-group).
106 |
107 |
108 | **Note**: The `--process-group` option is aliased to `-g` for faster command entry.
109 |
110 |
111 | The following example changes the CPU/RAM of Machines in the `web` process group to a different preset combination:
112 |
113 | ```
114 | fly scale vm performance-2x --process-group web
115 | ```
116 |
117 | Run `fly platform vm-sizes` for a list of the valid CPU/RAM preset combinations.
118 |
119 | This example changes only the RAM of Machines in the `web` process group:
120 |
121 | ```
122 | fly scale memory 4096 --process-group web
123 | ```
124 |
125 | ## Move a Machine between process groups
126 |
127 | You can change the process group of an existing Machine by updating its metadata:
128 |
129 | ```cmd
130 | fly machine update --metadata fly_process_group=app 21781973f03e89
131 | ```
132 | Then deploy the app to apply the configuration for that process group to the Machine:
133 |
134 | ```cmd
135 | fly deploy
136 | ```
137 |
--------------------------------------------------------------------------------
/launch/scale-count.html.markerb:
--------------------------------------------------------------------------------
1 | ---
2 | title: Scale the Number of Machines
3 | layout: docs
4 | nav: apps
5 | redirect_from:
6 | - /docs/reference/scaling/
7 | - /docs/apps/scale-count/
8 | ---
9 |
10 | 
12 |
17 | Starting and stopping existing Machines is much faster than creating and destroying them. Stopped Machines are cheaper than running ones. Machines release their CPU and RAM when they stop, and their rootfs is rebuilt fresh from their Docker image, ready to start.
18 |
19 | For bursty workloads, we recommend creating enough Machines to handle your peak load, and adjusting the active capacity of the app by stopping and starting Machines as needed.
20 |
21 | For more information, see:
22 | * [Automatically Stop and Start App Machines](/docs/launch/autostop-autostart/), for adjusting active capacity based on traffic.
23 | * [Autoscale based on metrics](/docs/launch/autoscale-by-metric/), to use the autoscaler app to scale Machines based on any metric.
24 | * [`fly machine` commands](/docs/flyctl/machine/), including [`start`](/docs/flyctl/machine-start/) and [`stop`](/docs/flyctl/machine-start/) subcommands to target individual Machines with flyctl.
25 | * Machines API [stop](/docs/machines/api-machines-resource/#stop-a-machine) and [start](/docs/machines/api-machines-resource/#start-a-machine) endpoints.
26 |
27 |
28 | There are two ways to change the number of Machines managed by [Fly Launch](/docs/launch/) after deploying an app for the first time:
29 |
30 | 1. with the `fly scale count` subcommand
31 | 2. by explicitly [cloning](#scale-up-with-fly-machine-clone) or [destroying](#scale-down-with-fly-machine-destroy) existing Machines on the app
32 |
33 | `fly scale count` uses internal rules to create or destroy Machines to reach the target scale that you specify. Machines get created when the target number of Machines is higher than the existing total, and Machines get destroyed when the target number of Machines is lower than the existing total.
34 |
35 | When Machines are created or destroyed using `fly scale count` or `fly machine clone`/`fly machine destroy`, the resulting scale is preserved by `fly deploy`—except in the case that you scale right down to zero Machines. If there are no existing Machines, then `fly deploy` seeds the app with new Machines in the `primary_region` and according to the `[processes]` configured in your `fly.toml` file. For more information about how many Machines are created when you launch a new app or deploy from zero, refer to [Redundancy by default on first deploy](/docs/reference/app-availability/#redundancy-by-default-on-first-deploy).
36 |
37 | ## View the app's current scale
38 |
39 | `fly scale show` outputs all the scale information about an app's Machines: how many Machines of each VM specification, in each of the app's process groups, in each [region](/docs/reference/regions/).
40 |
41 | Here's an example to illustrate that:
42 |
43 | ```cmd
44 | fly scale show
45 | ```
46 | ```out
47 | VM Resources for app: my-app-name
48 |
49 | Groups
50 | NAME COUNT KIND CPUS MEMORY REGIONS
51 | app 3 shared 4 1024 MB mia,scl(2)
52 | disk 3 shared 4 1024 MB ord(2),scl
53 | task 4 performance 1 2048 MB iad,mia,ord,scl
54 | ```
55 |
56 | This app has 10 Machines total. The `app` process group has two in scl (Santiago) and one in mia (Miami). `disk` has two in ord (Chicago) and one in scl. `task` has one Machine in each of iad (Ashburn), mia, ord, and scl. You can put your Machines wherever works best for your app.
57 |
58 | ## Scale the number of Machines in a single region
59 |
60 | The following examples apply to a Fly App's default process group: the `app` process group. If you don't define [process groups](/docs/apps/processes/), then all of the app's Machines belong to the `app` process group, with the exception of any Machines created with `fly machine` commands or the Machines API.
61 |
62 | `fly scale count` applies changes to the default process group if it is not [passed explicit per-process target counts](#change-the-number-of-machines-in-a-process-group).
63 |
64 | Here's the `fly scale show` output for a newly deployed web app, with two machines in yyz (Toronto):
65 |
66 | ```cmd
67 | fly scale show
68 | ```
69 | ```out
70 | VM Resources for app: my-app-name
71 |
72 | Groups
73 | NAME COUNT KIND CPUS MEMORY REGIONS
74 | app 2 shared 1 256 MB yyz(2)
75 | ```
76 |
77 | The simplest way to scale up is by using `fly scale count
100 | The `fly scale count` command creates new empty volumes, or attaches existing volumes, and does not copy or move any data between volumes.
101 |
102 |
103 | In this example, the app starts with 1 Machine with an attached volume in the `disk` process and 1 unattached volume, all in the yul region. The following command to scale the `disk` process to 3 Machines creates 2 new Machines and 1 new volume:
104 |
105 | ```cmd
106 | fly scale count disk=3 --region yul
107 | ```
108 | ```output
109 | App 'my-app-name' is going to be scaled according to this plan:
110 | +2 machines for group 'disk' on region 'yul' with size 'shared-cpu-1x'
111 | +1 new volumes and using 1 existing volumes for group 'disk' in region 'yul'
112 | ? Scale app my-app-name? (y/N)
113 | ```
114 |
115 | Note that the preceding example specifies:
116 | - The region where we have unattached volumes and want the Machines to live.
117 | - The process group, because our `my-app-name` app has volumes for Machines that belong to the `disk` process group.
118 |
119 | ## Scale an app's regions
120 |
121 | The `--region` option takes one or more [region codes](/docs/reference/regions/). `fly scale count` creates and/or destroys Machines to reach the specified target count across the regions you list in this option, and tries to balance its changes across these regions.
122 |
123 | For example, to end up with a total of three Machines between the yyz (Toronto) and ewr (Secaucus) regions on an app:
124 |
125 | ```cmd
126 | fly scale count 3 --region yyz,ewr
127 | ```
128 |
129 | In the above example, the resulting total Machine count seen with `fly scale show` will be more than 3 if the app has existing Machines in regions other than yyz and ewr:
130 |
131 | ```
132 | Groups
133 | NAME COUNT KIND CPUS MEMORY REGIONS
134 | web 4 shared 1 256 MB ewr,mia,yyz(2)
135 | ```
136 |
137 | You can also set the scale explicitly per region by specifying a single region per `fly scale` command. For example:
138 |
139 | ```cmd
140 | fly scale count 4 --region ewr
141 | ```
142 |
143 | If `--region` is not used, then the target count is distributed across all the regions in which the app already has Machines that belong to any process group.
144 |
145 | ## Scale by process group
146 |
147 | `fly scale count` takes explicit target counts per process group.
148 |
149 | Here's an app with two process groups running in two regions, nrt (Tokyo) and yyz (Toronto):
150 |
151 | ```cmd
152 | fly scale show
153 | ```
154 | ```out
155 | VM Resources for app: my-app-name
156 |
157 | Groups
158 | NAME COUNT KIND CPUS MEMORY REGIONS
159 | web 4 shared 1 256 MB nrt(2),yyz(2)
160 | worker 4 shared 1 256 MB nrt(2),yyz(2)
161 | ```
162 |
163 | Scale it out to 10 `web` Machines and 6 `worker` Machines, without constraining the change by region:
164 |
165 | ```cmd
166 | fly scale count web=10 worker=6
167 | ```
168 | ```out
169 | App 'my-app-name' is going to be scaled according to this plan:
170 | +3 machines for group 'web' on region 'yyz' with size 'shared-cpu-1x'
171 | +3 machines for group 'web' on region 'nrt' with size 'shared-cpu-1x'
172 | +1 machines for group 'worker' on region 'yyz' with size 'shared-cpu-1x'
173 | +1 machines for group 'worker' on region 'nrt' with size 'shared-cpu-1x'
174 | ? Scale app my-app-name? Yes
175 | Executing scale plan
176 | Created 9080eeddc29387 group:web region:yyz size:shared-cpu-1x
177 | ...
178 | Created 1781779b52d489 group:worker region:nrt size:shared-cpu-1x
179 | ```
180 |
181 | ```cmd
182 | fly scale show
183 | ```
184 | ```out
185 | ...
186 | Groups
187 | NAME COUNT KIND CPUS MEMORY REGIONS
188 | web 10 shared 1 256 MB nrt(5),yyz(5)
189 | worker 6 shared 1 256 MB nrt(3),yyz(3)
190 | ```
191 |
192 | If an app has more capacity than required in a particular region, then you can also scale Machines by region. The following example scales both processes down by one Machine in only the yyz (Toronto) region:
193 |
194 | ```cmd
195 | fly scale count web=4 worker=2 --region yyz
196 | ```
197 |
198 | As requested, nrt is unchanged, but in yyz the `web` process is scaled down to 4 and `worker` to 2 Machines.
199 |
200 | ```
201 | Groups
202 | NAME COUNT KIND CPUS MEMORY REGIONS
203 | web 9 shared 1 256 MB nrt(5),yyz(4)
204 | worker 5 shared 1 256 MB nrt(3),yyz(2)
205 | ```
206 |
207 | You can also specify a single process group to scale using the `--process-group` option:
208 |
209 | ```cmd
210 | fly scale count 4 --process-group web --region nrt,yyz
211 | ```
212 |
213 | ## Add a new region
214 |
215 | Adding a region to an app just means putting at least one Machine there.
216 |
217 | For example, add syd (Sydney) to an app's regions by scaling up from 0 there:
218 |
219 | ```cmd
220 | fly scale count 2 --region syd
221 | ```
222 |
223 | Now syd will show up in the app's `regions list`:
224 |
225 | ```cmd
226 | fly regions list
227 | ```
228 | ```out
229 | Regions [app]: yyz, syd
230 | ```
231 |
232 | If the app has multiple process groups, specify which process or processes to put in the new region:
233 |
234 | ```
235 | fly scale count web=1 worker=1 --region syd
236 | ```
237 |
238 | Alternatively, you can [clone](#scale-up-with-fly-machine-clone) specific Machines to a new region, and the new Machine inherits the process group of its source Machine.
239 |
240 |
241 | ## Balance Machines between regions with `--max-per-region`
242 |
243 | Use `--max-per-region` for added control over Machine placement by region if the changes proposed by `fly scale count` look unbalanced. This option caps the resulting count of Machines in any one region to the number you provide.
244 |
245 |
246 | You can also use `--max-per-region` to redistribute the Machine count more evenly among regions.
247 |
248 | For example, on an app with 8 machines in yyz (Toronto), 2 in yul (Montreal) and only 1 in ewr (Secaucus):
249 |
250 | ```
251 | NAME COUNT KIND CPUS MEMORY REGIONS
252 | app 11 shared 1 256 MB ewr,yul(2),yyz(8)
253 | ```
254 |
255 | ```cmd
256 | fly scale count 11 --max-per-region 5
257 | ```
258 |
259 | ```
260 | NAME COUNT KIND CPUS MEMORY REGIONS
261 | app 11 shared 1 256 MB ewr(3),yul(3),yyz(5)
262 | ```
263 |
264 | You can combine `--max-per-region` with process groups and `--region` in a single `fly scale count` command.
265 |
266 | ## Scale to zero and back up
267 |
268 | Scale to zero Machines with `fly scale count`. Don't leave out any processes:
269 |
270 | ```cmd
271 | fly scale count web=0 worker=0
272 | ```
273 |
274 | Check that it worked:
275 |
276 | ```cmd
277 | fly scale show
278 | ```
279 | ```out
280 | VM Resources for app: my-app-name
281 |
282 | Groups
283 | NAME COUNT KIND CPUS MEMORY REGIONS
284 |
285 | ```
286 |
287 | Now if there are no Machines in any process groups, we can't just scale up, because `fly scale count` relies on essentially cloning an existing Machine. But we can simply redeploy:
288 |
289 |
290 | ```cmd
291 | fly deploy
292 | ```
293 |
294 | ```cmd
295 | fly scale show
296 | ```
297 | ```out
298 | ...
299 | Groups
300 | NAME COUNT KIND CPUS MEMORY REGIONS
301 | web 2 shared 1 256 MB yyz(2)
302 | worker 2 shared 1 256 MB yyz(2)
303 | ```
304 |
305 | `fly deploy` creates two Machines per process, for resilience purposes.
306 |
307 | We're back in business and can scale as desired!
308 |
309 | ## Scale up with `fly machine clone`
310 |
311 | You can add Machines to an app by cloning Machines. The new Machine will be, as you would expect, a copy of the specified Machine, and will belong to the same process group. If the original Machine has a [Fly Volume](/docs/volumes/) attached, an empty volume will be provisioned for the new Machine. It's up to you to decide what to put on the new volume; `fly machine clone` will not automatically copy the contents of the original Machine's volume.
312 |
313 | The following commands create three new Machines by cloning an existing Machine:
314 |
315 | ```
316 | $ fly machine clone 21781973f03e89
317 | $ fly machine clone --region syd 21781973f03e89
318 | $ fly machine clone --region nrt 21781973f03e89
319 | ```
320 |
321 | ## Scale down with `fly machine destroy`
322 |
323 | Use `fly machine stop` and `fly machine destroy` to scale down the app by removing specific Machines:
324 |
325 | ```
326 | $ fly machine stop 9080524f610e87
327 | $ fly machine destroy 9080524f610e87
328 | ```
329 |
330 | If a Machine is misbehaving (for instance, it's not `stop`ping successfully), you can use `fly machine destroy --force` to get rid of it.
331 |
332 | ```cmd
333 | fly machine destroy --force 0e286039f42e86
334 | ```
335 |
336 | If you destroy a Machine with a volume attached, the volume remains intact until you either explicitly destroy the volume or destroy the app it belongs to.
337 |
--------------------------------------------------------------------------------
/launch/scale-machine.html.markerb:
--------------------------------------------------------------------------------
1 | ---
2 | title: Scale Machine CPU and RAM
3 | layout: docs
4 | nav: apps
5 | redirect_from: /docs/apps/scale-machine/
6 | ---
7 |
8 | You can scale Machine memory and CPU settings for entire process groups in apps that are managed by Fly Launch (`fly deploy` + `fly.toml`). If you haven't defined any process groups, then commands and settings are applied to all the Machines in your app (in the default `app` process group).
9 |
10 |
11 | You can scale an app even if it has crashed. Its Machines are restarted with the new specification, however, if you redeploy the app, then any VM settings in `fly.toml` take precedence.
12 |
13 |
14 | ## Machine size configuration precedence
15 |
16 | 1. **The `[[vm]]` section in `fly.toml`**: The `fly deploy` and `fly scale count` commands respect the VM size configurations in your app's `fly.toml` file.
17 | 2. **Existing Machine sizes in the app:** If no VM size is set in `fly.toml`, then `fly deploy` won't change existing Machines, and `fly scale` will use existing Machines to infer new Machine sizes.
18 | 3. **Default Machine size of `shared-cpu-1x`:** If no VM size is set in `fly.toml`, and there are no existing Machines to infer size from, then the default Machine size is used.
19 |
20 | ## Check the VM resources on an app
21 |
22 | Here's a simple web app with three Machines running in different regions: two in Toronto and one in Tokyo. All the app's Machines belong to the default process group, `app`, since no other [processes](/docs/apps/processes/) exist.
23 |
24 | ```cmd
25 | fly status
26 | ```
27 | ```out
28 | App
29 | Name = testrun
30 | Owner = personal
31 | Hostname = testrun.fly.dev
32 | Image = testrun:deployment-01GWZY7ZVJ2HNED4B0KZBPS3AQ
33 |
34 | Machines
35 | PROCESS ID VERSION REGION STATE ROLE CHECKS LAST UPDATED
36 | app 17811943f031d8 3 yyz stopped 1 total, 1 passing 2024-02-07T15:34:57Z
37 | app 328749d3c53958 3 yyz stopped 1 total, 1 passing 2024-01-23T19:39:50Z
38 | app 908057ef21e487 3 nrt started 1 total, 1 passing 2024-01-23T19:39:51Z
39 | ```
40 |
41 | `fly scale show` shows the CPU and RAM settings for all the Machines deployed using `fly deploy` under this app.
42 |
43 | ```cmd
44 | fly scale show
45 | ```
46 | ```out
47 | VM Resources for app: testrun
48 |
49 | Groups
50 | NAME COUNT KIND CPUS MEMORY REGIONS
51 | app 3 shared 1 256 MB nrt,yyz(2)
52 | ```
53 |
54 | These Machines are running at the `shared-cpu-1x` preset scale, with a single shared vCPU and 256MB RAM.
55 |
56 | ## Add Machine size configuration to `fly.toml`
57 |
58 | With the `[[vm]]` section in `fly.toml`, you can set default Machine VM memory and CPU configurations, which [take precedence](#machine-size-configuration-precedence) when you run commands like `fly deploy` or `fly scale count`.
59 |
60 | This example shows a very simple config that specifies the `shared-cpu-2x` preset with 2GB of RAM:
61 |
62 | ```toml
63 | [[vm]]
64 | size = "shared-cpu-2x"
65 | memory = "2gb"
66 | ```
67 |
68 | If you don't include a process group in the `[[vm]]` section, then the settings apply to all process groups in your app. Add another `[[vm]]` section if you want different CPU or memory settings for specific process groups.
69 |
70 | For details and more settings, see [The `vm` section](/docs/reference/configuration/#the-vm-section) in the `fly.toml` reference.
71 |
72 | ## Scale VM memory and CPU with flyctl
73 |
74 | Use [`fly scale`](/docs/flyctl/scale) subcommands to apply VM memory and CPU settings to all Machines: `fly scale vm` applies a preset CPU/RAM combination; `fly scale memory` sets RAM separately, for cases when the preset's RAM is not enough.
75 |
76 |
77 | **Important:** If you make changes using `fly scale vm` or `fly scale memory`, the VM settings in `fly.toml` take precedence when you redeploy the app.
78 |
79 |
80 | ### Select a preset CPU/RAM combination
81 |
82 | There are a number of VM size presets available. See the list of valid named presets with `fly platform vm-sizes`.
83 |
84 | Scale to a different preset using `fly scale vm`. In general, you should choose a named VM "size" based on your desired CPU type and scale; RAM can be increased separately.
85 |
86 | ```cmd
87 | fly scale vm shared-cpu-2x
88 | ```
89 | ```out
90 | Updating machine 148ed599c14189
91 | Waiting for 148ed599c14189 to become healthy (started, 1/1)
92 | Machine 148ed599c14189 updated successfully!
93 | Updating machine 32874400f35285
94 | Waiting for 32874400f35285 to become healthy (started, 1/1)
95 | Machine 32874400f35285 updated successfully!
96 | Updating machine 9080e6e1f94987
97 | Waiting for 9080e6e1f94987 to become healthy (started, 1/1)
98 | Machine 9080e6e1f94987 updated successfully!
99 | Scaled VM Type to 'shared-cpu-2x'
100 | CPU Cores: 2
101 | Memory: 512 MB
102 | ```
103 |
104 | Check that the `app` process group has had this scale applied:
105 |
106 | ```cmd
107 | fly scale show
108 | ```
109 | ```out
110 | VM Resources for app: testrun
111 |
112 | Groups
113 | NAME COUNT KIND CPUS MEMORY REGIONS
114 | app 3 shared 2 512 MB nrt,yyz(2)
115 | ```
116 |
117 | You can also confirm that an individual Machine's config matches this, using `fly machine status
181 | **Note**: The `--process-group` option is aliased to `-g` for faster command entry.
182 |
183 |
184 | Here's an app with two process groups defined:
185 |
186 | ```cmd
187 | fly scale show
188 | ```
189 | ```out
190 | VM Resources for app: mr18-2
191 |
192 | Groups
193 | NAME COUNT KIND CPUS MEMORY REGIONS
194 | worker 2 shared 1 512 MB ams,yyz
195 | web 1 shared 1 512 MB yyz
196 | ```
197 |
198 | Say the workers are constantly crunching data and need to be bigger. You can scale a single process group using the `--process-group` option:
199 |
200 | ```cmd
201 | fly scale vm performance-2x --process-group worker
202 | ```
203 | ```out
204 | Updating machine 0e286561f35586
205 | No health checks found
206 | Machine 0e286561f35586 updated successfully!
207 | Updating machine 32873d9b012048
208 | No health checks found
209 | Machine 32873d9b012048 updated successfully!
210 | Scaled VM Type for 'worker' to 'performance-2x'
211 | CPU Cores: 2
212 | Memory: 4096 MB
213 | ```
214 |
215 | Check the result:
216 |
217 | ```cmd
218 | fly scale show
219 | ```
220 | ```out
221 | VM Resources for app: mr18-2
222 |
223 | Groups
224 | NAME COUNT KIND CPUS MEMORY REGIONS
225 | worker 2 performance 2 4096 MB ams,yyz
226 | web 1 shared 1 512 MB yyz
227 | ```
228 |
229 | ## Machines not belonging to Fly Launch
230 |
231 | If an app has Machines that don't belong to Fly Launch (in other words, if you created Machines using `fly machine run` or the Machines API), then `fly status` will warn you of their existence:
232 |
233 | ```text
234 | Found machines that aren't part of Fly Launch, run fly machines list to see them.
235 | ```
236 |
237 | The app-wide `fly scale` commands and any VM settings in `fly.toml` don't apply to these Machines, but you can scale any Machine individually with `fly machine update`:
238 |
239 | ```
240 | fly machine update --vm-size shared-cpu-2x 21781973f03e89
241 | fly machine update --vm-memory 1024 21781973f03e89
242 | fly machine update --vm-cpus 2 21781973f03e89
243 | ```
244 |
245 | If you try to set an incompatible CPU/RAM combination through `fly machine update --vm-memory` or `fly machine update --vm-cpus`, flyctl will let you know. Learn more about [individual Machine sizing with flyctl and the Machines API](/docs/machines/guides-examples/machine-sizing/).
246 |
--------------------------------------------------------------------------------
/launch/volume-storage.html.markerb:
--------------------------------------------------------------------------------
1 | ---
2 | title: Add volume storage to a Fly Launch app
3 | layout: docs
4 | nav: apps
5 | redirect_from: /docs/apps/volume-storage/
6 | ---
7 |
8 | Fly Volumes are local persistent storage for [Fly Machines](/docs/machines/).
9 |
10 | Learn more:
11 | - [How Fly Volumes work](/docs/volumes/overview/)
12 | - [How to manage volumes with flyctl commands](/docs/volumes/volume-manage/)
13 | - [How to manage volume snapshots (backups)](/docs/volumes/snapshots)
14 |
15 | ## Launch a new app with a Fly Volume
16 |
17 | 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.
18 |
19 | 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`.
20 |
21 | ```cmd
22 | fly launch --no-deploy
23 | ```
24 | `fly launch` creates a `fly.toml` app configuration file in your project source directory.
25 |
26 | 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:
27 |
28 | ```toml
29 | [mounts]
30 | source = "myapp_data"
31 | destination = "/data"
32 | ```
33 |
34 |
35 | Note: You can't mount a volume with `destination="/"` since `/` is used for the root file system.
36 |
37 |
38 | 1. Deploy the app:
39 |
40 | ```cmd
41 | fly deploy
42 | ```
43 |
44 | 1. [Confirm that the volume is attached to a Machine](#confirm-the-volume-is-attached-to-a-machine).
45 |
46 | 1. (Recommended only if your app handles replication) Clone the first Machine to scale out to two Machines with volumes:
47 |
48 | ```cmd
49 | fly machine clone
66 | Warning: `fly machine clone` doesn't write data into the new volume.
67 |
68 |
69 | ## Add volumes to an existing app
70 |
71 | Add a volume to an app created with [Fly Launch](/docs/launch/).
72 |
73 | 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:
74 |
75 | ```toml
76 | [mounts]
77 | source = "myapp_data"
78 | destination = "/data"
79 | ```
80 |
81 | 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:
82 |
83 | ```cmd
84 | fly volumes create
90 | **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.
91 |
92 |
93 | 4. Deploy the app:
94 |
95 | ```cmd
96 | fly deploy
97 | ```
98 |
99 | 5. [Confirm that the volume is attached to a Machine](#confirm-the-volume-is-attached-to-a-machine).
100 |
101 | ## Confirm the volume is attached to a Machine
102 |
103 | Use flyctl to check the status of volumes and Machines.
104 |
105 | ### List the Machines
106 |
107 | List Machines to check attached volumes:
108 |
109 | ```cmd
110 | fly machine list
111 | ```
112 |
113 | Example output:
114 |
115 | ```out
116 | 1 machines have been retrieved from app my-app-name.
117 | View them in the UI here
118 |
119 | my-app-name
120 | ID NAME STATE REGION IMAGE IP ADDRESS VOLUME CREATED LAST UPDATED APP PLATFORM PROCESS GROUP SIZE
121 | 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
122 | ```
123 |
124 | ### List the volumes
125 |
126 | List volumes to check attached Machines:
127 |
128 | ```cmd
129 | fly volumes list
130 | ```
131 |
132 | Example output:
133 |
134 | ```out
135 | ID STATE NAME SIZE REGION ZONE ENCRYPTED ATTACHED VM CREATED AT
136 | vol_zmjnv8m81p5rywgx created data 1GB lhr b6a7 true 5683606c41098e 3 minutes ago
137 | ```
138 |
139 | ### SSH into the Machine
140 |
141 | View the volume in the Machine file system:
142 |
143 | ```cmd
144 | fly ssh console -s -C df
145 | ```
146 |
147 | Example output showing a 1GB volume mounted at `/data`:
148 |
149 | ```out
150 | ? Select VM: lhr: 5683606c41098e fdaa:0:3b99:a7b:7e:3155:9844:2 nameless-feather-6339
151 | Connecting to fdaa:0:3b99:a7b:7e:3155:9844:2... complete
152 | Filesystem 1K-blocks Used Available Use% Mounted on
153 | devtmpfs 103068 0 103068 0% /dev
154 | /dev/vda 8191416 172748 7582856 3% /
155 | shm 113224 0 113224 0% /dev/shm
156 | tmpfs 113224 0 113224 0% /sys/fs/cgroup
157 | /dev/vdb 1011672 2564 940500 1% /data
158 | ```
159 |
160 | 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.
161 |
162 | ## Access a volume
163 |
164 | <%= partial "/docs/partials/docs/volumes_access" %>
165 |
166 | ## Related topics
167 |
168 | - [Fly Volumes overview](/docs/volumes/overview/)
169 | - [`mounts` section](/docs/reference/configuration/#the-mounts-section) in the `fly.toml` app configuration file
170 | - [Create and manage volumes](/docs/volumes/volume-manage/)
171 | - [Manage volume snapshots](/docs/volumes/snapshots/)
172 | - [Scale an app with volumes](/docs/apps/scale-count/#scale-an-app-with-volumes)
173 |
--------------------------------------------------------------------------------