호소세의 개발 블로그

AWS - Terraform - 코드형 인프라(IaC) : 테라폼 프로젝트 기본 구성 및 초기화(init) 가이드

호소세 — Mon, 24 Aug 2026 18:29:24 +0900

이전 시간 내용 참고 후 진행하면 더 좋습니다. aws 계정 등록해야합니다!

https://pabeba.tistory.com/296

1. 개요: 테라폼 프로젝트를 구성하는 핵심 파일들

테라폼은 특정 디렉토리에 있는 .tf 확장자를 가진 파일들을 읽어 들여 인프라를 구성합니다.

비록 하나의 파일에 모든 코드를 담을 수도 있지만, 실무에서는 관리의 용이성, 재사용성, 가독성을 위해 목적에 따라 파일을 분리하여 구성하는 것이 표준 관례(Best Practice)입니다.

이번 실습에서 생성하고 작성할 핵심 파일들의 역할은 다음과 같습니다.

테라폼 기본 구성 파일 설명

파일명의미 및 역할 (Description)

provider.tf	'누구에게' 명령을 내릴지 정의하는 파일입니다. AWS, Azure, GCP 등 인프라를 제공하는 공급자(Provider) 설정과 사용할 버전을 명시합니다.
main.tf	'무엇을' 만들지 정의하는 메인 파일입니다. 실제 리소스(EC2, VPC 등)를 생성하는 핵심 코드가 주로 이곳에 작성됩니다. 프로젝트 규모가 커지면 다른 이름의 .tf 파일로 분리하기도 합니다.
variables.tf	코드 내에서 사용할 변수(Variable)들의 '입력 타입'을 정의하는 파일입니다. 코드의 재사용성을 높이기 위해 하드코딩 대신 변수를 선언합니다.
terraform.tfvars	variables.tf에서 정의한 변수에 실제 '값'을 할당하는 파일입니다. 민감한 정보(비밀번호, 키 등)가 포함될 수 있어 주의가 필요합니다.
outputs.tf	인프라 생성 후 인프라의 '결과 값'을 출력하는 파일입니다. 생성된 EC2의 퍼블릭 IP나 S3 버킷의 URL 등, 다른 프로젝트나 사용자가 확인해야 할 정보를 정의합니다.
.gitignore	Git 버전 관리에서 제외할 파일 목록을 지정합니다. 테라폼 초기화 시 생성되는 임시 폴더나 민감한 정보가 담긴 .tfvars 파일 등을 Git에 업로드하지 않도록 방지합니다.

2. 실습 1단계: 테라폼 프로젝트 기본 파일 구성

가장 먼저 실습 공간을 만들고, 위에서 설명한 기본 파일들을 생성해 보겠습니다.

PowerShell을 열고 아래 명령어를 한 줄씩 실행하거나 전체 복사하여 실행합니다.

디렉토리는 다들 자신의 디렉토리로 변경하셔야 합니다.

# 1. 실습 디렉토리 생성 및 이동 (경로는 본인 환경에 맞게 수정 가능)
$path = "C:\Users\NT551_11TH\OneDrive\Desktop\workspace\tf_project\basic"
New-Item -ItemType Directory -Path $path -Force
cd $path

# 2. 테라폼 핵심 구성 파일(공파일) 한 번에 생성하기
'provider.tf', 'main.tf', 'variables.tf', 'outputs.tf', 'terraform.tfvars', '.gitignore' | ForEach-Object { New-Item -ItemType File -Path $_ -Force }

명령어 실행이 완료되면 해당 폴더에 6개의 공파일이 생성된 것을 확인할 수 있습니다.

3. 실습 2단계: Provider 설정 (provider.tf 작성)

이제 테라폼에게 우리는 AWS 클라우드의 서울 리전(ap-northeast-2)에 인프라를 구축할 것이라고 알려주는 설정을 provider.tf 파일에 작성합니다.

# provider.tf 파일 내용

terraform {
  # 테라폼 자체 설정 (필요한 프로바이더 버전 명시)
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0" # 5.0 버전 이상을 사용하되 최신 마이너 버전 허용
    }
  }
}

# AWS 프로바이더 설정
provider "aws" {
  region = "ap-northeast-2" # 서울 리전
}

4. 실습 3단계: 테라폼 파이프라인 가동 (init & validate)

파일 작성이 완료되었다고 바로 인프라를 생성할 수 없습니다. 테라폼이 구동하기 위한 준비 과정이 필요합니다.

터미널에서 아래 명령어를 차례로 실행해 보세요.

Step 1: 테라폼 초기화 (terraform init)

init 명령은 테라폼 프로젝트가 위치한 디렉토리에서 가장 먼저, 그리고 딱 한 번 실행해야 하는 명령어입니다.

provider.tf를 읽고 필요한 AWS 플러그인(Provider 바이너리)을 다운로드하는 등의 준비 작업을 수행합니다.

terraform init

초기화 성공 후 생성되는 결과물 분석

초기화에 성공하면 폴더 내에 새로운 임시 폴더와 파일이 숨겨진 상태로 생성됩니다. 이들의 역할은 다음과 같습니다.

.terraform/ (폴더):
- 의미: 테라폼이 인프라 공급자(AWS 등)와 통신하기 위해 다운로드한 프로바이더 플러그인 바이너리 파일들이 저장되는 로컬 임시 저장소입니다.
- 주의: 이 폴더는 용량이 크고 환경마다 다르므로 .gitignore에 등록하여 Git에 절대 올리지 않습니다.
.terraform.lock.hcl (파일):
- 의미: 프로젝트가 사용하는 프로바이더의 모듈명, 정확한 버전, 그리고 해시값(Checksum)을 기록하여 잠그는(Lock) 파일입니다.
- 역할: 나중에 다른 팀원이나 서버에서 이 프로젝트를 구동할 때, 항상 동일한 버전의 프로바이더가 사용되도록 보장하여 예기치 않은 버전 업데이트로 인한 인프라 장애를 방지합니다. 이 파일은 Git에 올려 함께 관리하는 것이 권장됩니다.

Step 2: 코드 문법 검사 (terraform validate)

이제 작성한 HCL 코드가 테라폼 문법에 맞게 올바르게 작성되었는지 검증할 차례입니다.

init 과정이 선행되어야 프로바이더별 고유한 속성 문법도 검증할 수 있습니다.

terraform validate

[실행 결과 확인]

Success! The configuration is valid.

위와 같이 Success! 메시지가 나타난다면, 작성한 provider.tf 코드의 문법에는 이상이 없다는 뜻입니다.

️ 마치며

오늘은 코드형 인프라(IaC)의 핵심 도구인 테라폼을 사용하기 위한 가장 기초적인 단계인 프로젝트 파일 구성과, 공급자(Provider) 설정 후 초기화(init) 및 검증(validate) 과정을 알아보았습니다.

이제 로컬 PC의 테라폼 엔진이 AWS 서버와 통신할 준비가 모두 완료되었습니다. 다음 포스팅에서는 실제로 main.tf를 작성하여 AWS EC2 인스턴스를 코드 한 줄로 생성하고 삭제해 보겠습니다.

[IaC] 코드형 인프라(Infrastructure as Code) 개요 및 테라폼(Terraform) 개발 환경 구축 가이드

호소세 — Fri, 21 Aug 2026 18:54:48 +0900

오늘은 클라우드 및 인프라 엔지니어링 생태계에서 가장 중요한 패러다임 중 하나인

코드형 인프라(Infrastructure as Code, IaC)의 핵심 개념과,

대표적인 IaC 도구인 테라폼(Terraform)을 사용하기 위한 로컬 개발 환경 구축 방법을 한눈에 알기 쉽게 정리해 보겠습니다.

1. IaC(Infrastructure as Code) 개요

IaC란 무엇인가요?

IaC(Infrastructure as Code)는 사람이 AWS 콘솔이나 GCP 웹 화면에 접속하여 마우스 클릭으로 서버, 네트워크, 데이터베이스 등을 일일이 설정하는 대신, 명확하게 정의된 코드(텍스트 파일)를 통해 IT 인프라를 자동으로 생성, 수정, 삭제하는 기술입니다.

주요 특징

인프라의 코드화(Text-based Definition)
- 서버(EC2), 저장소(S3), 네트워크(VPC) 등의 인프라 구성 요소를 선언적 언어나 프로그래밍 언어 형태의 코드로 작성합니다.
동일성 및 멱등성(Idempotency) 보장
- 코드를 실행할 때마다 환경의 치우침 없이 언제나 동일한 구성 결과를 보장받을 수 있습니다.
버전 관리(Version Control) 용이
- 인프라 설정 파일도 일반 소스 코드처럼 Git을 이용해 커밋, 브랜칭, 이력 추적 및 롤백(Rollback) 관리를 수행할 수 있습니다.

IaC 도입 시 주요 장점

휴먼 에러(Human Error) 방지: 웹 콘솔 클릭 실수로 인한 잘못된 설정이나 세팅 누락을 근본적으로 예방할 수 있습니다.
압도적으로 빠른 배포 속도: 수동 작업으로 수시간~수일이 걸리던 인프라 구축을 수초~수분 내에 마칠 수 있습니다.
팀 내 협업 및 리뷰 용이: 코드 리뷰(Pull Request) 절차를 통해 인프라 변경 사항을 팀원들과 검증하고 간편하게 공유할 수 있습니다.

2. 주요 IaC 제품군 비교

IaC 도구는 특정 클라우드 벤더 전용 도구와, 여러 클라우드를 아우르는 멀티 클라우드 도구로 구분됩니다.

1) AWS 전용 도구

AWS CloudFormation: YAML 또는 JSON 형태의 선언적(Declarative) 템플릿 파일로 인프라를 정의하는 AWS의 기본 서비스입니다.
AWS CDK (Cloud Development Kit): Python, TypeScript, Java, Go 등 익숙한 프로그래밍 언어를 그대로 사용하여 AWS 인프라를 생성할 수 있는 개발자 친화적 도구입니다.

2) 멀티 클라우드 도구

Terraform (테라폼)
- 사실상 글로벌 표준(De-facto Standard)으로 여겨지는 오픈소스/써드파티 프로비저닝 도구입니다.
- HashiCorp가 개발한 HCL(HashiCorp Configuration Language)이라는 직관적인 독자 언어를 사용합니다.
- AWS, GCP, Azure, 네이버클라우드 등 대부분의 클라우드 인프라를 하나의 도구로 통합 관리할 수 있습니다.
Ansible (앤서블)
- 테라폼이 *'인프라 뼈대(프로비저닝)'*를 생성하는 데 집중한다면, 앤서블은 생성된 인프라 내부의 소프트웨어 설치나 설정 관리(구성 관리, Configuration Management)에 특화된 도구입니다.

3. 테라폼 & AWS CLI 개발 환경 구축

이제 테라폼 코드를 작성하고 AWS 클라우드에 실제 인프라 명령을 전달할 수 있도록 로컬 PC 세팅을 진행해 보겠습니다.

Step 1. AWS CLI 설치 및 설정

AWS CLI(Command Line Interface)는 터미널 쉘에서 AWS 서비스를 명령어로 관리할 수 있게 돕는 통합 오픈소스 도구입니다.

다운로드 패키지 설치
- Windows: AWS CLI V2 MSI 다운로드
- Mac: AWS CLI V2 PKG 다운로드

설치 상태 확인 (터미널 새로 오픈 후 실행)

aws --version

# 출력 예시
aws-cli/2.35.6 Python/3.14.5 Windows/11 exe/AMD64

IAM 액세스키(Access Key) 설정 터미널에서 아래 명령어를 실행하고, 발급받은 IAM 액세스 키 정보를 입력합니다.

Step 2. AWS IAM 인증 액세스키(Access Key) 발급 절차 및 주의사항

테라폼이나 AWS CLI가 외부 로컬 PC에서 AWS 리소스에 접근하려면 인증 자격 증명이 필요합니다.

액세스 키 발급 과정
- AWS Console ➔ IAM 서비스 진입 ➔ 본인 계정/사용자 선택 ➔ 보안 자격 증명(Security credentials) 탭 선택
- [액세스 키] 항목에서 [액세스 키 만들기] 클릭
- 사용 사례 선택 시 Command Line Interface(CLI) 선택 후 안내 모범 사례 확인 체크 ➔ [다음] ➔ [액세스 키 만들기] 클릭
- CSV 파일 다운로드를 클릭하여 발급받은 Access Key ID와 Secret Access Key를 저장합니다.
액세스 키 관리 및 삭제 방법
- 필요가 없어진 키는 보안을 위해 IAM 콘솔에서 비활성화 처리 후 삭제하는 것이 모범 사례입니다.

⚠️ 보안 주의사항 (중요!) 발급된 Secret Access Key는 절대 외부로 유출되거나 GitHub 공개 저장소에 올려서는 안 됩니다. 해커들이 매크로 스크립트로 깃허브를 상시 모니터링하고 있으며, 유출 시 고성능 가상화 머신(채굴 등)이 무단 생성되어 방대한 비용 폭탄을 맞을 수 있습니다.

잘 숨긴 후 아래 명령어 cmd나 powershell에서 작성합니다.

그럼 id, access key, region name, output format을 작성하라고 나오는데

위의 두 개는 iam 액세스 키 치시면 되고 지역은 자신이 쓰고있는 지역 작성 output format은 json으로 해주세요.

aws configure

AWS Access Key ID [None]: AKIA4BQ3...
AWS Secret Access Key [None]: NZkQwWX...
Default region name [ap-northeast-2]: ap-northeast-2
Default output format [json]: json

Step 3. Terraform 설치 및 시스템 경로(PATH) 등록

다운로드
- Windows (AMD64): HashiCorp Terraform Windows 다운로드
- Mac: HashiCorp Terraform Mac 다운로드
설치 및 환경변수 지정
1. 압축 파일 내부의 terraform.exe 파일을 C:\terraform 경로에 저장합니다.
2. Windows [시스템 속성] ➔ [환경 변수] ➔ Path 항목 편집에 C:\terraform 경로를 추가합니다.

버전 확인

terraform --version

# 출력 예시
Terraform v1.15.6 on windows_amd64

Step 4. VS Code 확장 프로그램 설치

VS Code 실행 ➔ Extensions(Ctrl + Shift + X) ➔ HashiCorp Terraform 검색 후 [Install] 버튼 클릭
설치 효과: HCL 코드 구문 강조(Syntax Highlighting), 자동 완성을 지원받아 개발 생산성이 크게 향상됩니다.

4. 테라폼 동작 매커니즘 한눈에 이해하기

테라폼으로 인프라가 구성되는 내부 흐름은 다음과 같은 단계로 연동되어 수행됩니다.

[VS Code]에서 테라폼 코드(*.tf) 작성 및 적용 명령 실행
      ↓
[Terraform Engine]에서 HCL 언어 해석 및 생성할 인프라 계획 수립
      ↓
[AWS CLI / Provider]를 통해 AWS API 호출 명령어 집합 변환
      ↓
[IAM Access Key] 자격 증명을 거쳐 AWS 클라우드로 전송
      ↓
[AWS Cloud] 실제 EC2, VPC, S3 등 인프라 자동 생성/구성

이와 같은 흐름을 이해하고 계시면 추후 테라폼 코드를 작성하고 트러블슈팅할 때 커뮤니케이션과 문제 원인 파악이 한층 수월해집니다.

마치며

지금까지 코드형 인프라(IaC)의 도입 배경부터 테라폼 및 AWS CLI 환경 설정 방법까지 살펴보았습니다. 이제 로컬 환경 구축이 완료되었으니 다음 글에서는 실제 .tf 파일 작성법과 terraform init, plan, apply 명령어의 사용법을 자세히 알아보겠습니다.

오늘의 한 마디

최근에 무기력에 대한 영상을 봤는데 거기서 현대인들이 무기력증이 엄청나게 많다고 한다. 그래서 그 무기력증을 해결할 수 있는 방법을 취미라고 했다. 무조건 가만히 쉬는 것을 좋아하는 사람도 있지만 그것이 아니라면 취미를 가지라고 하고 취미에서도 흥미를 느끼지 못한다면 통제 가능한 취미를 가지라고 했다.

통제 가능한 취미라는 것이 아래 그림과 같이 밑그림이 그려진 그림에 색칠해서 성공의 기쁨? 완성의 기쁨을 누릴 수 있는 것들을 하라고 했다. 그래서 수학 문제 풀기 이런것도 도움이 되지 않을까 생각했다.

아무튼 요즘 세상이 너무 팍팍해서 다들 힘을 못내고 있는 것 같다. 회복 탄력성을 길러 다시 몇 번이고 일어나야 한다. 그래야 생존할 수 있다. 모두 조금 힘들지만 파이팅입니다 ㅎㅎ

AWS EC2 에 GitHub Action으로 CI/CD 해보기

호소세 — Thu, 20 Aug 2026 18:40:40 +0900

https://pabeba.tistory.com/294

이전 시간에 AWS EC2를 구성하고 파일 업로드와 설정을 손수 진행해보았는데요.

이번 시간에는 GitHub Action으로 딸깍 push만 해서 AWS EC2 인스턴스에 파일을 올리고 재시작 하는 것을 해볼겁니다.

이전전 시간에 deploy.yml 파일에서 업그레이드하고 Github 프로젝트에 설정 조금하면 금방 CI/CD 가능합니다!

1. CI/CD와 GitHub Actions 개요

본격적인 코드 설명에 앞서 간단한 개념을 잡고 가겠습니다.

CI (Continuous Integration - 지속적 통합): 개발자들이 작성한 코드를 주기적으로 중앙 저장소에 통합하고, 자동화된 빌드 및 테스트를 통해 코드의 품질을 검증하는 과정입니다.
CD (Continuous Deployment - 지속적 배포): CI 과정을 통과한 코드를 실제 운영 환경(Production)에 자동으로 배포하는 과정입니다.
GitHub Actions: GitHub에서 제공하는 강력한 CI/CD 도구입니다. GitHub 저장소 내에서 발생하는 이벤트(Push, Pull Request 등)를 트리거(Trigger)로 삼아 사용자가 정의한 작업(Workflow)을 실행할 수 있습니다.

지식 더하기: 왜 CI/CD를 사용할까요? CI/CD를 구축하면 개발자는 코드 작성에만 집중할 수 있고, 반복적인 빌드, 테스트, 배포 작업을 자동화하여 휴먼 에러를 방지하고 배포 속도를 획기적으로 향상시킬 수 있습니다. 또한, 언제든 안정적으로 배포 가능한 상태를 유지할 수 있다는 큰 장점이 있습니다.

2. GitHub Actions 워크플로(Workflow) 분석

이제 실제 배포에 사용되는 .github/workflows/deploy.yml (파일명은 자유) 파일을 한 부분씩 살펴보며 기능을 설명해 드리겠습니다.

전체 소스는 여기 있어요.

https://github.com/hosose/my_project/blob/main/.github/workflows/deploy.yml

my_project/.github/workflows/deploy.yml at main · hosose/my_project

git 사용 연습. Contribute to hosose/my_project development by creating an account on GitHub.

github.com

name: Push 기반 CI/CD 테스트

# [트리거 지정] CI/CD가 작동하게 되는 원인, 이벤트를 정의합니다.
# main 브랜치에서 push 이벤트가 발생(Listen -> on)하면 아래 설정한 내용이 작동합니다.
on:
  push:
    branches:
      - main

name: 워크플로의 이름을 지정합니다. GitHub Actions 탭에서 이 이름으로 표시됩니다.
on.push.branches: 파이프라인을 실행할 트리거를 정의합니다. 여기서는 main 브랜치에 코드가 push될 때만 이 워크플로가 실행되도록 설정했습니다. 실무에서는 보통 main(운영) 또는 develop(개발) 브랜치를 지정합니다.

# 개별 작업(jobs)을 순서대로 나열합니다 (파이프라인).
jobs:
  # 'ci'라는 이름의 job을 하나 설정합니다.
  ci:
    # 어떤 OS에서 job을 진행할 것인가? -> GitHub에서 클라우드 방식으로 제공합니다 (Runner).
    runs-on: ubuntu-latest

jobs: 워크플로에서 실행될 실제 작업들을 정의합니다. 여러 작업을 병렬로 실행할 수도 있지만, 여기서는 ci라는 하나의 작업을 정의했습니다.
runs-on: 작업이 실행될 가상 환경(Runner)의 OS를 지정합니다. ubuntu-latest는 가장 최신의 우분투 환경을 사용하겠다는 의미이며, GitHub에서 제공하는 클라우드 리소스를 사용하게 됩니다.

    # 작업 단계(steps)를 지정합니다.
    steps:
      # 1. GitHub에 저장되어 있는 최신 내용을 체크아웃합니다 (소스를 모두 내려받음).
      - name: 코드 checkout
        uses: actions/checkout@v4

steps: 하나의 job 내에서 실행될 일련의 단계들을 순서대로 정의합니다.
actions/checkout@v4: GitHub에서 공식적으로 제공하는 액션(Action)입니다. 현재 구동 중인 Runner OS 환경으로 GitHub 저장소의 소스 코드를 복사(Checkout)해옵니다. 이 단계가 있어야 이후 단계에서 소스 파일을 기반으로 작업을 진행할 수 있습니다.

      # 확인 or 단위테스트 (편의상 생략하고 환경 확인만 진행)
      - name: 확인 검증
        # 여러 개의 명령어를 작동시킬 때는 '|' 기호를 통해 배치로 작성합니다.
        run: |
          pwd
          ls -al
          cat main.py
        shell: bash

run: Runner의 터미널에서 실행할 명령어를 기술합니다. 여기서는 소스 코드가 정상적으로 체크아웃되었는지 확인하기 위해 현재 경로(pwd), 파일 목록(ls -al), 그리고 메인 파일 내용(cat main.py)을 출력해봅니다.
실무에서는 이 단계에서 파이썬 패키지 설치(pip install) 및 단위 테스트(pytest 등)를 실행하여 코드의 이상 유무를 검증하는 CI 과정을 수행합니다.

여기서부터는 CD (Continuous Deployment) 작업입니다.

이제 검증된 소스 코드를 실제 운영 중인 AWS EC2 서버로 복사하고 서비스를 재시작하는 배포 과정을 진행합니다.

      # [CD 작업 1: 파일 복사]
      # CI 쪽 서버(Runner)에서 EC2 서버(배포용 서버)로 배포 진행 -> SSH 활용
      - name: source code copy to EC2
        uses: appleboy/scp-action@master
        with:
          host: ${{ secrets.HOST }}
          username: ${{ secrets.USERNAME }}
          key: ${{ secrets.EC2_KEY }}
          port: 22
          # 복사할 대상 (편의상 . (현재 디렉토리 전체))
          source: .
          # 우분투 OS가 세팅된 EC2 서버의 대상 경로로 복사
          target: "/home/ubuntu/projects"

appleboy/scp-action: SCP(Secure Copy) 프로토콜을 이용해 Runner에서 원격 서버로 파일을 복사해주는 서드파이 액션입니다.
with (중요 - 보안): 접속 정보를 입력합니다. 이때 IP 주소(HOST), 사용자명(USERNAME), SSH 키(.pem 파일 내용 - EC2_KEY)와 같은 민감한 정보는 소스 코드에 직접 노출하지 않고, GitHub 저장소의 Settings -> Secrets and variables -> Actions에 저장된 Secrets 변수를 활용해 보안을 유지합니다. 도커 등에서 사용하는 환경변수(.env) 파일 내용도 시크릿 변수에 담아 배포 시 동적으로 생성할 수 있습니다.
보안 이슈: EC2 서버의 SSH 포트(22번)는 GitHub Action Runner가 접속할 수 있도록 보안 그룹(Security Group)에서 접근 허용이 되어 있어야 합니다. 편의상 0.0.0.0/0 (모든 IP 허용)으로 설정하기도 하지만, 보안 강화를 위해 GitHub의 서브넷 IP만 허용하는 방식이 더 권장됩니다.

      # [CD 작업 2: 서비스 재가동]
      # 파일 복사 후 서버에서 실제 서비스를 갱신하고 재시작하는 명령을 전달합니다.
      - name: Run Script And Service Restart
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.HOST }}
          username: ${{ secrets.USERNAME }}
          key: ${{ secrets.EC2_KEY }}
          port: 22
          script: |
            # 1. 프로젝트 폴더 위치로 이동합니다.
            #cd /home/ubuntu/projects
            
            # 2. 가상환경에 추가된 패키지가 있다면 설치를 진행합니다.
            #./web/bin/pip install -r requirements.txt
            
            # 3. systemd로 관리 중인 애플리케이션 서비스를 재시작합니다.
            sudo systemctl restart hello.service

appleboy/ssh-action: SSH를 통해 원격 서버에 접속하여 명령어를 실행해주는 액션입니다.
script: EC2 서버에 접속해서 실행할 쉘 명령어를 기술합니다.
1. 배포된 폴더로 이동합니다.
2. 새로 추가된 파이썬 패키지가 있다면 가상환경의 pip를 이용해 설치합니다.
3. 리눅스 시스템 데몬(systemd)으로 관리 중인 웹 애플리케이션 서비스(hello.service)를 재시작하여 변경된 코드가 반영되도록 합니다.

지식 더하기: 보안 이슈에 대한 첨언 원문의 주석에 "EC2 -> GitHub로 다시 요청 보내서 명령 실행(이 부분은 보안 이슈로 하지 않고 터미널에서 수동으로 함)"이라는 내용이 있는데, 이는 GitHub Actions의 동작 방식과 다소 차이가 있습니다. GitHub Actions는 **GitHub 측(Runner)에서 EC2로 접속하는 형태(Outbound)**이지, EC2가 GitHub에 요청을 보내는 구조가 아닙니다. 위 워크플로처럼 SSH 액션을 사용하면 GitHub 측에서 EC2에 접속해 명령어를 실행할 수 있어 완전한 자동화 배포가 가능합니다. 다만, 민감한 키(secrets.EC2_KEY)가 GitHub 측에 저장된다는 점에 대한 보안 관리(예: 주기적인 키 로테이션, 권한 최소화)가 필요합니다.

3. 마치며

이제 모든 설정이 완료되었습니다. main 브랜치에 코드를 push하면 GitHub Actions가 자동으로 동작하여 코드 체크아웃 -> 검증(테스트 생략) -> EC2 파일 복사 -> 서비스 재시작까지 한 번에 완료해 줍니다.

이렇게 구축된 CI/CD 파이프라인은 초기 세팅에 노력이 들지만, 이후 개발 생산성을 비약적으로 높여주는 강력한 도구가 됩니다. 여러분의 프로젝트에도 꼭 적용해 보시길 권장합니다!

AWS - EC2 서버 구성 및 직접 app 배포 해보기 (CI/CD가 왜 좋은지 이유를 알기 위한 탐...)

호소세 — Wed, 19 Aug 2026 18:23:39 +0900

고민 많이 했습니다. EC2 서버 만드는 과정을 블로그에 작성해야한다는 엄청난 중압감 하지만 사나이라면 이겨내야한다고 생각합니다. 그냥 해보겠습니다. ㅋ

이번시간은 AWS EC2 인스턴스에 직접 접속하여 파이썬 개발 환경을 구축하고,

FastAPI 애플리케이션을 백그라운드 데몬 서비스(systemd)로 등록하여 안정적으로 배포하는 전체 과정을 정리해보겠습니다.

1. 수동 서버/프로덕션 환경 구성의 단점과 한계

클라우드 인프라 구축 시 Terraform이나 Docker/Kubernetes 같은 자동화 도구 없이, EC2에 직접 접속하여 하나씩 세팅하는 방식은 다음과 같은 명확한 한계가 존재합니다. (이 단점을 보여드리기 위한 내용)

시간 소요 및 휴먼 에러(Human Error) 가능성 증가: 설치 명령어나 환경변수를 하나라도 누락하면 원인을 찾기 어려운 오류가 발생할 수 있습니다.
재현성(Reproducibility)의 한계: 패키지 버전 업데이트나 리눅스 환경 변수로 인해 '어제는 되었는데 오늘은 안 되는' 상황이 발생하기 쉽습니다.
결론: 수동 구축은 초기 인프라 구조를 이해하는 데는 가장 좋지만, 실제 운영에서는 CI/CD 파이프라인이나 컨테이너 기반 자동화 배포 환경으로 전환하는 것이 바람직합니다.

2. EC2 초기 접속 및 인프라 사전 준비

1. AWS 콘솔 접속

할당받은 로그인 주소를 통해 콘솔에 접속합니다.

2. 보안 그룹(Security Group) 설정 + 태그 추가

인바운드 규칙에 SSH 접속용 22번 포트와 FastAPI 웹 서비스 연결용 8000번 포트를 개방합니다.

태그 추가하면 검색할 때 쉬워용

3. 퍼블릭 IP 및 Elastic IP(탄력적 IP) 할당

EC2 인스턴스를 재부팅할 때마다 퍼블릭 IP가 변경되는 것을 방지하기 위해 전용 탄력적 IP를 할당받아 매핑합니다.

4. 인스턴스 생성

aws ec2 에 작성해야하는 내용은 영어로 작성해주세요.

저희는 ubuntu를 이용했고 대부분의 설정은 기본 값을 그대로 해주시고 제가 사진 올린것만 변경하시면 됩니다.

키 페어 만드는 것이 매우 중요합니다.

키페어 만들기

잘 만들어서 어디 꽁꽁 숨겨두세요. 해킹당하시지 않게 ㅎㅎ

설정 다 하시고 인스턴스 시작 누르시면 인스턴스 시작됩니다.

5. SSH 접속

터미널이나 SSH 툴(PuTTY, MobaXterm 등)을 열고 퍼블릭 IP와 .pem 키를 이용해 서버에 접근합니다.

MobaXterm 설치 위치

https://mobaxterm.mobatek.net/download-home-edition.html

MobaXterm free Xserver and tabbed SSH client for Windows

The ultimate toolbox for remote computing - includes X server, enhanced SSH client and much more!

mobaxterm.mobatek.net

설치후 실행

Session 버튼 클릭

SSH 클릭

Remote host 값을 EC2 인스턴스에서 가져옵니다.

Username 은 ubuntu 입니다. (default 값이라고 하네요 ㅎㅎ)

저장했던 pem 키는 Use private key에 업로드해주면 됩니다.

다 하시고 ok 누르시면 접속되실 겁니다. 아마 무슨 창이 뜰텐데 accept 해주시면 됩니다.

안되면 조금 상세히 뭐가 안되시는지 댓글 남겨주세요 ㅎㅎㅎ

3. 리눅스 패키지 및 파이썬 가상환경(venv) 세팅

1) 시스템 패키지 업데이트

sudo apt update && sudo apt upgrade -y

알아두면 좋은 리눅스 지식: apt vs apt-get

apt: apt-get과 apt-cache의 주요 기능을 통합하여 일반 사용자가 사용하기 쉽도록 만든 최신 명령어로, 진행률 표시줄 및 권장 패키지 안내 등이 개선되어 대화형 터미널에 적합합니다.

apt-get: 하위 호환성을 보장하는 오래된 명령어입니다. 동작 결과가 일정하여 쉘 스크립트 기반 자동화 작업 시 안전하게 자주 사용됩니다.

2) 파이썬 pip 및 venv 설치

sudo apt install python3-pip python3-venv -y

왜 파이썬 가상환경(venv)을 사용할까요?

하나의 OS 환경에서 여러 파이썬 프로젝트를 구동할 때, 프로젝트 간 라이브러리 패키지 버전 충돌을 방지하고 격리된 독립 환경을 만들어 줍니다.

참고: 도커(Docker) 컨테이너 환경에서는 1개의 컨테이너 OS 단위에 단 하나의 애플리케이션만 구동되므로, 컨테이너 내부에서는 가상환경을 별도로 생성하지 않는 경우가 많습니다.

3) 프로젝트 생성 및 패키지 설치

# 프로젝트 디렉토리 생성 및 이동
mkdir projects && cd projects

# 'web'이라는 이름의 가상환경 생성
python3 -m venv web

# 가상환경 활성화 (프롬프트 앞에 (web) 표시 확인)
source web/bin/activate

# 가상환경 내 pip 최신화
pip install --upgrade pip

# 백엔드 필수 패키지 설치
pip install fastapi uvicorn[standard] jinja2

이후 소스 코드(main.py 등)를 SFTP 전송, Git Clone, 혹은 신규 작성을 통해 ~/projects/ 디렉토리에 배치합니다.

4. 백그라운드 서비스를 위한 systemd 파일 구성

터미널 세션을 종료하더라도 서버가 계속해서 실행되고, EC2 인스턴스가 재가동되더라도 서비스가 자동으로 켜지도록 리눅스 시스템 데몬 서비스(systemd)로 등록해 주어야 합니다.

1) 서비스 등록 파일 생성

/etc/systemd/system/ 디렉토리 내의 모든 파일은 root 권한 소유이므로, sudo 명령어를 활용하여 관리자 권한으로 작성합니다.

sudo nano /etc/systemd/system/hello.service

2) 서비스 설정 내용 기재

아래 내용을 편집기에 그대로 입력합니다.

[Unit]
Description=FastAPI WAS (Web Application Service)
After=network.target

[Service]
User=ubuntu
Group=www-data
# 애플리케이션 소스 코드가 위치한 작업 디렉토리
WorkingDirectory=/home/ubuntu/projects

# 환경변수 파일(.env)이 필요하다면 아래 주석 해제 후 연결
# EnvironmentFile=/home/ubuntu/projects/.env

# 가상환경(web) 내부에 설치된 uvicorn으로 FastAPI 앱 실행
ExecStart=/home/ubuntu/projects/web/bin/uvicorn main:app --host 0.0.0.0 --port 8000

# 프로세스가 다운되거나 OS 재부팅 시 항상 자동 재가동
Restart=always

[Install]
WantedBy=multi-user.target

저장 및 종료 방법: Ctrl + X ➔ Y 입력 ➔ Enter

5. 서비스 등록 및 제어

작성한 서비스 파일을 시스템에 반영하고 제어합니다.

# 1. systemd 데몬 재로드 (새로 작성된 서비스 파일 인식)
sudo systemctl daemon-reload

# 2. 서비스 상태 확인 (초기 상태: inactive)
sudo systemctl status hello.service

# 3. 서비스 시작
sudo systemctl start hello.service

# 4. 서버(OS) 재부팅 시 서비스가 자동으로 실행되도록 설정
sudo systemctl enable hello.service

# 실행 정상 상태 확인 예시
● hello.service - FastAPI WAS (Web Application Service)
     Loaded: loaded (/etc/systemd/system/hello.service; enabled; preset: enabled)
     Active: active (running) since Thu 2026-07-23 02:12:42 UTC; 8s ago
   Main PID: 50681 (uvicorn)

서비스 관리 주요 명령어 요약

중단: sudo systemctl stop hello.service
재가동: sudo systemctl restart hello.service
상태 확인: sudo systemctl status hello.service

6. 최종 배포 테스트

터미널 세션 종료 테스트: SSH 터미널 접속을 종료한 후에도 웹 브라우저에서 http://[EC2-퍼블릭IP]:8000으로 정상 접속되는지 확인합니다.
인스턴스 재부팅 테스트: AWS 콘솔에서 EC2 인스턴스를 재시작(Reboot)한 뒤에도 systemd에 의해 FastAPI 서비스가 자동으로 로드되어 정상 응답하는지 테스트합니다.

이로써 EC2 환경에 FastAPI 애플리케이션 수동 배포 및 자동 재시작 환경 세팅이 모두 완료되었습니다! 추후에는 이 환경에 GitHub Actions나 Jenkins를 연동하여 CI/CD 파이프라인으로 발전시킬 수 있습니다.

아 그리고 소스 코드가 필요하시다면 여기서 사용하세요.

main branch에 있는 소스 사용하시면 됩니다.

https://github.com/hosose/my_project

GitHub - hosose/my_project: git 사용 연습

git 사용 연습. Contribute to hosose/my_project development by creating an account on GitHub.

github.com

아무튼 위의 작업을 자동화하여 직접 수동으로 터미널에 작성하지 않게 하기 위해 CI/CD를 반드시 해야합니다! 너무 귀찮거덩요.

GitHub Actions - CI/CD (./github/workflow/deploy.yml)

호소세 — Tue, 18 Aug 2026 18:39:51 +0900

이번 시간에는 현대 소프트웨어 개발 및 DevOps 환경에서 필수 요소로 자리 잡은 CI/CD(지속적 통합 및 지속적 배포)의 개념과 배포 모델(Push vs Pull), 그리고 GitHub Actions를 활용하여 AWS EC2 인스턴스에 코드를 자동으로 배포하는 실습까지 한눈에 알기 쉽게 정리해 보겠습니다.

1. CI/CD 개요 및 필요성

CI/CD란?

CI (Continuous Integration, 지속적 통합): 개발자들이 작업한 소스 코드를 주기적으로 중앙 저장소에 자동 합치고, 이를 검증하기 위해 자동화된 빌드 및 테스트를 수행하는 프로세스입니다.
CD (Continuous Delivery / Deployment, 지속적 제공 / 배포):
- Continuous Delivery: CI 통과 후 프로덕션 환경에 배포할 수 있도록 준비(릴리스)하는 과정입니다. (최종 배포 버튼은 사람이 클릭)
- Continuous Deployment: CI를 통과한 코드를 사람이 개입하지 않고 실제 프로덕션 서버에 자동으로 배포하는 완벽 자동화 과정입니다.

CI/CD 도입 시 이점

개발 라이프사이클 단축: 코드 작성 후 배포까지 걸리는 수동 작업 시간을 획기적으로 줄여줍니다.
안정성 및 소프트웨어 품질 향상: 커밋마다 자동 테스트가 실행되므로 버그와 코드 충돌을 빠르게 감지합니다.
생산성 증가 및 비용 절감: 반복적인 배포 작업이 자동화되어 개발자가 비즈니스 로직 작성에만 집중할 수 있습니다.

2. CI/CD 배포 모델 (Push vs Pull)

배포 방식은 크게 Push 방식(전통적 방식)과 Pull 방식(GitOps 방식)으로 나누어 볼 수 있습니다.

[ Push 모델 ]
  GitHub (CI) ─────SSH 접속/파일전송(Push)─────>  AWS EC2 (운영서버)

[ Pull 모델 (GitOps) ]
  GitHub (CI) ──(Manifest 변경)──> Git Repo <──주기적 감지/가져오기(Pull)── ArgoCD (클러스터 내부)

1) Push 모델 (전통적 방식)

정의: CI 서버(GitHub Actions, Jenkins 등)가 빌드/테스트를 완료한 후, 직접 원격 서버(AWS EC2 등)에 접속(SSH)하여 배포 명령을 밀어넣는(Push) 방식입니다.
특징:
- 하나의 파이프라인 안에서 [빌드 ➔ 테스트 ➔ 배포]를 일괄적으로 직관 처리할 수 있습니다.
- 구성이 매우 간단하여 소규모 프로젝트나 단일 서버 환경에 적합합니다.
- 주의점: CI 서버가 운영 서버의 접근 권한(SSH Key, IP 정보 등)을 들고 있어야 하므로, CI 서버가 해킹당할 경우 보안 위험이 발생할 수 있습니다.

2) Pull 모델 (GitOps 방식)

정의: 배포 서버 내부의 에이전트(ArgoCD 등)가 Git 저장소를 주기적으로 모니터링하다가 새로운 변경 사항(Manifest)이 생기면 스스로 가져와(Pull) 적용하는 방식입니다.
특징:
- CI 서버가 운영 환경에 직접 접근하지 않으므로 보안상 매우 유리합니다.
- 쿠버네티스(Kubernetes) 환경에서 버전 관리 및 선언적 배포(Declarative Deployment) 관리가 수월합니다.

Tip: 단일 EC2에 소규모 서비스를 배포할 때는 Push 모델(GitHub Actions + SSH)이 훨씬 간단하고 효율적입니다. 반면, 쿠버네티스 기반의 클러스터 환경에서는 Push(CI) + Pull(CD via ArgoCD)을 조합하는 것이 현대적인 대세 패턴입니다.

3. [실습] GitHub Actions를 이용한 Push 기반 CI/CD 구축

이제 GitHub Actions를 이용해 소스 코드가 main 브랜치에 push되면,

AWS EC2 서버로 소스 코드가 자동 전송되는 파이프라인을 만들어 보겠습니다.

1) 프로젝트 구조 준비

우선 아래와 같이 파이썬(FastAPI 또는 Flask) 프로젝트가 구성되어 있다고 가정합니다.

main.py
templates/index.html
static/

GitHub Actions를 발동시키려면 프로젝트 루트 디렉토리에 .github/workflows/ 폴더를 만들고 YAML 파일(예: deploy.yml)을 작성해야 합니다.

2) 사전 작업: GitHub Secrets 환경 변수 등록

SSH 접속 정보와 비밀키를 소스 코드(YML)에 직접 하드코딩하면 보안상 치명적입니다. GitHub 저장소의 Settings ➔ Secrets and variables ➔ Actions로 이동하여 다음 비밀값들을 등록해 줍니다.

HOST: AWS EC2 퍼블릭 IP 주소 (또는 도메인)
USERNAME: EC2 OS 사용자 이름 (Ubuntu의 경우 기본값 ubuntu)
EC2_KEY: EC2 인스턴스 생성 시 받은 .pem 파일의 전체 텍스트 내용

3) GitHub Actions 워크플로우 파일 작성 (.github/workflows/deploy.yml)

아래 코드를 작성하여 프로젝트에 포함한 뒤 GitHub에 Push합니다.

# 파이프라인 이름 지정
name: Push 기반 CI/CD 테스트

# 1. 트리거(Trigger) 정의
# main 브랜치에 push 이벤트가 발생하면 이 워크플로우가 자동으로 실행됩니다.
on:
  push:
    branches:
      - main

# 2. 수행할 작업(Jobs) 정의
jobs:
  ci:
    # GitHub에서 제공하는 최신 Ubuntu 가상 환경(Runner)에서 작업 실행
    runs-on: ubuntu-latest

    steps:
      # Step 1: GitHub 저장소에 등록된 최신 코드를 가상 환경으로 가져옴(Checkout)
      - name: 코드 checkout
        uses: actions/checkout@v4

      # Step 2: 코드 전달 상태 및 테스트 검증
      - name: 확인 검증
        # 여러 줄의 Bash 명령어를 실행할 때는 '|' 부호를 사용합니다.
        run: |
          pwd
          ls -al
          cat main.py
        shell: bash

      # Step 3: SCP(Secure Copy)를 이용해 AWS EC2 서버로 소스 코드 전송
      - name: source code copy to EC2
        uses: appleboy/scp-action@master
        with:
          host: ${{ secrets.HOST }}
          username: ${{ secrets.USERNAME }}
          key: ${{ secrets.EC2_KEY }}
          port: 22
          # 복사할 대상 ('.' 은 현재 프로젝트의 모든 파일)
          source: .
          # EC2 서버 내부에서 파일이 복사되어 들어갈 경로
          target: "/home/ubuntu/projects"

한 걸음 더! (실무 팁: 코드 전송 후 서비스 자동 재시작)

현재 작성된 scp-action은 소스 코드를 서버로 '전송'하는 역할만 수행합니다. 실제 배포가 완료되려면 전송이 끝난 후 FastAPI/Flask 백엔드 서버 프로세스를 재시작해 주어야 새 코드가 반영됩니다.

이때는 appleboy/ssh-action을 파이프라인 마지막 스텝에 추가하여 EC2 명령어를 실행해 주는 것이 좋습니다.

      # Step 4 (추가 권장): EC2 서버 접속 후 서비스 프로세스 재시작
      - name: SSH로 EC2 접속 후 애플리케이션 재시작
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.HOST }}
          username: ${{ secrets.USERNAME }}
          key: ${{ secrets.EC2_KEY }}
          port: 22
          script: |
            cd /home/ubuntu/projects
            # 예시: 기존 uvicorn/python 프로세스 종료 후 재구동 (또는 systemctl restart / docker-compose restart 등)
            sudo systemctl restart my_app.service

4. 마치며

GitHub Actions를 활용하면 복잡한 빌드 및 배포 과정을 손쉽게 자동화할 수 있습니다.

main 브랜치에 코드 Push
GitHub Actions가 이를 감지하여 최신 코드 검증
AWS EC2 서버로 파일 전송 및 서비스 자동으로 재시작

이 파이프라인 구축을 통해 수동 배포로 인한 실수(Human Error)를 방지하고, 빠르고 안전하게 서비스를 업데이트할 수 있습니다. 실무 프로젝트에서도 차근차근 적용해 보세요!

오늘의 한 마디

업무 진행하면서 운영중인 서버에 파일을 직접 배포하고 재시작할 때면 얼마나 마음이 떨리는지 직접해보지 않으면 알지 못할겁니다. 이런 ci/cd 기술을 개발시 미리 만들어 놓고 진행하는 것이 백번 천번 좋습니다. 요즘은 ai의 발달로 ci/cd하는 것도 점점 쉬워지지 않을까 생각이 듭니다. 명령어만 잘 치면 말이죠.

확실히 ci/cd가 있는 프로젝트와 없는 프로젝트는 차이가 너무 납니다. 어떤 미친 프로젝트는 형상관리도 안되고 있어 제가 직접 svn을 설치하여 프로젝트 형상관리를 그제서야 진행한 것도 있습니다... 하 갑자기 생각하니 열받으니 여기까지만 하시죠 ㅎㅎ

[Git/GitHub] GitHub 원격 저장소 생성, 커밋·푸시 및 취소(Reset/Revert)

호소세 — Mon, 17 Aug 2026 18:10:40 +0900

GitHub를 활용해 1인 프로젝트를 관리할 때 필수적으로 거치는

원격 저장소 생성 ➔ 로컬 복사(Clone) ➔ 작업 ➔ 스테이징(Add) ➔ 커밋(Commit) ➔ 푸시(Push)의 전체 과정과,

작업 도중 실수가 발생했을 때 유용한 작업 취소 및 되돌리기(Restore/Reset/Revert) 방법을 알기 쉽게 정리해 보겠습니다.

1. 원격 저장소(Remote Repository) 생성하기

가장 먼저 GitHub 웹사이트에서 프로젝트의 중심이 될 원격 저장소를 생성합니다.

생성 절차 및 옵션

GitHub 우측 상단의 + 버튼 클릭 ➔ New repository 선택
General 설정:
- Repository name: my_project (프로젝트의 성격을 나타내는 직관적인 이름으로 지정)
- Description: git 사용 연습 (저장소에 대한 간단한 설명 입력)
Configuration 설정:
- Visibility: Public(공개) 또는 Private(비공개) 선택 (팀 작업이나 보안이 필요한 소스코드는 Private 권장)
- Add a README file: ON (프로젝트 소개 문서를 기본 생성합니다. OFF로 생성 후 나중에 직접 만들어도 무방합니다.)
- Add .gitignore: Python 검색 후 선택

.gitignore 파일이란? Python 실행 시 생성되는 임시 파일, 가상환경 폴더(venv), 데이터베이스 비밀번호가 담긴 환경변수 파일(.env) 등 Git이 추적할 필요가 없거나 외부에 유출되면 안 되는 파일들을 자동으로 제외해 주는 아주 중요한 설정 파일입니다.

Add a license: 현재는 미선택 (추후 Open Source 라이선스가 필요한 경우 선택)

4. Create repository 버튼 클릭으로 원격 저장소 생성 완료!

2. 원격 저장소 로컬 PC로 클론(Clone)하기

생성된 원격 저장소를 내 컴퓨터(로컬 PC)로 가져오는 작업입니다.

Clone 수행 과정

생성된 GitHub 저장소 메인 화면에서 초록색 Code 버튼 클릭 ➔ SSH 또는 HTTPS 주소 복사
로컬 PC의 터미널(CMD / PowerShell / Bash)에서 작업할 디렉토리로 이동:

C:\Users\Dell3571> cd Desktop/workspace

복사한 원격 저장소 주소를 이용해 클론 실행:

git clone git@github.com:[유저아이디]/my_project.git

Cloning into 'my_project'...
remote: Enumerating objects: 4, done.
remote: Counting objects: 100% (4/4), done.
remote: Compressing objects: 100% (3/3), done.
remote: Total 4 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
Receiving objects: 100% (4/4), done.

클론이 완료되면 my_project 폴더가 생성됩니다. VS Code 등의 에디터로 해당 폴더를 열어 작업을 시작합니다.

3. 1인 개발 형상관리 워크플로우 (개발 ➔ 스테이징 ➔ 커밋 ➔ 푸시)

Git으로 코드 이력을 관리할 때는 크게 3가지 영역(Working Directory ➔ Staging Area ➔ Repository)을 거치게 됩니다.

[ Working Directory ] ──(git add)──> [ Staging Area ] ──(git commit)──> [ Local Repo ] ──(git push)──> [ Remote Repo ]
    (코드 작성/수정)                    (장바구니)                         (로컬 기록)                    (GitHub)

1) 기능 개발 (Working Directory)

새로운 파일 app.py를 생성하고 코드를 작성합니다.

print("hi")

2) 스테이징 (Staging / git add)

변경 사항을 커밋하기 전에 "장바구니(Staging Area)"에 담는 단계입니다.

변경사항 전체 올리기:

git add .

특정 파일만 올리기:

git add app.py

[취소하기] 스테이징 되돌리기 (Unstage)

장바구니에 잘못 담은 파일을 다시 작업 영역으로 되돌립니다.

전체 파일 스테이징 취소:

git restore --staged .

특정 파일 스테이징 취소:

git restore --staged app.py

3) 커밋 (Commit / git commit)

스테이징 영역에 올라온 파일들을 어떤 작업을 했는지 설명하는 메모와 함께 로컬 저장소(.git)에 영구적으로 기록합니다.

git commit -m "Feat: 메인코드 작성"

좋은 커밋 메시지 작성 태그 (Commit Convention)

Feat: 새로운 기능 추가

Fix: 버그 수정

Docs: 문서 수정 (README 등)

Refactor: 코드 리팩토링 (기능 변경 없는 구조 개선)

Chore: 빌드 업무, 패키지 매니저 설정 등

[취소하기] 로컬 커밋 되돌리기 (git reset)

이미 수행한 커밋을 취소하고 이전 상태로 되돌릴 수 있습니다. reset 명령어의 옵션 차이를 이해하는 것이 중요합니다.

(이건 직접 해보시면 바로 느낌 옵니다.)

--soft: 코드는 유지하고, 커밋만 취소하여 파일을 스테이징(Staging) 상태로 되돌립니다.

git reset --soft HEAD^

--mixed (기본값): 코드는 유지하고, 커밋과 스테이징을 모두 취소하여 개발(Unstaged) 상태로 되돌립니다.

git reset HEAD^

--hard: 커밋, 스테이징 취소는 물론 작성했던 코드까지 완전히 파기하고 이전 커밋 시점으로 되돌립니다. (※ 복구가 어려우므로 주의해서 사용해야 합니다.)

git reset --hard HEAD^

4) 푸시 (Push / git push)

로컬 저장소에 기록된 커밋들을 GitHub 원격 저장소로 업로드(동기화)합니다.

git push origin main

Enumerating objects: 4, done.
Counting objects: 100% (4/4), done.
Writing objects: 100% (3/3), 341 bytes | 341.00 KiB/s, done.
To github.com:ucoccto/my_project.git
   5ab9259..f0f2055  main -> main

푸시 완료 후 GitHub 웹사이트를 새로고침하면 내가 작성한 파일과 커밋 메시지가 정상적으로 반영된 것을 확인할 수 있습니다.

4. 이미 푸시한 작업 안전하게 취소하기 (git revert)

원격 저장소(GitHub)에 이미 git push까지 완료된 커밋을 취소할 때, git reset으로 히스토리를 강제로 삭제하고 푸시하면 원격 저장소와의 이력이 꼬여 협업이나 추적에 문제가 생길 수 있습니다.

이때는 이전 커밋을 삭제하는 것이 아니라, 해당 커밋의 작업을 반대로 수행하는 '새로운 커밋'을 생성하는 revert를 사용하는 것이 안전합니다.

# 가장 최근 푸시된 커밋의 반대 작업을 담은 커밋 생성
git revert HEAD

git revert를 실행하면 에디터가 열리면서 리버트 커밋 메시지를 작성하게 됩니다.

저장 후 닫은 뒤, 다시 git push origin main을 해주면 안전하게 취소 이력이 반영됩니다.

️ 요약 및 정리

원격 저장소 생성: GitHub에서 .gitignore 설정과 함께 저장소 생성
클론: git clone <주소> 명령으로 내 PC로 가져오기
기본 루틴:
- 파일 작성/수정 ➔ git add . (스테이징) ➔ git commit -m "메시지" (로컬 기록) ➔ git push origin main (원격 업로드)
취소 명령어 정리:
- 스테이징 취소: git restore --staged <파일명>
- 로컬 커밋 취소: git reset (--soft / --mixed / --hard) HEAD^
- 푸시된 커밋 취소: git revert HEAD ➔ git push

Git의 단계별 흐름과 되돌리기 명령어들의 차이점을 이해하면 실수하더라도 당황하지 않고 안전하게 프로젝트를 관리하실 수 있습니다!

[Git/GitHub] 개발 필수 도구 Git 기초 개념부터 SSH 인증 및 초기 세팅

호소세 — Fri, 14 Aug 2026 18:43:09 +0900

현대 소프트웨어 개발에서 결코 빠질 수 없는 필수 도구인 Git과 GitHub의 개요부터, 초보자분들이 가장 헷갈려하시는 SSH 공개키 연동 및 초기 환경 설정 과정을 깔끔하게 정리해 드리겠습니다.

1. 개요 (Git & GitHub란?)

Git과 GitHub의 차이점 (지식 더하기)

많은 분들이 Git과 GitHub를 같은 것으로 오해하곤 합니다.

Git: 내 컴퓨터(로컬)에서 코드의 변경 이력을 기록하고 관리하는 분산 버전 관리 시스템(DVCS) 소프트웨어입니다.
GitHub: Git으로 관리되는 프로젝트들을 클라우드(원격)에 저장하고 공유할 수 있게 해주는 웹 기반 저장소 서비스입니다.

주요 기능

협업 관리: 1인 개인 프로젝트부터 수십, 수백 명 단위의 대규모 팀 프로젝트까지 효율적인 소스코드 통합 및 동시 작업 지원
형상 관리 & 이력 관리: 코드의 변경 내역을 시간순으로 저장하여 언제든 과거 특정 시점으로 복구 가능
코드 분석 & 리팩토링: 브랜치(Branch) 기능을 활용해 안전하게 신규 기능을 개발하고 리팩토링 테스트 가능
디버깅 & 트러블슈팅: 이슈(Issue) 관리 기능을 통해 버그를 추적하고, git blame 등을 통해 문제가 발생한 코드의 작성자와 시점 파악
문서화 & AI 생산성 증대: Wiki, README를 통한 프로젝트 문서화 및 GitHub Copilot과 같은 AI 보조 도구 활용

개인 이력 관리 (포트폴리오)

과거에는 깃허브의 '잔디(Commit 이력)'가 개발자의 성실함을 증명하는 핵심 이력이었습니다. 최근 AI 시대에 들어서며 단순 커밋의 수보다는 어떤 프로젝트에 참가했고, 문제 해결을 위해 어떤 고민을 거쳤는지 증명하는 기록 도구로서의 성격이 강화되었습니다.

2. Git 설치 및 GitHub 회원가입

1) Git 설치 (Windows 기준)

Git 공식 다운로드 페이지에 접속하여 설치 프로그램을 다운로드합니다.
기본 옵션 그대로 설치를 진행해 주시면 큰 이슈 없이 완료됩니다.
설치 확인: CMD(명령 프롬프트) 또는 PowerShell을 열고 아래 명령어를 입력해 정상 작동 여부를 확인합니다.

git

출력 예시: usage: git [-v | --version] [-h | --help] ... 문구가 출력되면 정상 설치된 것입니다.

2) GitHub 가입

GitHub 공식 홈페이지에서 개별 가입을 진행합니다. (Google 계정을 활용하면 빠르게 가입하실 수 있습니다.)

3. SSH 공개키(Public Key) 등록 (인증 자동화)

GitHub에 코드를 올리거나(push) 가져올 때(pull) 매번 아이디와 비밀번호를 입력하는 것은 번거로울 뿐만 아니라 보안상 권장되지 않습니다. 로컬 PC와 GitHub 간에 SSH 키(Key)를 등록해 두면 비밀번호 없이 안전하고 편리하게 자동 인증을 처리할 수 있습니다.

SSH 키 작동 원리 (비대칭키 암호화)

비밀키 (id_rsa): 내 컴퓨터에만 안전하게 보관되는 키 (절대 외부에 유출되면 안 됨)

공개키 (id_rsa.pub): GitHub와 같은 원격 서버에 등록하는 키

Step 1: SSH 키 발급받기

CMD 터미널을 열고 본인의 GitHub 가입 이메일 주소를 넣은 후 아래 명령어를 실행합니다.

ssh-keygen -t rsa -C "본인이메일@gmail.com"

명령어 실행 후 비밀번호 입력창 등이 나오는데, 엔터(Enter) 키를 3회 연속 입력하여 기본값으로 생성합니다.

# 실행 결과 예시
Your identification has been saved in C:\Users\사용자계정/.ssh/id_rsa
Your public key has been saved in C:\Users\사용자계정/.ssh/id_rsa.pub
The key fingerprint is:
SHA256:B2jQfb/lq542+w1e2v48r2cceYAr3oyeE07zFE4 본인이메일@gmail.com

Step 2: 공개키 복사하기

탐색기를 열어 위에 저장된 C:\Users\사용자계정\.ssh\ 디렉토리로 이동합니다.
id_rsa.pub (공개키) 파일을 VS Code나 메모장으로 열어줍니다.
ssh-rsa AAAAB3NzaC1... 로 시작하는 전체 텍스트 내용을 복사합니다.

Step 3: GitHub에 공개키 등록하기

[GitHub] 접속 후 로그인
우측 상단 프로필 아이콘 클릭 > Settings 진입
좌측 메뉴의 SSH and GPG keys 클릭
New SSH key 버튼 클릭
Title에는 PC 이름(예: My Laptop)을 적고, Key 란에 복사했던 id_rsa.pub 파일의 내용을 붙여 넣은 뒤 Add SSH key 클릭

4. 로컬 PC Git 글로벌 환경 설정 (Global Config)

Git으로 코드 이력을 남길 때(Commit), "누가 이 코드를 작성했는지" 기록을 남겨야 합니다.

이를 위해 터미널에서 글로벌 사용자 정보를 설정해줍니다.

1) 사용자 이메일 및 이름 설정

# GitHub에 가입한 이메일 입력
git config --global user.email "본인이메일@gmail.com"

# GitHub 프로필 이름(닉네임) 입력
git config --global user.name "본인닉네임"

⚠️ 주의: 설정하는 이메일은 반드시 GitHub 계정에 등록된 이메일과 동일해야 커밋 내역이 본인의 GitHub 프로필(잔디)에 올바르게 연동됩니다!

2) 설정 내용 확인

정상적으로 설정이 완료되었는지 아래 명령어로 목록을 확인합니다.

git config --list

# 주요 설정 확인 목록 예시
init.defaultbranch=master (또는 main)
user.email=본인이메일@gmail.com
user.name=본인닉네임

Docker Compose - FastAPI + MySQL 다중 컨테이너 환경 구축하기

호소세 — Thu, 13 Aug 2026 18:34:35 +0900

이전 포스팅에서 단일 컨테이너를 생성하는 Dockerfile에 대해 알아보았다면, 오늘은 여러 개의 컨테이너를 하나로 묶어서 일괄 관리할 수 있는 도구, 'Docker Compose(도커 컴포즈)'에 대해 정리해 보겠습니다.

실제 웹 서비스는 단일 프로그램으로 돌아가지 않습니다. 웹 서버, 백엔드 애플리케이션, 데이터베이스가 각각의 역할을 맡아 유기적으로 통신해야 하죠. 복잡해지는 컨테이너들을 명령어 하나로 제어하는 방법을 지금부터 알아보겠습니다.

1. Docker Compose 개요

Docker Compose는 특정 서비스를 구성하는 모든 컨테이너 요소를 한 번에(일괄적으로) 정의하고 실행할 때 사용하는 도구입니다. 주로 docker-compose.yml (또는 compose.yaml) 파일에 설정을 명시하여 사용합니다.

통상적인 웹 서비스 아키텍처 일반적으로 다음과 같은 3계층(3-Tier) 구조로 컨테이너를 분리하여 구성합니다.
- Web Server: Nginx 컨테이너 (정적 자원 처리 및 리버스 프록시 역할)
- WAS Server: FastAPI 컨테이너 (비즈니스 로직 처리, Python + Uvicorn + FastAPI)
- DB Server: MySQL 컨테이너 (데이터 저장)
사용 범위 및 한계
- 도커 컴포즈는 1개의 물리적인 호스트 PC(단일 OS) 내에서 여러 컨테이너를 묶어 실행하는 데 최적화되어 있습니다.

지식 더하기: 만약 트래픽이 몰려 여러 대의 서버(노드)로 분산 처리를 하거나 오토 스케일링(확장)이 필요한 대규모 구조라면, 도커 컴포즈의 범위를 넘어서므로 쿠버네티스(Kubernetes)와 같은 컨테이너 오케스트레이션 도구로 넘어가야 합니다.

2. docker-compose.yml 파일 작성 및 분석

웹 서비스의 데이터베이스(MySQL)와 백엔드 애플리케이션(FastAPI)을 정의한 컴포즈 파일 예시입니다. YAML 형식은 들여쓰기(띄어쓰기 2칸)가 매우 중요하므로 작성 시 주의해야 합니다.

# 각각의 서비스 주체들을 구성합니다. 각 주체는 하나의 독립된 컨테이너가 됩니다.
services:
  # 1. 데이터베이스 서비스
  # 서비스명(db)은 컨테이너명과 통상 일치시키며, 도커 네트워크 내부에서 도메인 주소로 사용됩니다.
  db:
    image: mysql
    container_name: mysql_db
    # restart 정책: 컨테이너가 중단되거나 오류 발생, 재부팅 시 항상 자동으로 재구동되게 설정합니다.
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: 1234
      MYSQL_DATABASE: memo  # 컨테이너 생성 시 최초로 구성될 빈 데이터베이스 이름
      MYSQL_USER: guest
      MYSQL_PASSWORD: 1234
    # 볼륨 설정: 컨테이너가 삭제되어도 데이터는 보존되도록 네임드 볼륨을 마운트합니다.
    volumes:
      - mysql-vol:/var/lib/mysql
    ports:
      - "3306:3306"
    networks:
      - my-net

  # 2. 백엔드 애플리케이션 서비스 (FastAPI)
  app:
    # build: 도커 허브의 이미지를 받는 대신, ./app 디렉토리 내부의 Dockerfile을 읽어 직접 이미지를 빌드합니다.
    build: ./app
    container_name: fastapi_app
    # restart 정책: 수동으로 정지(stop)하지 않는 한 재시작을 시도합니다.
    restart: unless-stopped
    # command: Dockerfile의 CMD를 덮어쓰며, Uvicorn 데몬을 백그라운드로 띄워 서버를 가동합니다.
    command: uvicorn main:app --host 0.0.0.0 --port 8000
    # ports: "호스트 포트 : 컨테이너 포트" 형식으로 외부 접근을 개방합니다.
    ports:
      - "8000:8000"
    # 바인드 마운트: 호스트 OS(개발 PC)의 ./app 경로와 컨테이너의 /app 경로를 실시간 동기화합니다.
    volumes:
      - ./app:/app
    networks:
      - my-net
    # 의존성 명시: db 컨테이너가 먼저 구동된 후 app 컨테이너가 실행되도록 순서를 보장합니다.
    depends_on:
      - db

# 사용할 도커 네트워크를 정의합니다.
networks:
  my-net:
    driver: bridge

# 사용할 네임드 볼륨을 선언합니다.
volumes:
  mysql-vol:

지식 더하기 (depends_on): depends_on은 단순히 '실행 순서'만 보장할 뿐, 내부 서비스(MySQL 프로세스)가 온전히 준비되어 연결 가능한 상태인지까지 기다려주지는 않습니다. 실제 실무에서는 DB 부팅이 늦어져 App이 DB 연결에 실패하는 경우가 발생하므로, healthcheck 설정을 추가하여 DB 프로세스 자체가 정상인지 확인한 후 App을 띄우는 심화 방식을 사용하기도 합니다.

3. 백엔드(WAS) 구성을 위한 하위 파일들

앞선 docker-compose.yml에서 app 서비스는 ./app 폴더의 Dockerfile을 빌드하도록 설정했습니다. 해당 폴더에 들어갈 파일 구성은 다음과 같습니다.

1) Dockerfile

# 1. 베이스 이미지 지정 (경량화된 slim 버전 사용)
FROM python:3.14.0-slim

# 2. 컨테이너 내부의 기본 작업 디렉토리 지정
WORKDIR /app

# 3. 라이브러리 설치 목록 파일 복사
COPY requirements.txt .

# 4. 파이썬 라이브러리 설치
RUN pip install -r requirements.txt

# 5. 원본 소스 코드 복사
# 실무에서는 COPY . . 방식을 주로 사용하며, 불필요한 파일은 .dockerignore로 걸러냅니다.
COPY main.py . 

# 6. 서버 가동 명령어 (도커 컴포즈의 command 속성으로 이관하였으므로 생략 가능합니다.)
# CMD ["uvicorn", "main:app", "--reload"]

2) requirements.txt

fastapi
uvicorn
jinja2

3) main.py (FastAPI 앱 코드)

# 1. 모듈 가져오기
from fastapi import FastAPI

# 2. FastAPI 객체 생성
app = FastAPI()

# 3. 라우터 설정: 특정 URL 요청에 대해 처리할 함수 매핑
@app.get("/")       # "/" 루트 경로 접근 시
def read_root():    # 응답으로 JSON 반환
    return {"message": "Hello World2"}

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

4. 생성, 실행, 종료 (라이프사이클 관리)

도커 컴포즈가 작성된 폴더에서 터미널을 열고 명령어 단 한 줄만 입력하면, 정의된 모든 네트워크, 볼륨, 컨테이너가 순서에 맞게 한 번에 생성되고 구동됩니다.

1. 일괄 실행 (up)

docker-compose up -d

-d 옵션을 주면 데몬(백그라운드) 모드로 실행되어 터미널을 계속 사용할 수 있습니다.
실행 시 Network, Volume이 먼저 생성되고, 의존성에 따라 mysql_db가 켜진 뒤 fastapi_app이 실행됩니다.

정상 작동

2. 일괄 종료 및 삭제 (down)

docker-compose down

구동 중인 컨테이너들을 안전하게 정지한 뒤 삭제하고, 생성했던 네트워크 망(my-net)도 함께 삭제합니다.
중요 포인트: down 명령어를 수행하여 컨테이너와 네트워크가 삭제되더라도, 데이터베이스가 저장된 볼륨(mysql-vol)은 절대 삭제되지 않고 유지됩니다!

3. 데이터 보존 확인

docker-compose up -d

다시 서비스를 구동해 보면, 네트워크와 컨테이너는 새로 만들어지지만 볼륨은 기존 것을 그대로 마운트하기 때문에 DB에 저장해 둔 데이터가 안전하게 복구된 것을 확인할 수 있습니다.

명령어 관련 추가 내용

docker-compose up -d 단독 실행 시 app 서비스의 빌드된 이미지가 로컬에 없는 최초 실행 상태라면, 도커 컴포즈가 자동으로 build: ./app 경로를 참조하여 이미지를 빌드한 후 컨테이너를 구동합니다. 만약 이미 빌드된 이미지가 존재한다면, Dockerfile의 변경 사항을 무시하고 기존 이미지를 재사용하여 구동합니다.
docker-compose up -d --build 실행 시 기존 이미지의 존재 여부와 무관하게 Dockerfile을 바탕으로 이미지를 강제로 다시 빌드한 후 컨테이너를 갱신하여 구동합니다.

최초 실행이거나 컨테이너의 근본적인 환경(Dockerfile 내용 변경, 새로운 패키지 설치 등)에 변화가 없다면 --build 옵션 없이 실행해도 정상 구동됩니다.

환경 설정이나 종속성 변경 사항을 이미지에 새로 반영해야 할 때만 --build 옵션을 추가하여 실행하면 됩니다.

Docker - Dockerfile (LABEL, ARG)

호소세 — Wed, 12 Aug 2026 18:01:37 +0900

1. LABEL 및 ARG의 개념

LABEL: 도커 이미지 자체에 부여하는 Key-Value 형태의 메타데이터입니다.
ARG: docker build가 실행되는 빌드 시점에만 유효한 변수입니다. 빌드가 완료된 후 구동되는 컨테이너 런타임 환경에서는 이 변수값에 접근할 수 없습니다.

FROM ubuntu

# ARG: 빌드 시점에만 존재하는 변수와 기본값 생성
ARG cus_title="도커 파일 기반 커스텀 이미지"

# LABEL: 이미지 메타데이터에 변수값 적용
LABEL title=$cus_title
LABEL author="익명"

# RUN: 빌드 로그에서 변수값 출력
RUN echo ${cus_title}

2. 이미지 정보 조회 명령어 정정

LABEL 정보는 컨테이너가 아닌 이미지에 기록되는 메타데이터입니다.

컨테이너가 해당 이미지를 기반으로 실행되면서 정보를 상속받기 때문에 컨테이너 inspect 명령에서도 확인할 수는 있으나, 순수하게 '이미지의 정보'를 확인하기 위한 정확한 명령어는 docker container inspect가 아닌 docker image inspect를 사용해야 합니다.

[이미지 정보 확인 명령어 적용]

# 이미지 빌드
docker build -t test_ubuntu:1.5 ./step5

# 이미지를 기반으로 컨테이너 가동
docker run -itd --name test_ubuntu_1.5 test_ubuntu:1.5

# 이미지 메타데이터 상세 정보 확인 (정정된 명령어)
docker image inspect test_ubuntu:1.5

[실행 결과 확인 (JSON 반환값 일부)]

"Labels": {
    "author": "익명",
    "title": "도커 파일 기반 커스텀 이미지"
}

Docker - Dockerfile (ENTRYPOINT, WORKDIR, ENV)

호소세 — Tue, 11 Aug 2026 18:57:05 +0900

Dockerfile을 통해 컨테이너의 실행 명령을 지정하고, 내부 작업 디렉토리 및 환경 변수를 설정하는 방법입니다.

원문에 기재된 실행 명령 관련 전제 중 일부 부정확한 부분을 정정 및 보완했습니다.

1. ENTRYPOINT와 CMD의 차이 및 결합 동작

ENTRYPOINT ["nginx"]와 CMD ["-g","daemon off;"]의 결합이 CMD ["nginx","-g","daemon off;"]와 같다고 할 수 없습니다.

이 둘은 런타임 시 인자값(Argument) 덮어쓰기(Override) 여부에 있어 명확한 차이가 존재하므로 분리하여 이해해야 합니다.

CMD: 컨테이너 실행 시 작동할 기본 명령을 지정합니다. 사용자가 docker run <이미지명> <추가명령어> 형태로 실행할 경우, Dockerfile 내부의 CMD 내용은 무시되고 사용자가 입력한 추가 명령어로 대체됩니다.
ENTRYPOINT: 컨테이너가 메인 프로세스로 실행할 고정된 실행 파일을 지정합니다. docker run 시 추가 인자를 입력하더라도 ENTRYPOINT의 실행 파일은 덮어쓰기 되지 않고 그대로 유지됩니다.
결합 사용: 두 명령어를 함께 작성할 경우, CMD는 ENTRYPOINT로 지정된 실행 파일에 전달할 '기본 매개변수' 역할을 수행합니다.

FROM ubuntu

# ENTRYPOINT: 런타임 시 변경되지 않는 메인 실행 파일 지정
ENTRYPOINT [ "nginx" ]

# CMD: ENTRYPOINT에 전달할 기본 매개변수 (사용자가 docker run 시 다른 옵션으로 덮어쓰기 가능)
CMD ["-g", "daemon off;"]

2. WORKDIR (작업 디렉토리)

WORKDIR은 컨테이너 내부의 작업 위치를 변경합니다. 리눅스의 cd 명령어와 목적이 같습니다.
한 번 지정되면 이후에 등장하는 ADD, COPY, RUN, CMD, ENTRYPOINT 명령어는 모두 해당 경로를 기준으로 동작합니다. 만약 명시한 디렉토리가 존재하지 않으면 도커 엔진이 해당 경로를 자동 생성합니다.

3. ENV (환경 변수)

ENV는 컨테이너 내부 운영체제 환경에서 전역적으로 사용할 변수를 선언합니다.
주로 데이터베이스 접속 정보, 타임존, 서비스 포트 등 애플리케이션에 필요한 동적 구성 값을 컨테이너에 전달할 때 사용됩니다.

# 권장 표기법: 한 줄에 여러 개의 환경 변수 선언 시 '=' 기호 사용
ENV MYSQL_USER=admin MYSQL_PORT=3306

ENTRYPOINT와 CMD의 차이

위의 ENTRYPOINT와 CMD 의 차이에 대해 조금 더 궁금해서 더 찾아보았습니다!

두 방식의 핵심적인 차이는 컨테이너 실행 시(docker run) 사용자가 입력하는 추가 인자(Argument)가 명령어를 덮어쓰는(Override) 방식에 있습니다.

1. CMD ["nginx", "-g", "daemon off;"] 단독 사용

기본 동작: 컨테이너 실행 시 nginx를 실행하며, -g daemon off;를 인자로 전달합니다.
명령어 덮어쓰기: docker run 명령어 뒤에 새로운 명령어를 입력하면, CMD에 정의된 전체 내용이 덮어씌워집니다.
실행 예시: docker run <이미지명> bash
- 결과: nginx 대신 bash 프로세스가 실행됩니다.

2. ENTRYPOINT ["nginx"] + CMD ["-g", "daemon off;"] 혼합 사용

기본 동작: ENTRYPOINT에 지정된 nginx를 항상 실행할 고정 실행 파일로 설정하고, CMD에 지정된 -g daemon off;를 기본 인자로 전달합니다. 아무 인자 없이 실행하면 1번 방식과 동일하게 작동합니다.
명령어 덮어쓰기: docker run 명령어 뒤에 새로운 인자를 입력하면, ENTRYPOINT는 그대로 유지되고 CMD에 지정된 인자 부분만 덮어씌워집니다.
실행 예시: docker run <이미지명> -t
- 결과: CMD 부분이 대체되어 nginx -t가 실행됩니다.
실행 예시 2: docker run <이미지명> bash
- 결과: nginx bash가 실행됩니다. (bash가 CMD를 덮어씀. 이는 nginx의 정상적인 실행 인자가 아니므로 오류가 발생합니다.)
- 이 방식에서 nginx가 아닌 bash를 실행하려면 docker run --entrypoint bash <이미지명>과 같이 --entrypoint 옵션을 명시적으로 변경해야 합니다.

요약

구분	실행 파일 고정 여부	docker run <이미지> [인자] 실행 시 덮어쓰기 대상	주 사용 목적
CMD 단독	고정 안 됨	실행 파일을 포함한 명령어 전체	실행 명령어를 유연하게 완전히 바꾸고 싶을 때
ENTRYPOINT + CMD	고정됨 (nginx)	CMD로 지정된 인자 부분만	메인 애플리케이션을 고정하고 전달할 옵션만 변경하고 싶을 때