앱 배포하기 (Deploy an app)

원문 보기 위키 갱신 2026.10.08

fly deploy 명령으로 앱을 빌드하고 하나 이상의 Fly Machine에서 실행하는 방법을 알려드려요. Fly Launch의 기능인 fly deploy는 로컬 fly.toml 파일에 지정된 구성을 적용해 앱을 새 릴리스로 배포해요.

출처: 문서

본문

Fly Launch의 기능인 fly deploy flyctl 명령은 앱을 빌드하고 하나 이상의 Fly Machine에서 띄우며, 로컬 fly.toml 파일에 지정된 구성을 적용해요.

fly launch를 --no-deploy 옵션으로 실행했든, 배포된 앱의 소스나 구성을 변경하고 싶든, 프로젝트의 소스 디렉토리(앱 소스 코드, 프로젝트 구성, fly.toml, Dockerfile이 있는 곳)에서 다음을 실행해 새 릴리스를 만들 수 있어요:

fly deploy

앱을 이전에 배포한 적이 없다면, fly deploy는 앱의 fly.toml 파일에 정의된 각 프로세스 그룹에 대해 서비스와 볼륨이 구성되어 있는지에 따라 Machine을 하나 또는 둘 생성해요. 프로세스 그룹을 명시적으로 정의하지 않았다면, 첫 배포는 이중화를 위해 Machine 두 대를 제공해요. Fly Launch가 언제 Machine 하나를 만들고 언제 두 개를 만드는지에 대한 자세한 내용은 첫 배포 시 기본 이중화를 참고하세요.

이후 배포는 앱의 소스와 구성에 대한 최신 로컬 변경사항으로 앱의 Machine을 그룹으로 업데이트해요. Fly App에는 fly deploy로 관리되지 않는 독립 Machine이 있을 수도 있어요.

구성 (Configuration)

flyctl은 fly.toml 파일에서 운영할 앱 이름과 배포 중 적용할 앱 구성을 찾아요. fly deploy -a <app-name>을 사용하면 fly.toml에 주어진 앱 이름을 무시하고 현재 작업 디렉토리의 프로젝트를 다른 기존 Fly App에 배포할 수 있어요.

fly deploy 명령과 함께 쓸 수 있는 다른 옵션들이 여러 가지 있어요.

빌드 (The build)

fly deploy는 앱의 Docker 이미지를 빌드하거나 가져와서 최신 변경사항으로 Machines를 갱신해요.

fly deploy가 앱의 Docker 이미지를 얻는 방법을 결정하는 방식은 이래요:

이미지가 지정된 경우 — --image 옵션 또는 fly.toml의 [build] 섹션으로 — 작업 디렉토리에 Dockerfile이 있든 --dockerfile 옵션을 쓰든 상관없이 그 이미지를 사용해요.
그렇지 않으면 fly.toml의 [build] 섹션을 확인하고 거기에 지정된 방법(Dockerfile 또는 buildpack)을 사용해요. (하지만 꼭 필요하지 않으면 buildpack은 쓰지 마세요. 깨지기 쉽고, 비대하고, 변경이 잦아요.)
그렇지 않으면, --dockerfile 플래그가 Dockerfile 경로를 제공하면 그 Dockerfile로 이미지를 빌드해요. 제대로 읽으셨어요. --dockerfile 플래그는 구성 파일의 [build] 섹션 이후에 확인돼요.
그렇지 않으면, 로컬 작업 디렉토리에 Dockerfile(정확히 Dockerfile 또는 dockerfile이라는 이름)이 있으면 그 Dockerfile로 빌드해요.

IP 주소 (IP addresses)

배포할 앱이 적격한 HTTP [[services]] 섹션으로 구성되어 있고 아직 공용 IP 주소가 없다면, fly deploy가 공용 IPv6와 공유 공용 IPv4 Anycast 주소를 프로비저닝해요.

Fly Launch가 관리하지 않는 Machines

fly deploy로 만들어진(또는 fly launch 중 배포의 일부로 만들어진) Machines, 또는 그런 Machine을 fly clone하여 만들어진 Machines에는 Fly Launch에 속한다는 메타데이터("fly_platform_version": "v2")가 담겨 있어요. 이 Machines는 이후 모든 fly deploy 명령에서 그룹으로 업데이트돼요.

fly machine run으로 만든 새 Machines(비관리 Machines라고도 함)은 fly_platform_version 메타데이터가 없어서 Fly Launch가 자동으로 관리하지 않아요. 이 비관리 Machines는 앱과 다른 자체 구성을 가질 수 있고, 다른 Docker 이미지를 기반으로 할 수도 있어요.

볼륨 마운트와 `fly deploy`

Machine에 볼륨이 마운트되어 있다면, fly deploy로 다른 볼륨을 마운트할 수는 없어요. 다만 볼륨 데이터가 Machine의 파일 시스템에서 사용 가능해지는 마운트 지점은 변경할 수 있어요. 이는 fly.toml의 [mounts] 섹션에서 구성해요.

Fly Volumes 사용에 대해 더 알아보세요.

`fly.toml`의 `fly deploy` 구성

다음 배포 동작을 fly.toml의 [deploy] 섹션에서 구성해요.

릴리스 명령 (Release commands)

해당 릴리스가 배포되기 전에, 성공적으로 빌드된 릴리스를 사용해 임시 VM에서 일회성 릴리스 명령을 실행할 수 있어요. 데이터베이스 마이그레이션 실행 같은 곳에 유용해요. 이 임시 VM은 앱에 마운트했을 수 있는 어떤 볼륨에도 접근할 수 없다는 점을 명심하세요.

배포 전략 (Deployment strategy)

다음 배포 전략 중 하나를 지정할 수 있어요:

rolling (기본값): 각 Machine이 성공적으로 배포될 때까지 기다렸다가 다음 Machine의 업데이트를 시작해요
immediate: 모든 Machine을 한 번에 내려서 업데이트해요
canary: 새 Machine 하나를 부팅하고, 건강 상태를 확인한 다음, 롤링 재시작 전략으로 진행해요
bluegreen: 같은 리전에 실행 중인 각 Machine 옆에 새 Machine을 부팅하고, 모든 새 Machine이 건강 검사를 통과한 후에만 새 Machines로 트래픽을 이동해요

배포 전략 설정에 대해 더 알아보세요.

```bash cmd fly deploy --strategy canary ```

...
==> Building image
Searching for image 'flyio/hellofly:latest' remotely...
image found: img_z1nr0lpjz9v5q98w

Watch your app at https://fly.io/apps/aged-water-8803/monitoring

Creating canary machine for group app
  Machine 328745da023e85 [app] update finished: success
Canary machines successfully created and healthy, destroying before continuing
machine 328745da023e85 was found and is currently in created state, attempting to destroy...
Updating existing machines in 'example-app-8803' with canary strategy
  [1/2] Machine 3287457df77785 [app] update finished: success
  [2/2] Machine 91857266c41638 [app] update finished: success
  Finished deploying
...

모든 변경사항이 새 App 릴리스를 요구하는 건 아니에요

예를 들어 재배포 없이 앱에 IP 주소를 추가할 수 있어요.

앱에 시크릿을 추가하는 것은 재시작이 필요하므로, fly secrets set는 새 배포를 트리거해요.

스모크 체크 (Smoke checks)

스모크 체크는 배포 중 Machine이 started 상태에 들어간 후 약 10초 동안 Machines를 모니터링해 Machine이 계속 실행되는지 확인해요. 이 기간 동안 Machine이 0이 아닌 종료 코드로 계속 재시작된다면 스모크 체크가 실패하고 배포가 중지돼요. 가능하면 스모크 체크 실패 출력에는 앱 문제를 진단하는 데 도움이 되는 로그 발췌가 포함돼요.