기억의 파편들

로컬 LLM 기반 AI Code Reviewer 구축기 - 단순 코드 리뷰를 넘어 아키텍처 리뷰까지

추억을 백앤드하자 — Thu, 11 Jun 2026 09:37:05 +0900

로컬 LLM 기반 AI Code Reviewer 구축기 - 단순 코드 리뷰를 넘어 아키텍처 리뷰까지

들어가며

최근 AI 기반 코드 리뷰 도구들이 빠르게 발전하고 있다.

GitHub Copilot, Cursor, Claude Code 같은 도구들은 코드 작성뿐만 아니라 코드 리뷰까지 지원하고 있다.

하지만 실제 프로젝트에서 사용해보니 한 가지 아쉬운 점이 있었다.

"이 변경사항이 현재 프로젝트 아키텍처에 적합한가?"

라는 질문에는 의외로 답변 품질이 높지 않았다.

특히 프로젝트의 설계 원칙이나 레이어 규칙을 모르는 상태에서 PR Diff만 보고 리뷰하기 때문에 종종 일반론적인 피드백이 나왔다.

그래서 직접 GitHub Pull Request 이벤트를 기반으로 동작하는 AI Code Reviewer를 만들어보기로 했다.

목표는 단순했다.

PR 생성 시 자동 리뷰
코드 품질 리뷰
프로젝트 아키텍처 리뷰
로컬 LLM 기반 운영
GitHub Comment 자동 작성

시스템 아키텍처

전체 구조는 다음과 같다.

GitHub PR 생성

      │

      ▼

Webhook 수신

      │

      ▼

PR Diff 수집

      │

      ▼

Review Context 생성

      │
      ├── Diff
      ├── 변경 파일 전체 코드
      ├── AGENTS.md
      └── Package Tree

      ▼

Local LLM

      │
      ├── Code Review
      └── Architecture Review

      ▼

Review Merge

      ▼

GitHub Comment 작성

기술 스택은 다음과 같다.

Spring Boot 3
Spring AI
Ollama
Qwen3 30B
GitHub Webhook
GitHub REST API

왜 Diff만으로는 부족했을까?

처음 구현은 매우 단순했다.

GitHub Webhook으로 PR 생성 이벤트를 수신한 후 Diff를 그대로 LLM에게 전달했다.

PR Diff
   ↓
LLM
   ↓
Review

코드 리뷰 품질은 꽤 괜찮았다.

예를 들어

Null 처리 누락
예외 처리 부족
테스트 코드 필요
성능 문제

등은 잘 찾아냈다.

하지만 아키텍처 리뷰는 이상했다.

예를 들면

PullRequestReviewService

내부에 새로운 책임이 추가되었는데도

전반적으로 구조가 양호합니다.

같은 답변이 나왔다.

곰곰이 생각해보니 이유는 명확했다.

LLM은 현재 변경된 몇 줄만 보고 있었다.

즉,

이 클래스가 원래 어떤 역할인지
같은 패키지에 어떤 클래스가 있는지
프로젝트 설계 원칙이 무엇인지

전혀 모르는 상태였다.

코드 리뷰와 아키텍처 리뷰를 분리하다

이 문제를 해결하기 위해 리뷰를 두 종류로 나누었다.

Code Review

입력

PR Diff

검토

버그 가능성
예외 처리
성능
가독성
테스트 필요성

Architecture Review

입력

PR Diff
+ 변경 파일 전체 코드
+ Package Tree
+ AGENTS.md

검토

계층 분리
책임 분산
Service 비대화
외부 API 호출 위치
테스트 가능성
프로젝트 규칙 위반 여부

AGENTS.md 도입

가장 효과가 좋았던 개선은 AGENTS.md였다.

프로젝트 루트에 다음과 같은 규칙 파일을 추가했다.

# Architecture Rules

- Controller는 HTTP 처리만 담당한다.
- Service는 유스케이스 조율만 담당한다.
- 외부 API 호출은 Client 계층에 둔다.
- Prompt 생성은 PromptBuilder에 둔다.

리뷰 시 이 파일을 읽어서 프롬프트에 포함한다.

[PROJECT_RULES]
AGENTS.md

[PR_DIFF]
...

[CHANGED_FILE_SOURCE]
...

[PACKAGE_TREE]
...

이후부터는 단순한 코드 품질 리뷰가 아니라

"현재 프로젝트 규칙을 위반하는지"

를 판단하기 시작했다.

변경 파일 전체 코드 수집

아키텍처 리뷰에서 가장 중요한 컨텍스트였다.

Diff만 보면

+ private final GithubClient githubClient;

정도만 보인다.

하지만 전체 클래스를 보면

PullRequestReviewService
 ├─ Diff 조회
 ├─ LLM 호출
 ├─ Comment 작성
 └─ Prompt 생성

처럼 책임 과다 문제를 발견할 수 있다.

GitHub API를 이용해 변경 파일의 최신 코드를 수집하도록 개선했다.

프로젝트 규칙을 모르는 AI는 좋은 리뷰어가 아니다

이번 프로젝트에서 얻은 가장 큰 교훈이다.

AI는 똑똑하지만 프로젝트를 모른다.

프로젝트가

Controller
  ↓
Service
  ↓
Client

구조를 따르는지,

DDD를 사용하는지,

Hexagonal Architecture를 사용하는지,

알 수 없다.

그래서 좋은 AI 리뷰를 만들기 위해서는

"좋은 모델"

보다

"좋은 컨텍스트"

가 훨씬 중요했다.

앞으로 개선할 내용

현재는 다음 단계까지 구현했다.

GitHub Webhook
PR Diff 수집
Local LLM 연동
Code Review
Architecture Review
GitHub Comment 작성

앞으로는 다음 기능을 추가할 예정이다.

RAG 기반 프로젝트 컨텍스트 검색

PR Diff
   ↓
Vector Search
   ↓
관련 코드 검색
   ↓
LLM

테스트 결과 기반 리뷰

Gradle Test
    ↓
실패 테스트
    ↓
LLM

프로젝트 히스토리 기반 리뷰

과거 PR
과거 버그
과거 설계 결정

을 참고하는 리뷰 환경 구축

마치며

AI 코드 리뷰어를 만들면서 느낀 점은 하나였다.

AI 리뷰 품질은 모델 크기로 결정되지 않는다.

얼마나 많은 프로젝트 컨텍스트를 제공하느냐가 더 중요하다.

Diff만 보는 리뷰어와

프로젝트 규칙, 전체 코드, 패키지 구조를 이해하는 리뷰어는 전혀 다른 결과를 만든다.

이번 프로젝트는 단순히 LLM을 붙이는 것이 아니라,

"프로젝트를 이해하는 AI 리뷰어"를 만드는 과정이었다.

PolyCARP를 활용한 드론 Geofence/Area 공간 판단 구현기 - 좌표계, 경계선 그리고 수많은 삽질들

추억을 백앤드하자 — Thu, 4 Jun 2026 20:57:48 +0900

PolyCARP를 활용한 드론 Geofence/Area 공간 판단 구현기 - 좌표계, 경계선 그리고 수많은 삽질들

드론 안전 제어 시스템을 개발하면서 가장 먼저 구현해야 했던 기능 중 하나는 "공간 판단(Spatial Evaluation)" 이었다.

겉으로 보기에는 단순해 보인다.

드론이 비행 가능 구역 안에 있는가?
드론이 비행 금지 구역에 진입했는가?

하지만 실제 구현을 시작해보니 생각보다 훨씬 어려운 문제였다.

특히 실제 운영 환경에서는 단순히 내부/외부 여부만 알면 되는 것이 아니라

현재 비행 가능 구역(Area) 안에 있는가
비행 금지 구역(Geofence)에 진입했는가
경계선까지 얼마나 남았는가
위험 상태라면 어디로 복귀시켜야 하는가

까지 판단해야 했다.

이번 글에서는 NASA PolyCARP 기반의 공간 판단 기능을 구현하면서 겪었던 경험과 트러블슈팅 내용을 정리해보려고 한다.

왜 PolyCARP를 선택했는가

처음에는 단순히 위도/경도 범위를 비교하는 방법도 고려했다.

if(lat >= minLat &&
   lat <= maxLat &&
   lon >= minLon &&
   lon <= maxLon){
}

하지만 실제 비행 구역은 대부분 사각형이 아니다.

예를 들어 아래와 같은 다각형 형태일 수 있다.

          *
        *   *
      *       *
    *           *
      *       *
        *   *
          *

이 경우 min/max 방식으로는 정확한 판단이 불가능하다.

결국 다각형 기반 공간 판단이 필요했고 PolyCARP의 Polygon Geometry 개념을 활용하게 되었다.

첫 번째 문제 - 위경도는 생각보다 계산하기 어렵다

처음에는 위도/경도 좌표만으로 모든 계산을 시도했다.

하지만 곧 문제가 발생했다.

위도 0.0001 차이
경도 0.0001 차이

가 항상 같은 거리가 아니다.

특히 경도는 위도에 따라 실제 길이가 달라진다.

결국 모든 계산을 Local 좌표계로 변환하기로 했다.

x = (lon - refLon)
      * 111320
      * cos(refLat)

y = (lat - refLat)
      * 111320

변환 후에는

x = 동서 방향 거리(m)
y = 남북 방향 거리(m)

로 표현할 수 있게 되었다.

이후 Polygon 포함 여부, 경계 거리 계산, 복귀 지점 계산이 훨씬 단순해졌다.

두 번째 문제 - GeoJSON 좌표 순서 함정

구현 후 이상한 현상이 발생했다.

분명 Geofence를 적재했는데 조회 결과가 항상 0건이었다.

디버깅해보니 Spatial Index가 비어 있었다.

원인을 찾아보니 GeoJSON 좌표 순서를 잘못 해석하고 있었다.

GeoJSON은

[
  127.123,
  37.123
]

형태로 저장된다.

즉

[lon, lat]

순서이다.

하지만 나는 무의식적으로

double refLat = coordinate[0];
double refLon = coordinate[1];

로 작성해버렸다.

결과적으로

위도 = 127
경도 = 37

이라는 말도 안 되는 좌표가 생성되었다.

Spatial Index의 Bounding Box도 전부 깨졌고 Geofence 검색 결과는 항상 0건이 되었다.

수정 후 정상적으로 동작했다.

double refLon = coordinate[0];
double refLat = coordinate[1];

단순한 실수였지만 실제로 하루 가까이 원인을 찾지 못했던 버그였다.

세 번째 문제 - Polygon 내부 판정 버그

어느 날 테스트 중 이상한 결과가 나왔다.

Geofence 밖에 있는 드론이 내부로 판정되고 있었다.

원인을 추적해보니 Polygon 마지막 점을 시작점과 동일하게 넣고 있었다.

A
B
C
D
A

Polygon을 닫기 위해 마지막 점을 중복 추가했던 것이다.

문제는 마지막 선분이

A -> A

가 되면서 길이가 0인 선분이 생성된다는 점이었다.

이 선분 때문에 Boundary Projection 계산이 꼬였고 contains() 결과까지 잘못 나오고 있었다.

이후에는

Polygon은 중복 없이 저장

하거나

if(segmentLength == 0){
    continue;
}

방어 코드를 추가해서 해결했다.

네 번째 문제 - 고도 단위(ft / m)

이 버그는 찾는 데 정말 오래 걸렸다.

수평 위치는 분명 Area 내부였다.

그런데 수직 판정이 계속 실패했다.

Position.makeLatLonAlt(
    lat,
    lon,
    100
);

고도를 100m로 넣었다고 생각했는데 실제로는 아니었다.

NASA 라이브러리의 기본 단위는 feet였다.

즉

100ft
≈ 30m

로 해석되고 있었던 것이다.

이 때문에

현재 고도 = 30m
Area 최소고도 = 100m

로 판단되어 계속 위험 상태가 발생했다.

결국 모든 Position 생성부를 아래처럼 수정했다.

Position.makeLatLonAlt(
    lat,
    "deg",
    lon,
    "deg",
    altitude,
    "m"
);

이후 수직 판단이 정상적으로 동작했다.

다섯 번째 문제 - Geofence와 Area는 복귀 방향이 반대다

초기 구현에서는 Geofence와 Area 모두 같은 복귀 알고리즘을 사용했다.

그런데 테스트를 해보니 이상했다.

Area 밖에 있는 드론이 더 멀리 도망가고 있었다.

곰곰이 생각해보니 두 개념은 완전히 달랐다.

Geofence는

위험구역

이다.

따라서 내부에 있으면 밖으로 나가야 한다.

반면 Area는

허용구역

이다.

따라서 외부에 있으면 안으로 들어와야 한다.

결국 복귀 알고리즘을 분리했다.

Geofence

현재위치
→ 경계점
→ 경계 밖

Area

현재위치
→ 경계점
→ 중심 방향 내부

이렇게 방향 자체가 반대였다.

최종 구조

현재 공간 판단 구조는 다음과 같다.

TrackPosition
      ↓
Local Projection
      ↓
Polygon Contains
      ↓
Boundary Distance
      ↓
Area / Geofence Evaluation
      ↓
Recovery Point Calculation
      ↓
Alert & Avoidance Command

평가 로직과 회피 로직을 분리하면서 테스트도 훨씬 쉬워졌다.

마무리

처음에는 "다각형 안에 있는지만 확인하면 되겠지"라고 생각했다.

하지만 실제 구현 과정에서는

좌표계 변환
GeoJSON 표준
단위(ft/m)
Polygon Geometry
경계 거리 계산
복귀 지점 계산

등 예상보다 훨씬 많은 요소를 고려해야 했다.

특히 이번 프로젝트를 통해 배운 점은 공간 판단은 단순한 좌표 계산이 아니라는 것이다.

결국 중요한 것은

"현재 어디에 있는가?"

보다

"얼마나 위험한가?"

그리고

"어디로 이동해야 안전한가?"

를 판단하는 것이라는 사실을 다시 한번 느낄 수 있었다.

드론 안전 제어 시스템을 설계하며 고민했던 것들

추억을 백앤드하자 — Thu, 4 Jun 2026 20:51:17 +0900

드론 관제 시스템을 개발하면서 가장 먼저 들었던 생각은 생각보다 "위치 판단"이 쉬운 문제가 아니라는 것이었다.

처음에는 단순히 드론 위치를 받아서 위험 여부를 판단하면 될 것이라고 생각했다.

현재 위치 수신
→ 위험 판단
→ 알림 발행

하지만 실제로 설계를 시작해보니 고려해야 할 요소가 예상보다 훨씬 많았다.

예를 들어 하나의 드론 위치 정보가 들어오더라도 동시에 다음과 같은 평가가 필요했다.

다른 드론과 충돌 위험은 없는가
비행금지구역(Geofence)을 침범했는가
허용 비행구역(Area)을 이탈했는가
지정 경로(Route)를 벗어났는가

더 큰 문제는 이 모든 판단 결과가 서로 다른 회피 전략을 요구한다는 점이었다.

충돌 위험은 즉시 회피가 필요하지만, 경로 이탈은 상대적으로 우선순위가 낮을 수 있다.

단순히 모든 위험 상황에 대해 명령을 생성하면 오히려 서로 충돌하는 회피 명령이 발생할 수 있었다.

첫 번째 고민: 모든 판단을 하나의 서비스에서 처리할 것인가

프로젝트 초기에 가장 단순하게 생각한 구조는 다음과 같았다.

public void evaluateSafety(TrackPosition position) {
    evaluateCollision(position);
    evaluateGeofence(position);
    evaluateArea(position);
    evaluateRoute(position);

    publishAlert();
    registerCommand();
}

작동은 가능하다.

하지만 기능이 늘어날수록 문제가 발생하기 시작했다.

충돌 로직을 수정하려고 열어본 클래스 안에

Geofence 로직
Route 로직
JMS 발행 로직

까지 모두 섞여 있었다.

결국 특정 도메인의 변경이 전체 시스템에 영향을 주기 시작했다.

도메인별로 책임을 분리하기

이 문제를 해결하기 위해 각 영역을 독립적인 도메인으로 분리했다.

collision
geofence
area
route

그리고 모든 도메인에 동일한 패턴을 적용했다.

Service
Evaluator
ResultHandler

Evaluator는 오직 판단만 수행한다.

RouteCheckResult result =
        routeEvaluator.evaluate(position, route);

이 단계에서는

알림 발행
회피 명령 저장
이벤트 처리

를 하지 않는다.

오직 "위험한가?"만 판단한다.

판단과 부수효과를 분리하기

프로젝트를 진행하면서 가장 중요하다고 느꼈던 부분은 판단 로직과 부수효과를 분리하는 것이었다.

예를 들어 Route 평가 결과가 DANGER라고 가정하자.

Evaluator의 역할은 여기까지다.

RouteCheckResult result =
        RouteCheckResult.builder()
                .routeDeviationLevel(DANGER)
                .build();

그 이후 알림 발행이나 회피 명령 생성은 ResultHandler에게 위임한다.

public void handle(
        RouteCheckResult result,
        TrackPosition position,
        RouteModel route
) {
    routeAlertPublisher.publishIfNeeded(result);
    routeAvoidanceCommandService.register(
            position,
            route,
            result
    );
}

덕분에 위험 판단 로직을 테스트할 때는 MQ나 저장소를 신경 쓸 필요가 없어졌다.

MQ 장애가 안전 판단을 막아서는 안 된다

실시간 안전 시스템을 설계하면서 또 하나 중요하게 생각한 부분은 장애 격리였다.

만약 MQ 발행 실패 때문에 안전 판단 자체가 실패한다면 심각한 문제가 될 수 있다.

그래서 알림 발행은 별도의 이벤트 구조로 분리했다.

Evaluator
 ↓
ResultHandler
 ↓
ApplicationEventPublisher
 ↓
@Async EventHandler
 ↓
MQ Publish

이 구조를 적용한 이후에는 MQ 장애가 발생하더라도 안전 판단 자체는 정상적으로 수행된다.

실시간 시스템에서는 "기능 수행"과 "외부 연동"을 분리하는 것이 생각보다 중요하다는 것을 다시 한 번 느꼈다.

가장 어려웠던 부분은 우선순위였다

충돌 위험, Geofence 침범, 경로 이탈이 동시에 발생하면 어떤 명령을 수행해야 할까?

처음에는 각 도메인이 독립적으로 회피 명령을 생성하도록 구현했다.

하지만 실제 테스트를 해보니 서로 다른 명령이 동시에 생성되는 문제가 발생했다.

충돌 회피
→ 상승

Geofence 회피
→ 하강

결국 최종 단계에서 하나의 명령만 선택할 수 있는 Safety Layer를 추가했다.

Collision
Geofence
Area
Route
 ↓
Safety Layer
 ↓
Final Command

그리고 우선순위를 명확하게 정의했다.

충돌 위험
Geofence 침범
Area 이탈
Route 이탈

이후부터는 각 도메인이 독립적으로 판단하더라도 최종 결과는 일관성을 유지할 수 있었다.

마무리

이번 프로젝트를 진행하면서 느낀 점은 드론 안전 제어 시스템은 단순히 좌표를 계산하는 문제가 아니라는 것이다.

실제로는

공간 판단
위험도 평가
회피 전략 생성
이벤트 처리
장애 격리
우선순위 결정

등 다양한 문제를 함께 해결해야 했다.

특히 구현보다 어려웠던 것은 "어떤 책임을 어디에 둘 것인가"에 대한 설계였다.

결국 좋은 안전 시스템은 복잡한 알고리즘보다도 각 구성 요소가 자신의 역할만 수행하도록 만드는 구조에서 시작된다고 생각한다.

쿠버네티스 정리2

추억을 백앤드하자 — Mon, 23 Mar 2026 09:58:31 +0900

Controller

Auto Healing, Software Update, Auto Scaling, Job 의 기능들을 제공한다.(- 표시는 추후 중급과정에서)

Controller 옵션

Template

Controller와 Pod는 Service와 Pod 처럼 label과 selector로 연결된다.
selector를 선언하고 template에 label을 선언한다. 버전 변경시에는 기존 pod만 죽이면 controller는 다시 되살리려는 특성을 갖고있기 때문에 그 특성을 이용해서 새로운 버전을 올리기 용이하다.

Replicas

replicas 숫자만큼 pod의 개수가 관리된다. replicas가 3개이면 pod도 3개로 scale out하여 만들어준다
pod에 대한 내용이 없으면 replicas가 동작하지 않게된다. pod와 controller를 따로 만들지 않고 한번에 만들 수 있는데 templete에 선언된 pod의 내용을 기반으로 연결되어 사용된다.

Selector

replication의 selector는 같은 정보를 갖고 있는 pod의 label을 보고 pod와 연결해주고 정보가 하나라도 일치하지 않으면 연결되지 않는다.
반면 replicaSet에는 selector에 matchLabels 속성을 사용하여 같은 정보(key와 value값이 같아야한다)를 갖고 있는 pod들과 연결되며, matchExpressions 속성을 사용하여 value는 다르지만 key값이 같은 정보들을 갖고 있는 pod들을 연결할 수도 있다.
- matchExpressions 의 value를 담당하는 operator 값에는 4가지가 있다.
- Exists: 키값이 같은 pod만 연결
- DoesNotExist:: 키값이 다른 pod만 연결
- In: 키값이 같고 value가 하나라도 포함된 pod와 연결
- NotIn: 키값이 같고 value가 하나라도 포함되지 않은 pod와 연결

예제

apiVersion: apps/v1
kind: ReplicaSet
metadata:
  name: replica2
spec:
  replicas: 1
  selector:
    matchLabels:
      type: web
      ver: v1
    matchExpressions:
    - {key: type, operator: In, values: [web]}
    - {key: ver, operator: Exists}
  template:
    metadata:
      labels:
        type: web
        ver: v1
        location: dev
    spec:
      containers:
      - name: container
        image: kubetm/app:v1
      terminationGracePeriodSeconds: 0

Deployment

ReCreate

Recreate로 Deployment 배포시 먼저 기존 버전들이 다운되고 새로운 버전이 생성된다.
다운 되는 순간 Downtime이 발생하기 때문에 일시적인 서비스 정지가 가능한 서비스에만 사용해야한다.

예제

deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: deployment-1
spec:
  selector:
    matchLabels:
      type: app
  replicas: 2
  strategy:
    type: Recreate
  revisionHistoryLimit: 1
  template:
    metadata:
      labels:
        type: app
    spec:
      containers:
      - name: container
        image: kubetm/app:v1
      terminationGracePeriodSeconds: 10

service

apiVersion: v1
kind: Service
metadata:
  name: svc-1
spec:
  selector:
    type: app
  ports:
  - port: 8080
    protocol: TCP
    targetPort: 8080

신규버전(v2)으로 업그레이드시

# kubectl set image deployment <deployment-name> <container-name>=<image>
$ kubectl set image deployment deployment-1 container=kubetm/app:v2

이전 버전으로 롤백시

# 특정 버전으로 롤백하기
$ kubectl rollout undo deployment deployment-1 --to-revision=1
# 롤백 버전 리스트 확인
$ kubectl rollout history deployment deployment-1

버전 업그레이드 확인해보기

$ while true; do curl <service-ip>:8080/version; sleep 1; done

Rolling Update

rolling update로 배포시 먼저 신규 버전이 1개씩 생성되며 그에 따른 추가적인 자원사용량이 발생한다.
신규 버전이 다 생성되었으면 자동으로 기존 버전들을 삭제한다.
배포 과정에서 기존버전과 신규버전이 공존하는 시간이 있는데 그사이에 사용자들이 서로 다르게 버전을 사용하게 될 수도 있다.
추가적인 자원 사용량이 발생하지만 Downtime이 없다는게 장점이다

예제

deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: deployment-2
spec:
  selector:
    matchLabels:
      type: app
  replicas: 2
  strategy:
    type: RollingUpdate
  minReadySeconds: 10
  template:
    metadata:
      labels:
        type: app
    spec:
      containers:
      - name: container
        image: kubetm/app:v1
      terminationGracePeriodSeconds: 0

service

apiVersion: v1
kind: Service
metadata:
  name: svc-2
spec:
  selector:
    type: app
  ports:
  - port: 8080
    protocol: TCP
    targetPort: 8080

업데이트시 기존 deployment의 내부 이미지 버전 수정(kubetm/app:v1 -> kubetm/app:v2)

apiVersion: apps/v1
kind: Deployment
metadata:
  name: deployment-2
spec:
  selector:
    matchLabels:
      type: app
  replicas: 2
  strategy:
    type: RollingUpdate
  minReadySeconds: 10
  template:
    metadata:
      labels:
        type: app
    spec:
      containers:
      - name: container
        image: kubetm/app:v2
      terminationGracePeriodSeconds: 0

Blue/Green

Deployment 자체기능으로도 있지만 Controller 를 사용하여 이번편을 설명한다.
배포하는 Pod의 라벨을 분리하여 배포한다. Service에는 타겟 라벨만 변경해주면 된다.
순간적으로 변경이 되기 때문에 Downtime이 없다.
신규버전 배포시에 문제가 있다면 Service의 라벨만 이전버전으로 변경해주면 되기 때문에 문제시 롤백이 쉽다는 장점이 있다.
최종 배포후에 문제가 없을때만 이전 버전의 Pod를 삭제해주면 된다. 다만 그전까지 이전버전,신규버전의 자원 사용량이 발생하기 때문에 이 부분만 단점이다.
실무에서 자주 사용하는 방식이다.

예제

ReplicaSet

apiVersion: apps/v1
kind: ReplicaSet
metadata:
  name: replica1
spec:
  replicas: 2
  selector:
    matchLabels:
      ver: v1
  template:
    metadata:
      labels:
        ver: v1
    spec:
      containers:
      - name: container
        image: kubetm/app:v1
      terminationGracePeriodSeconds: 0

Service

apiVersion: v1
kind: Service
metadata:
  name: svc-3
spec:
  selector:
    ver: v1
  ports:
  - port: 8080
    protocol: TCP
    targetPort: 8080

Update할 새 ReplicaSet(replica2) 생성 후 Service(svc-3)의 Selector를 변경하여 트래픽 변경

apiVersion: apps/v1
kind: ReplicaSet
metadata:
  name: replica2
spec:
  replicas: 2
  selector:
    matchLabels:
      ver: v2
  template:
    metadata:
      labels:
        ver: v2
    spec:
      containers:
      - name: container
        image: kubetm/app:v2
      terminationGracePeriodSeconds: 0

Service의 Selector 수정

apiVersion: v1
kind: Service
metadata:
  name: svc-3
spec:
  selector:
    ver: v2
  ports:
  - port: 8080
    protocol: TCP
    targetPort: 8080

Canary

카나리아는 1초에 17번 숨을 쉬는 새다. 공기중 유해한 물질이 있으면 빨리죽는다. 그래서 광산안에 일산화탄소를 감지하는 역할로 많이 사용했다고 한다. 위험을 감지하는 느낌쓰
방법1. Pod의 type,version으로 배포를 관리한다. 신규 버전 배포 문제가 될시 v2(신규버전) controller에 replicas만 0으로 만들면 된다. 배포를 해두면 누군가는 v1로 누군가는 v2로 서비스를 이용하게된다. 해당 방식은 불특정 다수를 테스트할때 사용하는 방식이다.

방법2. 기존버전과 신규버전 각각 Service를 만들고, Ingress Controller에서 url로 패킷을 분리하여 전달해준다
이렇게 특정 타겟을 위하여 테스트및 배포가 가능하게 된다.(ex) 해외 사용자/국내 사용자 접속시 다른 서비스로 대응)

Blue/Green 방식과 마찬가지로 Downtime은 없지만 자원 사용량이 2배가 될 수 있다.

Controller - DaemonSet, Job ,CronJob

목적

DaemonSet

노드의 자원 여부와 상관 없이 모든 노드에 pod가 1개씩 생성되는 특징이 있다. 만약 노드가 10개면 각 노드에 pod1개씩 총 pod 10개가 생성되는 것이다.
성능 수집 에이전트(prometheus), 로그 수집(fluentd), 스토리지(GlusterFS) 에 주로 사용된다.

Job, CronJob

Pod들이 Node1에서 돌아갈때 Node1이 down되었을때 controller에 의해서 만들어진 pod들은 장애를 감지하여 Node2에 pod를 재생성하는 등으로 장애 대응이 가능하게 된다.(ReplicaSet, Job)
ReplicaSet 에서 Recreate: pod를 다시 만들어주기때문에 pod의 ip나 이름이 변경된다, Restart: pod는 그대로 있고 pod 안에 컨테이너만 재기동 시켜준다
반면 Job으로 만들어진 pod는 프로세스가 일을 하지 않으면 pod가 종료(자원을 사용하지 않는 상태로 멈춤, 없어지는것은 아님)
CronJob들은 이런 Job들을 주기적으로 생성하는 역할을 한다.(특정 시간에 반복적으로 사용할 목적으로 사용, db백업, 주기적 업데이트, 메일/sms 메시지 발송)

특징

DaemonSet

selector와 template으로 모든 node에 Pod를 만든다.
nodeSelector를 통해 os를 지정하여 특정 os에서 돌아가는 pod만 연결할 수도 있다. 지정하지 않으면 모든 node에 생긴다
아래와 같이 NodePort 타입의 Service를 만들때 extarnalTrafficPolicy: Local 옵션을 설정하면 특정 노드의 nodePort를 외부에서 접근했을때 Service로 연결이 된다. 이와 같이 DaemonSet에서도 hostPort 옵션을 사용하면 외부에서 hostPort로 접근하면 containerPort 를 통해서 각 노드의 pod로 연결해준다.

예제1(hostPort)

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: daemonset-1
spec:
  selector:
    matchLabels:
      type: app
  template:
    metadata:
      labels:
        type: app
    spec:
      containers:
      - name: container
        image: kubetm/app
        ports:
        - containerPort: 8080
          hostPort: 18080

예제2(NodeSelector)

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: daemonset-2
spec:
  selector:
    matchLabels:
      type: app
  template:
    metadata:
      labels:
        type: app
    spec:
      nodeSelector:
        os: centos
      containers:
      - name: container
        image: kubetm/app:v1
        ports:
        - containerPort: 8080

Job

template에는 특정 작업만 하고 종료하는 pod들만 담아둔다. selector는 직접 만들지 않아도 Job이 만들어준다.
completions 옵션을 사용하면 pod를 completions 개수 만들고 모두 작업을 완료해야 Job이 종료된다.
parallelism 옵션을 사용하면 pod가 생성시 동시에 parallelism 개수만큼 생성된다.
activeDeadlineSeconds 옵션을 사용하면 설정 시간 후에 모든 Job은 종료된다. 특정 작업에 행이 걸릴꺼 같을때 자원을 릴리즈 하기위해 사용한다.
template에서 pod를 만들때 restartPolicy 옵션을 필수값이다.(Never / onFailure) 해당 옵션은 추후 Pod 파트에서 자세히 설명

예제1

apiVersion: batch/v1
kind: Job
metadata:
  name: job-1
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
      - name: container
        image: kubetm/init
        command: ["sh", "-c", "echo 'job start';sleep 20; echo 'job end'"]
      terminationGracePeriodSeconds: 0

예제2

apiVersion: batch/v1
kind: Job
metadata:
  name: job-2
spec:
  completions: 6
  parallelism: 2
  activeDeadlineSeconds: 40
  template:
    spec:
      restartPolicy: Never
      containers:
      - name: container
        image: kubetm/init
        command: ["sh", "-c", "echo 'job start';sleep 20; echo 'job end'"]
      terminationGracePeriodSeconds: 0

CronJob

jobTemplate을 통해 job을 만들어준다. schedule 통해 주기적으로 job을 생성한다.
concurrencyPolicy 라는 옵션이 있는데 설정하지 않으면 Allow값이 default로 적용된다.
Allow: schedule 주기마다 pod가 생성된다 , Forbid: schedule 주기마다 pod가 생성되지만 기존 Job이 안끝났으면 생성을 skip하고, 기존 Job이 종료되었으면 생성한다, Replace: 기존 Pod를 삭제하고 새로운 Job과 Pod가 주기적으로 생성된다.

예제

apiVersion: batch/v1
kind: CronJob
metadata:
  name: cron-job
spec:
  schedule: "*/1 * * * *"
  jobTemplate:
    spec:
      template:
        spec:
          restartPolicy: Never
          containers:
          - name: container
            image: kubetm/init
            command: ["sh", "-c", "echo 'job start';sleep 20; echo 'job end'"]
          terminationGracePeriodSeconds: 0

예제2(concurrencyPolicy 옵션)

apiVersion: batch/v1
kind: CronJob
metadata:
  name: cron-job-2
spec:
  schedule: "20,21,22 * * * *"
  concurrencyPolicy: Forbid
  jobTemplate:
    spec:
      template:
        spec:
          restartPolicy: Never
          containers:
          - name: container
            image: kubetm/init
            command: ["sh", "-c", "echo 'job start';sleep 140; echo 'job end'"]
          terminationGracePeriodSeconds: 0

demonset, job, cronjob, node 삭제 명령어들

$ kubectl delete ds daemonset-1 daemonset-2
$ kubectl delete job job-1 job-2
$ kubectl delete cronjob cron-job cron-job-2 cron-job-3

// Node에 라벨 삭제
$ kubectl label nodes k8s-worker1 os-
$ kubectl label nodes k8s-worker2 os-

쿠버네티스 정리1

추억을 백앤드하자 — Mon, 23 Mar 2026 09:54:01 +0900

쿠버네티스

서비스의 격리를 Docker로 했지만, 엄청 많은 서비스들을 일일이 배포하고 운영하는 역할이 필요하게 되면서 쿠버네티스가 등장하였다.

쿠버네티스 클러스터를 운영하는 운영자(Admin)
자신의 서비스를 배포하려는 사용자(User)

Overview

namespace

쿠버네티스 객체들을 독립된 공간으로 분리

Pod

쿠버네티스의 배포 최소 단위

Service

Pod 들을 외부와 연결시켜줌

ResourceQuota/LimitRange

namespace에서 사용할 수 있는 자원의 양을 한정(pod의 개수, cpu, memory 제한등..)

ConfigMap / Secret

Pod의 환경변수

Replication Controller, ReplicaSet

Pod 헬스체크 및 되살리기, Pod scale in out

Pod

파일 읽기를 예로 들어보면 cpu공유시에 여러 파일을 동시에 읽는다고 파일 읽는 속도가 느려질뿐 시스템이 종료되지는 않는다(cpu)

그러나 메모리 공유시에는 잘못된 메모리가 참조되었습니다 라고 하면서 시스템이 종료된다.

이런 특성으로 cpu 초과시에는 Pod가 종료되지 않지만 메모리 초과시 Pod가 종료된다.

Service

ClusterIP

ClusterIp는 클러스터 내에서만 유효한 IP 이다
Pod의 아이피는 Pod가 on/off 할때마다 변하지만 Service는 변하지 않는다.
그래서 Pod는 항상 Service로부터 접근해야한다.
주 사용처: 인가된 사용자, 내부 대시보드, Pod의 서비스 상태 디버깅

NodePort

NodePort가 열리는 위치

[Client]
   ↓
<Node IP>:30080   ← 여기!
   ↓
kube-proxy (iptables/ipvs)
   ↓
Service (ClusterIP)
   ↓
Pod

그래서 ip도 호스트의 ip에 포트를 연다.

모든 노드에 같은 포트 할당 가능
1번 노드에서 온 데이터라도 2번 노드로 전송 가능
externalTrafficPolicy: Local 옵션을 적용하면 특정 노드 포트의 ip로 접근하는 트래픽은 service가 해당 노드위에 올려져있는 Pod에게만 데이터를 전달한다.
주 사용처: 내부망 연결, 데모나 임시 연결용, 내부 환경에서 시스템 개발을 하다가 외부의 간단한 데모를 보여줄때 종종 네트워크 중계기에 포트포워딩을 해서 외부에서 내부시스템에 연결할때, 이럴때 NodePort를 잠시 뚫어두고 사용한다.

Load Balancer

주 사용처: 외부 시스템 노출용도

Load Balancer 타입으로 만들면 따로 별도의 외부접속 ip 플러그인이 설치되어 있어야만 Ip가 자동으로 할당된다.(ex. GCP, AWS..)

Kubernetes:

“LoadBalancer가 필요하군요. 누군가 외부 LB 만들어 주세요 ”

실제 LB 생성 & IP 할당:
클라우드 제공자(GCP, AWS, Azure 등) 또는 LB 컨트롤러가 담당

폐쇠망에서는?

1️⃣ LoadBalancer 타입 생성은 가능

$ kubectl expose deployment my-app \
  --type=LoadBalancer \
  --port=80

하지만 상태를 보면:

kubectl get svc
NAME       TYPE           CLUSTER-IP     EXTERNAL-IP   PORT(S)
my-app     LoadBalancer   10.96.12.34    <pending>     80:31234/TCP

EXTERNAL-IP가 <pending>에서 절대 안 바뀜

왜냐면: 외부 IP를 할당해 줄 LB 컨트롤러가 없기 때문

로컬 / 폐쇄망에서의 현실적인 대안

Ingress + Ingress Controller

NGINX Ingress Controller
Traefik
HAProxy

구성 예시

[Client]
   ↓ 80/443
[Ingress Controller Service]  (NodePort or LoadBalancer)
   ↓
[Ingress Controller Pod]      ← NGINX 실행 중
   ↓ (Ingress 규칙 적용)
[Service (ClusterIP)]
   ↓
[Pod]

Ingress Controller = 실제 HTTP 서버 (NGINX)
Ingress = 그 서버에 먹이는 라우팅 설정

Controller Pod (Deployment)

apiVersion: apps/v1
kind: Deployment
metadata:
  name: ingress-nginx-controller
  namespace: ingress-nginx
spec:
  replicas: 1
  selector:
    matchLabels:
      app: ingress-nginx
  template:
    metadata:
      labels:
        app: ingress-nginx
    spec:
      containers:
      - name: controller
        image: registry.k8s.io/ingress-nginx/controller:v1.9.5
        args:
          - /nginx-ingress-controller
        ports:
          - name: http
            containerPort: 80
          - name: https
            containerPort: 443

✔️ 이 Pod 안에서 NGINX가 실행 중
✔️ Ingress 리소스를 감시(watch)함

Controller Service (외부 노출)

apiVersion: v1
kind: Service
metadata:
  name: ingress-nginx
  namespace: ingress-nginx
spec:
  type: NodePort   # 로컬/폐쇄망에서는 보통 NodePort
  selector:
    app: ingress-nginx
  ports:
    - name: http
      port: 80
      nodePort: 30080
    - name: https
      port: 443
      nodePort: 30443

(클라우드면 type: LoadBalancer로 바뀜)

Ingress 리소스 (라우팅 규칙)

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app-ingress
spec:
  rules:
  - host: app.local
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: frontend
            port:
              number: 80

app.local로 오면 frontend Service로 전달

궁금증: nginx 설정 파일이 어디에도 마운트 되지 않았는데 어떻게 로드밸런싱을 해주지?

Pod가 여러 개면, Ingress Controller(NGINX)가 Service 뒤에 있는 Pod들로 자동 로드밸런싱을 한다.

레벨	역할
Ingress Controller (NGINX)	L7 로드밸런싱 (HTTP)
Service (kube-proxy)	L4 로드밸런싱 (TCP)
Pod	실제 처리

Volume

emptyDir

컨테이너들 끼리 볼륨을 공유하기 위한 목적
Pod 안에서 생성되기 때문에 일시적인 사용목적에 의한 데이터 용도로만 사용되어야 한다
Pod가 죽으면 emptyDIr 볼륨의 데이터로 사라진다

apiVersion: v1
kind: Pod
metadata:
  name: pod-volume-1
spec:
  containers:
  - name: container1
    image: kubetm/init
    volumeMounts:
    - name: empty-dir
      mountPath: /mount1
  - name: container2
    image: kubetm/init
    volumeMounts:
    - name: empty-dir
      mountPath: /mount2
  volumes:
  - name : empty-dir
    emptyDir: {}

hostPath

Pod들이 개별적으로 path를 공유하기 때문에 Pod가 죽어도 데이터가 사라지지 않는다.
만약 Pod2가 죽고 되살아났을때 기존 Node1에서 Node2로 재생성되었다면 Pod2는 기존 Node1의 path를 자동으로 읽지 못한다.
때문에 노드가 추가될때마다 리눅스 시스템 별도의 마운트 기술을 이용하여 Node2에도 자동으로 구성해주어야 한다. 이것은 쿠버네티스가 자동으로 해주는것이 아닌 직접 사람이 개입해줘야 함으로 권장되지는 않는 방법이다.
참고로 hostPath 정보는 Pod가 만들어지기 전에 미리 만들어져있어야 한다.

아래와 같이 생성해두고, 다음 새로운 Pod를 만들때 노드선언부를 제외하고 만들게되면 새로운 노드가 만들어지게 되면서

기존 노드에 생성되어 있던 hostPath의 설정값은 새로운 Pod에서는 존재하지 않게 된다.

apiVersion: v1
kind: Pod
metadata:
  name: pod-volume-3
###### 노드선언 ######  
spec:
  nodeSelector:
    kubernetes.io/hostname: k8s-worker1
#####################  
  containers:
  - name: container
    image: kubetm/init
    volumeMounts:
    - name: host-path
      mountPath: /mount1
  volumes:
  - name : host-path
    hostPath:
      path: /node-v
      type: DirectoryOrCreate

PVC/PV

apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv-01
spec:
  capacity:
    storage: 1G
  accessModes:
  - ReadWriteOnce
  local:
    path: /node-v
  nodeAffinity:
    required:
      nodeSelectorTerms:
      - matchExpressions:
        - {key: kubernetes.io/hostname, operator: In, values: [k8s-worker1]}

values: [k8s-worker1]} 만 주의깊게 확인하면 된다. worker1에 저장된다는 의미다

출처:https://biz.inflearn.com/course/%EC%BF%A0%EB%B2%84%EB%84%A4%ED%8B%B0%EC%8A%A4-%EA%B8%B0%EC%B4%88/dashboard?cid=324190

[K8s] 쿠버네티스 사설 레지스트리 구축 및 x509: certificate signed by unknown authority 에러 해결 가이드

추억을 백앤드하자 — Fri, 6 Mar 2026 12:21:56 +0900

[K8s] 쿠버네티스 사설 레지스트리 구축 및 x509: certificate signed by unknown authority 에러 해결 가이드

쿠버네티스(Kubernetes) 환경에서 보안상의 이유로 사설 레지스트리(Private Registry)를 운영하다 보면 반드시 마주치는 문제가 있습니다. 바로 HTTPS/TLS 인증서 관련 에러입니다.

특히 ctr 명령어로는 이미지가 잘 당겨지는데, 정작 kubectl로 배포하면 ImagePullBackOff와 함께 "x509: certificate signed by unknown authority" 에러가 발생하는 상황에서의 완벽한 해결법을 정리합니다.

사설 TLS 인증서 생성 (OpenSSL)

사설 레지스트리를 HTTPS로 운영하기 위해서는 자체 서명 인증서(Self-Signed Certificate)가 필요합니다. 이때 주의할 점은 IP 주소를 인증서에 명시(SAN 설정)해야 한다는 것입니다.

인증서 생성 명령어

마스터 노드에서 아래 명령어를 실행하여 10년(3650일) 유효한 인증서를 생성합니다.

Bash

openssl req -newkey rsa:4096 -nodes -sha256 -keyout domain.key \
-x509 -days 3650 -out domain.crt \
-subj "/CN=10.202.2.129" \
-addext "subjectAltName = IP:10.202.2.129"

왜 `subjectAltName`이 중요한가요?

최근의 컨테이너 런타임(containerd, Docker 등)은 보안상의 이유로 일반적인 Common Name(CN)만으로는 인증을 통과시키지 않습니다. subjectAltName (SAN) 필드에 레지스트리의 IP 주소가 정확히 명시되어야만 x509: certificate signed by unknown authority 에러를 방지할 수 있습니다.

쿠버네티스 Secret 등록

생성된 domain.crt와 domain.key를 쿠버네티스 클러스터에서 사용할 수 있도록 Secret 객체로 등록합니다.

Bash

# 기존 시크릿이 있다면 삭제 후 재생성
kubectl delete secret registry-tls --ignore-not-found

# TLS 타입의 시크릿 생성
kubectl create secret tls registry-tls \
  --cert=domain.crt \
  --key=domain.key

1. 사설 레지스트리(Private Registry) 배포 설정

사설 레지스트리는 내부망에서 이미지를 안전하게 관리하기 위해 필수적입니다. 아래는 TLS 인증서를 적용한 registry.yaml 예시입니다.

Registry Deployment & Service YAML

YAML

apiVersion: apps/v1
kind: Deployment
metadata:
  name: private-registry
spec:
  replicas: 1
  selector:
    matchLabels:
      app: registry
  template:
    metadata:
      labels:
        app: registry
    spec:
      dnsPolicy: ClusterFirstWithHostNet
      containers:
      - name: registry
        image: registry:2
        env:
        - name: REGISTRY_HTTP_ADDR
          value: "0.0.0.0:30500"
        - name: REGISTRY_HTTP_TLS_CERTIFICATE
          value: /certs/tls.crt
        - name: REGISTRY_HTTP_TLS_KEY
          value: /certs/tls.key
        ports:
        - containerPort: 5000
        volumeMounts:
        - name: storage
          mountPath: /var/lib/registry
        - name: cert-vol
          mountPath: /certs
          readOnly: true
      volumes:
      - name: storage
        persistentVolumeClaim:
          claimName: watercluster-pvc
      - name: cert-vol
        secret:
          secretName: registry-tls
---
apiVersion: v1
kind: Service
metadata:
  name: registry-service
spec:
  type: NodePort
  selector:
    app: registry
  ports:
    - port: 30500
      targetPort: 30500
      nodePort: 30500

2. 트러블슈팅: x509 인증서 에러 해결 (CentOS/RHEL)

사설 인증서(Self-Signed Certificate)를 사용하면 쿠버네티스 노드들은 해당 레지스트리를 신뢰하지 않습니다. 이를 해결하기 위해 모든 마스터 및 워커 노드에서 다음 작업을 수행해야 합니다.

단계 1: 시스템 인증서 저장소에 등록

레지스트리 서버에서 인증서를 추출하여 OS 신뢰 목록에 추가합니다.

Bash

# 1. 인증서 추출 (129번은 레지스트리 IP)
openssl s_client -showcerts -connect 10.202.2.129:30500 </dev/null 2>/dev/null | openssl x509 -outform PEM > /tmp/registry.crt

# 2. 신뢰 저장소 경로로 복사
sudo cp /tmp/registry.crt /etc/pki/ca-trust/source/anchors/watercluster-registry.crt

# 3. 인증서 갱신
sudo update-ca-trust extract

단계 2: containerd 설정 최적화 (핵심 포인트)

많은 분이 /etc/containerd/config.toml에 config_path를 설정하지만, 사설 인증서를 OS에 등록했다면 이 설정이 오히려 충돌을 일으킬 수 있습니다.

Bash

sudo vi /etc/containerd/config.toml

수정 내용: 아래 설정을 찾아 주석 처리합니다.

Ini, TOML

[plugins."io.containerd.grpc.v1.cri".registry]
  # config_path = "/etc/containerd/certs.d"  <-- 주석 처리

이렇게 하면 containerd가 개별 설정 대신 시스템 기본 인증서 저장소를 참조하게 되어 훨씬 안정적입니다.

단계 3: 서비스 완전 재시작

설정 적용을 위해 엔진을 새로고침합니다.

Bash

sudo systemctl daemon-reload
sudo systemctl restart containerd
sudo systemctl restart kubelet

3. 대규모 환경에서의 자동화 (Ansible)

관리해야 할 서버가 100대 이상이라면 수동 작업은 불가능합니다. Ansible을 활용하면 폐쇄망 환경에서도 안전하고 빠르게 인증서를 배포할 수 있습니다.

에이전트 미설치(Agentless): SSH만 연결되면 즉시 실행 가능.
멱등성 보장: 여러 번 실행해도 동일한 설정 상태 유지.
폐쇄망 최적화: 외부 인터넷 없이도 내부망 내에서 모든 노드 제어 가능.

4. 서비스 노출 시 포트 매핑 이해

외부 접속을 위해 Service의 ports 설정을 할 때 다음의 구분을 명확히 해야 접속 오류를 방지할 수 있습니다.

포트 항목	설명	예시
port	클러스터 내부 서비스 IP에서 사용하는 포트	8080
targetPort	컨테이너 내부 앱(Tomcat 등)이 실제 리스닝하는 포트	8080
nodePort	외부에서 노드 IP를 통해 접속할 때 사용하는 포트	30080

요약 및 결론

사설 레지스트리 사용 시 인증서 에러는 필수 관문입니다.
OS 레벨(update-ca-trust)에 인증서를 등록하는 것이 가장 확실한 방법입니다.
containerd의 config_path 설정 충돌을 주의해야 합니다.
서버 대수가 많다면 Ansible과 같은 자동화 도구 도입을 적극 고려하세요.

도움이 되셨다면 공감과 댓글 부탁드립니다! 추가적인 질문은 언제든 환영합니다.

Next.js에서 통합 테스트 환경 구축하기 (Vitest)

추억을 백앤드하자 — Fri, 27 Feb 2026 14:04:26 +0900

Next.js에서 Supabase 실무 통합 테스트 환경 구축하기 (Vitest)

Next.js 프로젝트에서 Supabase 실제 DB를 대상으로 통합 테스트(Integration Test)를 작성할 때, 가장 큰 걸림돌은 환경 변수(process.env) 로딩 순서입니다. 본 가이드에서는 Vitest와 dotenv를 활용해 이 문제를 해결하고 실제 DB 연동까지 확인하는 완벽한 워크플로우를 소개합니다.

️ 1. 필수 패키지 설치

테스트 환경을 구축하기 위해 필요한 핵심 도구들을 설치합니다. Next.js의 경로 별칭(@/)과 브라우저 환경(jsdom)을 지원하는 패키지들입니다.

PowerShell

npm install -D vitest @vitejs/plugin-react vite-tsconfig-paths jsdom dotenv @testing-library/jest-dom

⚙️ 2. Vitest 설정 (환경 변수 문제 해결)

Next.js 환경에서 import 문은 코드 실행보다 먼저 처리되어 환경 변수가 undefined로 뜨는 경우가 많습니다. 이를 방지하기 위해 setupFiles를 활용합니다.

`vitest.config.ts` 생성

TypeScript

import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react';
import tsconfigPaths from 'vite-tsconfig-paths';
import path from 'path';

export default defineConfig({
  plugins: [react(), tsconfigPaths()],
  test: {
    environment: 'jsdom',
    globals: true,
    // [핵심] 테스트 실행 직전 환경 변수를 먼저 로드합니다.
    setupFiles: [path.resolve(__dirname, './vitest.setup.ts')],
  },
});

`vitest.setup.ts` 생성

.env.test 파일을 읽어 process.env에 강제로 주입하는 셋업 파일입니다.

TypeScript

import { config } from 'dotenv';
import path from 'path';

// .env.test 파일을 로드하여 테스트 프로세스에 할당합니다.
config({ path: path.resolve(__dirname, '.env.test') });

3. 환경 변수 및 스크립트 설정

테스트 전용 DB 정보를 관리하기 위해 .env.test 파일을 별도로 생성하는 것을 권장합니다.

`.env.test` 파일 예시

코드 스니펫

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_SERVICE_ROLE_KEY=your-secret-key

`package.json` 스크립트 추가

JSON

"scripts": {
  "test": "vitest --config ./vitest.config.ts --mode test"
}

4. 실제 DB 통합 테스트 코드 작성

테스트 대상 파일(supabaseService.ts)과 같은 위치에 .test.ts 파일을 생성하여 관리합니다.

`supabaseService.ts` (원본 코드)

TypeScript

import { supabaseAdmin } from '@/lib/supabaseServer';

export const supabaseService = {
  async save(content: string) {
    const { data, error } = await supabaseAdmin
      .from('ko_grammer') // 테이블명 확인 필수
      .insert([{ content }])
      .select()
      .single();

    if (error) {
      console.error('DB 저장 실패:', error.message);
      return { success: false, error };
    }
    return { success: true, data };
  }
};

`supabaseService.test.ts` (테스트 코드)

실제 네트워크 통신이 발생하므로 타임아웃을 넉넉히 설정하고, 테스트 후 데이터를 삭제하는 Cleanup 로직을 포함합니다.

TypeScript

import { afterAll, describe, expect, it } from 'vitest';
import { supabaseAdmin } from '@/lib/supabaseServer';
import { supabaseService } from './supabaseService';

describe('supabaseService.save 실제 DB 통합 테스트', () => {
  const TEST_CONTENT = '테스트 코드에서 보낸 실제 데이터입니다.';

  // 테스트 종료 후 생성된 데이터를 삭제하여 DB 정결 유지
  afterAll(async () => {
    await supabaseAdmin
      .from('ko_grammer')
      .delete()
      .eq('content', TEST_CONTENT);
  });

  it('실제 Supabase DB에 데이터를 저장하고 결과를 반환해야 한다', async () => {
    // 1. 함수 실행
    const result = await supabaseService.save(TEST_CONTENT);

    // 2. 응답 값 검증
    expect(result.success).toBe(true);
    expect(result.data?.content).toBe(TEST_CONTENT);

    // 3. DB 직접 조회 교차 검증
    const { data } = await supabaseAdmin
      .from('ko_grammar')
      .select()
      .eq('id', result.data?.id)
      .single();

    expect(data).not.toBeNull();
    expect(data?.content).toBe(TEST_CONTENT);
  }, 10000); // 네트워크 통신 고려 타임아웃 10초 설정
});

[Troubleshoot] Next.js TTS 모바일 발음 이슈 및 Gemini API 서버 사이드 캐싱 해결기

추억을 백앤드하자 — Tue, 3 Feb 2026 10:32:56 +0900

[Troubleshoot] Next.js TTS 모바일 발음 이슈 및 Gemini API 서버 사이드 캐싱 해결기

Next.js 환경에서 학습 서비스를 개발하며 겪은 두 가지 핵심 이슈인 '모바일 TTS 발음 파편화'와 'API 호출 비용 최적화를 위한 서버 캐싱'에 대한 트러블슈팅 과정을 공유합니다.

1. TTS 발음 이슈: 왜 내 폰에서는 영어가 한국어처럼 들릴까?

문제 상황

PC 웹 브라우저에서는 유창한 영어로 들리던 TTS(Text-to-Speech)가 모바일(Android/iOS) 기기에서 접속하면 한국어 억지로 영어를 읽는 듯한 '한국어식 발음'으로 출력되는 현상이 발생했습니다.

원인 분석

브라우저 내장 window.speechSynthesis는 OS 및 브라우저 엔진에 따라 제공하는 음성 데이터(Voices)가 다릅니다. 단순히 lang = 'en-US'만 설정할 경우, 모바일 기기에서는 기본 설정된 한국어 엔진이 영어를 읽어버리는 경우가 발생하기 때문입니다.

✅ 해결 방법: 음성 엔진 우선순위 할당 로직 도입

모바일 환경을 감지하여, 품질이 검증된 엔진(Google, Apple 등)을 강제로 매칭하고 모바일 특유의 먹먹함을 해결하기 위해 pitch와 rate를 보정했습니다.

이전로직

 async playTTS(text: string, options?: AudioServiceOptions): Promise<void> {
    return new Promise((resolve, reject) => {
      if (!this.isSupported()) {
        reject(new Error('Browser does not support speech synthesis'));
        return;
      }

      const opts = { ...this.defaultOptions, ...options };

      // 이전 재생 중지
      window.speechSynthesis.cancel();

      const utterance = new SpeechSynthesisUtterance(text);
      utterance.lang = opts.lang || 'en-US';
      utterance.rate = opts.rate || 0.9;
      utterance.pitch = opts.pitch || 1;

      // 최고 품질 음성 선택
      const voice = this.selectBestVoice(utterance.lang);
      if (voice) {
        utterance.voice = voice;
      }

      utterance.onend = () => resolve();
      utterance.onerror = (error) => {
        console.error('Speech synthesis error:', error);
        reject(error);
      };

      window.speechSynthesis.speak(utterance);
    });
  }

이후 로직

async playTTS(text: string, options?: AudioServiceOptions): Promise<void> {
    return new Promise((resolve, reject) => {
      if (typeof window === 'undefined' || !window.speechSynthesis) {
        return reject(new Error('지원하지 않는 브라우저입니다.'));
      }
      window.speechSynthesis.cancel();

      const opts = { ...this.defaultOptions, ...options };
      const utterance = new SpeechSynthesisUtterance(text);
      utterance.lang = opts.lang || 'en-US';

      const isMobile = this.checkIsMobile();
      if(isMobile){
        utterance.rate = options?.rate || 0.85; 
        utterance.pitch = 1.2;  보
      } else {

        utterance.rate = options?.rate || 0.9;
        utterance.pitch = options?.pitch || 1.0;
      }

// 핵심 로직: 영어 발음 강제를 위한 Voice Selection
      const voices = window.speechSynthesis.getVoices();
      const enVoices = voices.filter(v => v.lang.startsWith('en'));

     // 모바일 품질이 좋은 엔진 순서대로 매칭
      const selectedVoice = 
        enVoices.find(v => v.name.includes('Google') && v.lang === 'en-US') ||
        enVoices.find(v => v.name.includes('Apple') && v.lang === 'en-US') ||
        enVoices.find(v => v.lang === 'en-US') ||
        enVoices[0];

      if (selectedVoice) {
        utterance.voice = selectedVoice;
      }

      utterance.onend = () => resolve();
      utterance.onerror = (e) => reject(e);

      window.speechSynthesis.speak(utterance);
    });
  }

2. Gemini API 재요청 이슈: LocalStorage의 한계와 서버 캐싱

문제 상황

Gemini API는 호출당 비용이나 할당량이 제한되어 있습니다. 처음에는 사용자의 새로고침을 막기 위해 LocalStorage와 Client-side 메모리 캐시를 사용했으나, 이는 '개별 사용자'에게만 유효했습니다. 서비스에 1,000명의 새로운 사용자가 들어오면 여전히 1,000번의 API 호출이 발생하는 구조였습니다.

원인 분석

LocalStorage/SWR: 클라이언트 브라우저에만 데이터가 존재하므로 기기 간 공유가 불가능합니다.
서버 메모리 변수: 서버가 재시작되면 초기화되며, 인스턴스가 여러 개일 경우 동기화되지 않습니다.

✅ 해결 방법: Next.js Route Segment Config를 통한 정적 캐싱

모든 사용자가 동일한 학습 데이터를 본다면, 매번 생성할 필요 없이 서버 레벨에서 정적 결과물로 빌드하거나 긴 주기(24시간 등)로 캐싱하는 것이 가장 효율적입니다.

TypeScript

// ✅ Next.js App Router 서버 캐시 전략 적용

export const revalidate = 86400; // 24시간 동안 캐시 유지
export const dynamic = 'force-static'; // 해당 라우트를 정적 페이지로 강제

export async function GET(request: NextRequest) {
  try {
    // API 호출 및 데이터 처리 로직...
    return NextResponse.json(grammarData);
  } catch (error) {
    return NextResponse.json({ error: 'Failed' }, { status: 500 });
  }
}

마치며: 무엇을 배웠는가?

TTS는 엔진 선택이 핵심이다: 단순 lang 설정만으로는 부족하며, 디바이스별 보이스 리스트를 직접 필터링해야 일관된 UX를 제공할 수 있습니다.
캐싱의 주체를 명확히 하자: * 개인화된 데이터 LocalStorage / SWR
- 공통된 리소스 (콘텐츠) Server-side Caching (Next.js Cache)

불필요한 API 호출을 줄임으로써 비용 절감은 물론, 서버 응답 속도를 획기적으로 개선할 수 있었습니다.

Supabase 도커(Docker)로 로컬 개발 환경 구축하기

추억을 백앤드하자 — Mon, 2 Feb 2026 18:06:07 +0900

Supabase 도커(Docker)로 로컬 개발 환경 구축하기

1. Supabase란?

Supabase는 오픈소스 기반의 BaaS(Backend as a Service) 플랫폼입니다. 구글의 Firebase와 유사한 경험을 제공하지만, 가장 큰 차이점은 PostgreSQL(SQL)을 기반으로 한다는 점입니다.

주요 기능: 인증(Auth), 실시간 데이터베이스, 스토리지, Edge Functions 등.
장점: SQL의 강력한 쿼리 기능을 그대로 사용하면서, 백엔드 구축 없이 API를 자동으로 생성해 줍니다. 개발 속도를 극대화하고 프론트엔드 로직에만 집중할 수 있게 돕습니다.

2. 왜 Docker로 로컬 환경을 구축해야 할까?

클라우드 버전을 사용할 수도 있지만, 도커를 통한 Self-hosting은 다음과 같은 이점이 있습니다.

비용 절감: 프로젝트 개수나 데이터 제한 없이 무료로 사용 가능합니다.
독립적 환경: 오프라인 상태에서도 개발이 가능하며, 보안상 로컬 네트워크 내에서만 데이터를 관리할 때 유리합니다.

도커를 통한 self hosting은 아래의 공식문서를 참고

https://supabase.com/docs/guides/self-hosting/docker

3. Supabase 도커 설치 단계

Step 1. 저장소 클론 (Clone Repository)

내부에 docker-compose.yml 파일이 존재한다.

# 코드 가져오기
$ git clone https://github.com/supabase/supabase 

# 설정 파일이 있는 위치로 이동
$ cd supabase/docker

# 기본 .env 파일 복사
cp .env.example .env

Step 2. `.env` 파일 핵심 설정 (필수 수정)

실행 전 보안과 정상 작동을 위해 .env 파일에서 아래 항목들을 반드시 수정해야 합니다.

POSTGRES_PASSWORD: PostgreSQL 접속 비밀번호
JWT_SECRET: Supabase Auth와 RLS에 사용하는 JWT 서명 키
ANON_KEY: 클아이언트가 사용할 수 있는 공개 키
SERVICE_ROLE_KEY: 서버 측에서만 사용할 수 있는 권한 높은 JWT
DASHBOARD_USERNAME: Supabase Studio 로그인 ID
DASHBOARD_PASSWORD: Supabase Studio 로그인 비밀번호
SECRET_KEY_BASE: Supabase 내부에서 사용하는 Rails 비밀키
VAULT_ENC_KEY: 환경 변수 암호화를 위한 Valut 암호화 키(32자 이상)

보안 팁: 로컬 테스트용이더라도 비밀번호와 키값은 가급적 복잡하게 설정하는 것이 좋습니다.

예제 .env

name: supabase

services:

  studio:
    container_name: supabase-studio
    image: supabase/studio:2026.01.27-sha-6aa59ff
    restart: unless-stopped
    ports:
      - "6661:3000"
    healthcheck:
      test:
        [
          "CMD",
          "node",
          "-e",
          "fetch('http://studio:3000/api/platform/profile').then((r) => {if (r.status !== 200) throw new Error(r.status)})"
        ]
      timeout: 10s
      interval: 5s
      retries: 3
    depends_on:
      analytics:
        condition: service_healthy
    environment:
      # Binds nestjs listener to both IPv4 and IPv6 network interfaces
      HOSTNAME: "::"

      STUDIO_PG_META_URL: http://meta:8080
      POSTGRES_PORT: ${POSTGRES_PORT}
      POSTGRES_HOST: ${POSTGRES_HOST}
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      PG_META_CRYPTO_KEY: ${PG_META_CRYPTO_KEY}

      DEFAULT_ORGANIZATION_NAME: ${STUDIO_DEFAULT_ORGANIZATION}
      DEFAULT_PROJECT_NAME: ${STUDIO_DEFAULT_PROJECT}
      OPENAI_API_KEY: ${OPENAI_API_KEY:-}

      SUPABASE_URL: http://kong:8000
      SUPABASE_PUBLIC_URL: ${SUPABASE_PUBLIC_URL}
      SUPABASE_ANON_KEY: ${ANON_KEY}
      SUPABASE_SERVICE_KEY: ${SERVICE_ROLE_KEY}
      AUTH_JWT_SECRET: ${JWT_SECRET}

      # LOGFLARE_API_KEY is deprecated
      LOGFLARE_API_KEY: ${LOGFLARE_PUBLIC_ACCESS_TOKEN}
      LOGFLARE_PUBLIC_ACCESS_TOKEN: ${LOGFLARE_PUBLIC_ACCESS_TOKEN}
      LOGFLARE_PRIVATE_ACCESS_TOKEN: ${LOGFLARE_PRIVATE_ACCESS_TOKEN}

      LOGFLARE_URL: http://analytics:4000
      NEXT_PUBLIC_ENABLE_LOGS: true
      # Comment to use Big Query backend for analytics
      NEXT_ANALYTICS_BACKEND_PROVIDER: postgres
      # Uncomment to use Big Query backend for analytics
      # NEXT_ANALYTICS_BACKEND_PROVIDER: bigquery
      SNIPPETS_MANAGEMENT_FOLDER: /app/snippets
      EDGE_FUNCTIONS_MANAGEMENT_FOLDER: /app/edge-functions
    volumes:
      - ./volumes/snippets:/app/snippets:Z
      - ./volumes/functions:/app/edge-functions:Z

  kong:
    container_name: supabase-kong
    image: kong:2.8.1
    restart: unless-stopped
    ports:
      - ${KONG_HTTP_PORT}:8000/tcp
      - ${KONG_HTTPS_PORT}:8443/tcp
    volumes:
      # https://github.com/supabase/supabase/issues/12661
      - ./volumes/api/kong.yml:/home/kong/temp.yml:ro,z
    depends_on:
      analytics:
        condition: service_healthy
    environment:
      KONG_DATABASE: "off"
      KONG_DECLARATIVE_CONFIG: /home/kong/kong.yml
      # https://github.com/supabase/cli/issues/14
      KONG_DNS_ORDER: LAST,A,CNAME
      KONG_PLUGINS: request-transformer,cors,key-auth,acl,basic-auth,request-termination,ip-restriction
      KONG_NGINX_PROXY_PROXY_BUFFER_SIZE: 160k
      KONG_NGINX_PROXY_PROXY_BUFFERS: 64 160k
      SUPABASE_ANON_KEY: ${ANON_KEY}
      SUPABASE_SERVICE_KEY: ${SERVICE_ROLE_KEY}
      DASHBOARD_USERNAME: ${DASHBOARD_USERNAME}
      DASHBOARD_PASSWORD: ${DASHBOARD_PASSWORD}
    # https://unix.stackexchange.com/a/294837
    entrypoint: bash -c 'eval "echo \"$$(cat ~/temp.yml)\"" > ~/kong.yml && /docker-entrypoint.sh kong docker-start'

  auth:
    container_name: supabase-auth
    image: supabase/gotrue:v2.185.0
    restart: unless-stopped
    healthcheck:
      test:
        [
          "CMD",
          "wget",
          "--no-verbose",
          "--tries=1",
          "--spider",
          "http://localhost:9999/health"
        ]
      timeout: 5s
      interval: 5s
      retries: 3
    depends_on:
      db:
        # Disable this if you are using an external Postgres database
        condition: service_healthy
      analytics:
        condition: service_healthy
    environment:
      GOTRUE_API_HOST: 0.0.0.0
      GOTRUE_API_PORT: 9999
      API_EXTERNAL_URL: ${API_EXTERNAL_URL}

      GOTRUE_DB_DRIVER: postgres
      GOTRUE_DB_DATABASE_URL: postgres://supabase_auth_admin:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}

      GOTRUE_SITE_URL: ${SITE_URL}
      GOTRUE_URI_ALLOW_LIST: ${ADDITIONAL_REDIRECT_URLS}
      GOTRUE_DISABLE_SIGNUP: ${DISABLE_SIGNUP}

      GOTRUE_JWT_ADMIN_ROLES: service_role
      GOTRUE_JWT_AUD: authenticated
      GOTRUE_JWT_DEFAULT_GROUP_NAME: authenticated
      GOTRUE_JWT_EXP: ${JWT_EXPIRY}
      GOTRUE_JWT_SECRET: ${JWT_SECRET}

      GOTRUE_EXTERNAL_EMAIL_ENABLED: ${ENABLE_EMAIL_SIGNUP}
      GOTRUE_EXTERNAL_ANONYMOUS_USERS_ENABLED: ${ENABLE_ANONYMOUS_USERS}
      GOTRUE_MAILER_AUTOCONFIRM: ${ENABLE_EMAIL_AUTOCONFIRM}

      # Uncomment to bypass nonce check in ID Token flow. Commonly set to true when using Google Sign In on mobile.
      # GOTRUE_EXTERNAL_SKIP_NONCE_CHECK: true

      # GOTRUE_MAILER_SECURE_EMAIL_CHANGE_ENABLED: true
      # GOTRUE_SMTP_MAX_FREQUENCY: 1s
      GOTRUE_SMTP_ADMIN_EMAIL: ${SMTP_ADMIN_EMAIL}
      GOTRUE_SMTP_HOST: ${SMTP_HOST}
      GOTRUE_SMTP_PORT: ${SMTP_PORT}
      GOTRUE_SMTP_USER: ${SMTP_USER}
      GOTRUE_SMTP_PASS: ${SMTP_PASS}
      GOTRUE_SMTP_SENDER_NAME: ${SMTP_SENDER_NAME}
      GOTRUE_MAILER_URLPATHS_INVITE: ${MAILER_URLPATHS_INVITE}
      GOTRUE_MAILER_URLPATHS_CONFIRMATION: ${MAILER_URLPATHS_CONFIRMATION}
      GOTRUE_MAILER_URLPATHS_RECOVERY: ${MAILER_URLPATHS_RECOVERY}
      GOTRUE_MAILER_URLPATHS_EMAIL_CHANGE: ${MAILER_URLPATHS_EMAIL_CHANGE}

      GOTRUE_EXTERNAL_PHONE_ENABLED: ${ENABLE_PHONE_SIGNUP}
      GOTRUE_SMS_AUTOCONFIRM: ${ENABLE_PHONE_AUTOCONFIRM}
      # Uncomment to enable custom access token hook. Please see: https://supabase.com/docs/guides/auth/auth-hooks for full list of hooks and additional details about custom_access_token_hook

      # GOTRUE_HOOK_CUSTOM_ACCESS_TOKEN_ENABLED: "true"
      # GOTRUE_HOOK_CUSTOM_ACCESS_TOKEN_URI: "pg-functions://postgres/public/custom_access_token_hook"
      # GOTRUE_HOOK_CUSTOM_ACCESS_TOKEN_SECRETS: "<standard-base64-secret>"

      # GOTRUE_HOOK_MFA_VERIFICATION_ATTEMPT_ENABLED: "true"
      # GOTRUE_HOOK_MFA_VERIFICATION_ATTEMPT_URI: "pg-functions://postgres/public/mfa_verification_attempt"

      # GOTRUE_HOOK_PASSWORD_VERIFICATION_ATTEMPT_ENABLED: "true"
      # GOTRUE_HOOK_PASSWORD_VERIFICATION_ATTEMPT_URI: "pg-functions://postgres/public/password_verification_attempt"

      # GOTRUE_HOOK_SEND_SMS_ENABLED: "false"
      # GOTRUE_HOOK_SEND_SMS_URI: "pg-functions://postgres/public/custom_access_token_hook"
      # GOTRUE_HOOK_SEND_SMS_SECRETS: "v1,whsec_VGhpcyBpcyBhbiBleGFtcGxlIG9mIGEgc2hvcnRlciBCYXNlNjQgc3RyaW5n"

      # GOTRUE_HOOK_SEND_EMAIL_ENABLED: "false"
      # GOTRUE_HOOK_SEND_EMAIL_URI: "http://host.docker.internal:54321/functions/v1/email_sender"
      # GOTRUE_HOOK_SEND_EMAIL_SECRETS: "v1,whsec_VGhpcyBpcyBhbiBleGFtcGxlIG9mIGEgc2hvcnRlciBCYXNlNjQgc3RyaW5n"

  rest:
    container_name: supabase-rest
    image: postgrest/postgrest:v14.3
    restart: unless-stopped
    depends_on:
      db:
        # Disable this if you are using an external Postgres database
        condition: service_healthy
      analytics:
        condition: service_healthy
    environment:
      PGRST_DB_URI: postgres://authenticator:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}
      PGRST_DB_SCHEMAS: ${PGRST_DB_SCHEMAS}
      PGRST_DB_ANON_ROLE: anon
      PGRST_JWT_SECRET: ${JWT_SECRET}
      PGRST_DB_USE_LEGACY_GUCS: "false"
      PGRST_APP_SETTINGS_JWT_SECRET: ${JWT_SECRET}
      PGRST_APP_SETTINGS_JWT_EXP: ${JWT_EXPIRY}
    command:
      [
        "postgrest"
      ]

  realtime:
    # This container name looks inconsistent but is correct because realtime constructs tenant id by parsing the subdomain
    container_name: realtime-dev.supabase-realtime
    image: supabase/realtime:v2.72.0
    restart: unless-stopped
    depends_on:
      db:
        # Disable this if you are using an external Postgres database
        condition: service_healthy
      analytics:
        condition: service_healthy
    healthcheck:
      test:
        [
          "CMD-SHELL",
          "curl -sSfL --head -o /dev/null -H \"Authorization: Bearer ${ANON_KEY}\" http://localhost:4000/api/tenants/realtime-dev/health"
        ]
      timeout: 5s
      interval: 30s
      retries: 3
      start_period: 10s
    environment:
      PORT: 4000
      DB_HOST: ${POSTGRES_HOST}
      DB_PORT: ${POSTGRES_PORT}
      DB_USER: supabase_admin
      DB_PASSWORD: ${POSTGRES_PASSWORD}
      DB_NAME: ${POSTGRES_DB}
      DB_AFTER_CONNECT_QUERY: 'SET search_path TO _realtime'
      DB_ENC_KEY: supabaserealtime
      API_JWT_SECRET: ${JWT_SECRET}
      SECRET_KEY_BASE: ${SECRET_KEY_BASE}
      ERL_AFLAGS: -proto_dist inet_tcp
      DNS_NODES: "''"
      RLIMIT_NOFILE: "10000"
      APP_NAME: realtime
      SEED_SELF_HOST: "true"
      RUN_JANITOR: "true"
      DISABLE_HEALTHCHECK_LOGGING: "true"

  # To use S3 backed storage: docker compose -f docker-compose.yml -f docker-compose.s3.yml up
  storage:
    container_name: supabase-storage
    image: supabase/storage-api:v1.33.5
    restart: unless-stopped
    volumes:
      - ./volumes/storage:/var/lib/storage:z
    healthcheck:
      test:
        [
          "CMD",
          "wget",
          "--no-verbose",
          "--tries=1",
          "--spider",
          "http://storage:5000/status"
        ]
      timeout: 5s
      interval: 5s
      retries: 3
    depends_on:
      db:
        # Disable this if you are using an external Postgres database
        condition: service_healthy
      rest:
        condition: service_started
      imgproxy:
        condition: service_started
    environment:
      ANON_KEY: ${ANON_KEY}
      SERVICE_KEY: ${SERVICE_ROLE_KEY}
      POSTGREST_URL: http://rest:3000
      PGRST_JWT_SECRET: ${JWT_SECRET}
      DATABASE_URL: postgres://supabase_storage_admin:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}
      REQUEST_ALLOW_X_FORWARDED_PATH: "true"
      FILE_SIZE_LIMIT: 52428800
      STORAGE_BACKEND: file
      FILE_STORAGE_BACKEND_PATH: /var/lib/storage
      TENANT_ID: stub
      # TODO: https://github.com/supabase/storage-api/issues/55
      REGION: stub
      GLOBAL_S3_BUCKET: stub
      ENABLE_IMAGE_TRANSFORMATION: "true"
      IMGPROXY_URL: http://imgproxy:5001

  imgproxy:
    container_name: supabase-imgproxy
    image: darthsim/imgproxy:v3.30.1
    restart: unless-stopped
    volumes:
      - ./volumes/storage:/var/lib/storage:z
    healthcheck:
      test:
        [
          "CMD",
          "imgproxy",
          "health"
        ]
      timeout: 5s
      interval: 5s
      retries: 3
    environment:
      IMGPROXY_BIND: ":5001"
      IMGPROXY_LOCAL_FILESYSTEM_ROOT: /
      IMGPROXY_USE_ETAG: "true"
      IMGPROXY_ENABLE_WEBP_DETECTION: ${IMGPROXY_ENABLE_WEBP_DETECTION}
      IMGPROXY_MAX_SRC_RESOLUTION: 16.8

  meta:
    container_name: supabase-meta
    image: supabase/postgres-meta:v0.95.2
    restart: unless-stopped
    depends_on:
      db:
        # Disable this if you are using an external Postgres database
        condition: service_healthy
      analytics:
        condition: service_healthy
    environment:
      PG_META_PORT: 8080
      PG_META_DB_HOST: ${POSTGRES_HOST}
      PG_META_DB_PORT: ${POSTGRES_PORT}
      PG_META_DB_NAME: ${POSTGRES_DB}
      PG_META_DB_USER: supabase_admin
      PG_META_DB_PASSWORD: ${POSTGRES_PASSWORD}
      CRYPTO_KEY: ${PG_META_CRYPTO_KEY}

  functions:
    container_name: supabase-edge-functions
    image: supabase/edge-runtime:v1.70.0
    restart: unless-stopped
    volumes:
      - ./volumes/functions:/home/deno/functions:Z
    depends_on:
      analytics:
        condition: service_healthy
    environment:
      JWT_SECRET: ${JWT_SECRET}
      SUPABASE_URL: http://kong:8000
      SUPABASE_ANON_KEY: ${ANON_KEY}
      SUPABASE_SERVICE_ROLE_KEY: ${SERVICE_ROLE_KEY}
      SUPABASE_DB_URL: postgresql://postgres:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}
      # TODO: Allow configuring VERIFY_JWT per function. This PR might help: https://github.com/supabase/cli/pull/786
      VERIFY_JWT: "${FUNCTIONS_VERIFY_JWT}"
    command:
      [
        "start",
        "--main-service",
        "/home/deno/functions/main"
      ]

  analytics:
    container_name: supabase-analytics
    image: supabase/logflare:1.30.3
    restart: unless-stopped
    ports:
      - 4000:4000
    # Uncomment to use Big Query backend for analytics
    # volumes:
    #   - type: bind
    #     source: ${PWD}/gcloud.json
    #     target: /opt/app/rel/logflare/bin/gcloud.json
    #     read_only: true
    healthcheck:
      test:
        [
          "CMD",
          "curl",
          "http://localhost:4000/health"
        ]
      timeout: 5s
      interval: 5s
      retries: 10
    depends_on:
      db:
        # Disable this if you are using an external Postgres database
        condition: service_healthy
    environment:
      LOGFLARE_NODE_HOST: 127.0.0.1
      DB_USERNAME: supabase_admin
      DB_DATABASE: _supabase
      DB_HOSTNAME: ${POSTGRES_HOST}
      DB_PORT: ${POSTGRES_PORT}
      DB_PASSWORD: ${POSTGRES_PASSWORD}
      DB_SCHEMA: _analytics
      LOGFLARE_PUBLIC_ACCESS_TOKEN: ${LOGFLARE_PUBLIC_ACCESS_TOKEN}
      LOGFLARE_PRIVATE_ACCESS_TOKEN: ${LOGFLARE_PRIVATE_ACCESS_TOKEN}
      LOGFLARE_SINGLE_TENANT: true
      LOGFLARE_SUPABASE_MODE: true

      # Comment variables to use Big Query backend for analytics
      POSTGRES_BACKEND_URL: postgresql://supabase_admin:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/_supabase
      POSTGRES_BACKEND_SCHEMA: _analytics
      LOGFLARE_FEATURE_FLAG_OVERRIDE: multibackend=true
      # Uncomment to use Big Query backend for analytics
      # GOOGLE_PROJECT_ID: ${GOOGLE_PROJECT_ID}
      # GOOGLE_PROJECT_NUMBER: ${GOOGLE_PROJECT_NUMBER}

  # Comment out everything below this point if you are using an external Postgres database
  db:
    container_name: supabase-db
    image: supabase/postgres:15.8.1.085
    restart: unless-stopped
    ports:
      - "54322:5432"
    volumes:
      - ./volumes/db/realtime.sql:/docker-entrypoint-initdb.d/migrations/99-realtime.sql:Z
      # Must be superuser to create event trigger
      - ./volumes/db/webhooks.sql:/docker-entrypoint-initdb.d/init-scripts/98-webhooks.sql:Z
      # Must be superuser to alter reserved role
      - ./volumes/db/roles.sql:/docker-entrypoint-initdb.d/init-scripts/99-roles.sql:Z
      # Initialize the database settings with JWT_SECRET and JWT_EXP
      - ./volumes/db/jwt.sql:/docker-entrypoint-initdb.d/init-scripts/99-jwt.sql:Z
      # PGDATA directory is persisted between restarts
      - ./volumes/db/data:/var/lib/postgresql/data:Z
      # Changes required for internal supabase data such as _analytics
      - ./volumes/db/_supabase.sql:/docker-entrypoint-initdb.d/migrations/97-_supabase.sql:Z
      # Changes required for Analytics support
      - ./volumes/db/logs.sql:/docker-entrypoint-initdb.d/migrations/99-logs.sql:Z
      # Changes required for Pooler support
      - ./volumes/db/pooler.sql:/docker-entrypoint-initdb.d/migrations/99-pooler.sql:Z
      # Use named volume to persist pgsodium decryption key between restarts
      - db-config:/etc/postgresql-custom
    healthcheck:
      test:
        [
        "CMD",
        "pg_isready",
        "-U",
        "postgres",
        "-h",
        "localhost"
        ]
      interval: 5s
      timeout: 5s
      retries: 10
    depends_on:
      vector:
        condition: service_healthy
    environment:
      POSTGRES_HOST: /var/run/postgresql
      PGPORT: ${POSTGRES_PORT}
      POSTGRES_PORT: ${POSTGRES_PORT}
      PGPASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      PGDATABASE: ${POSTGRES_DB}
      POSTGRES_DB: ${POSTGRES_DB}
      JWT_SECRET: ${JWT_SECRET}
      JWT_EXP: ${JWT_EXPIRY}
    command:
      [
        "postgres",
        "-c",
        "config_file=/etc/postgresql/postgresql.conf",
        "-c",
        "log_min_messages=fatal" # prevents Realtime polling queries from appearing in logs
      ]

  vector:
    container_name: supabase-vector
    image: timberio/vector:0.28.1-alpine
    restart: unless-stopped
    volumes:
      - ./volumes/logs/vector.yml:/etc/vector/vector.yml:ro,z
      - ${DOCKER_SOCKET_LOCATION}:/var/run/docker.sock:ro,z
    healthcheck:
      test:
        [
          "CMD",
          "wget",
          "--no-verbose",
          "--tries=1",
          "--spider",
          "http://vector:9001/health"
        ]
      timeout: 5s
      interval: 5s
      retries: 3
    environment:
      LOGFLARE_PUBLIC_ACCESS_TOKEN: ${LOGFLARE_PUBLIC_ACCESS_TOKEN}
    command:
      [
        "--config",
        "/etc/vector/vector.yml"
      ]
    security_opt:
      - "label=disable"

  # Update the DATABASE_URL if you are using an external Postgres database
  supavisor:
    container_name: supabase-pooler
    image: supabase/supavisor:2.7.4
    restart: unless-stopped
    ports:
      - ${POSTGRES_PORT}:5432
      - ${POOLER_PROXY_PORT_TRANSACTION}:6543
    volumes:
      - ./volumes/pooler/pooler.exs:/etc/pooler/pooler.exs:ro,z
    healthcheck:
      test:
        [
          "CMD",
          "curl",
          "-sSfL",
          "--head",
          "-o",
          "/dev/null",
          "http://127.0.0.1:4000/api/health"
        ]
      interval: 10s
      timeout: 5s
      retries: 5
    depends_on:
      db:
        condition: service_healthy
      analytics:
        condition: service_healthy
    environment:
      PORT: 4000
      POSTGRES_PORT: ${POSTGRES_PORT}
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      DATABASE_URL: ecto://supabase_admin:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/_supabase
      CLUSTER_POSTGRES: true
      SECRET_KEY_BASE: ${SECRET_KEY_BASE}
      VAULT_ENC_KEY: ${VAULT_ENC_KEY}
      API_JWT_SECRET: ${JWT_SECRET}
      METRICS_JWT_SECRET: ${JWT_SECRET}
      REGION: local
      ERL_AFLAGS: -proto_dist inet_tcp
      POOLER_TENANT_ID: ${POOLER_TENANT_ID}
      POOLER_DEFAULT_POOL_SIZE: ${POOLER_DEFAULT_POOL_SIZE}
      POOLER_MAX_CLIENT_CONN: ${POOLER_MAX_CLIENT_CONN}
      POOLER_POOL_MODE: transaction
      DB_POOL_SIZE: ${POOLER_DB_POOL_SIZE}
    command:
      [
        "/bin/sh",
        "-c",
        "/app/bin/migrate && /app/bin/supavisor eval \"$$(cat /etc/pooler/pooler.exs)\" && /app/bin/server"
      ]

volumes:
  db-config:

docker-compose.yml

name: supabase

services:

  studio:
    container_name: supabase-studio
    image: supabase/studio:2026.01.27-sha-6aa59ff
    restart: unless-stopped
    ports:
      - "6661:3000"
    healthcheck:
      test:
        [
          "CMD",
          "node",
          "-e",
          "fetch('http://studio:3000/api/platform/profile').then((r) => {if (r.status !== 200) throw new Error(r.status)})"
        ]
      timeout: 10s
      interval: 5s
      retries: 3
    depends_on:
      analytics:
        condition: service_healthy
    environment:
      # Binds nestjs listener to both IPv4 and IPv6 network interfaces
      HOSTNAME: "::"

      STUDIO_PG_META_URL: http://meta:8080
      POSTGRES_PORT: ${POSTGRES_PORT}
      POSTGRES_HOST: ${POSTGRES_HOST}
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      PG_META_CRYPTO_KEY: ${PG_META_CRYPTO_KEY}

      DEFAULT_ORGANIZATION_NAME: ${STUDIO_DEFAULT_ORGANIZATION}
      DEFAULT_PROJECT_NAME: ${STUDIO_DEFAULT_PROJECT}
      OPENAI_API_KEY: ${OPENAI_API_KEY:-}

      SUPABASE_URL: http://kong:8000
      SUPABASE_PUBLIC_URL: ${SUPABASE_PUBLIC_URL}
      SUPABASE_ANON_KEY: ${ANON_KEY}
      SUPABASE_SERVICE_KEY: ${SERVICE_ROLE_KEY}
      AUTH_JWT_SECRET: ${JWT_SECRET}

      # LOGFLARE_API_KEY is deprecated
      LOGFLARE_API_KEY: ${LOGFLARE_PUBLIC_ACCESS_TOKEN}
      LOGFLARE_PUBLIC_ACCESS_TOKEN: ${LOGFLARE_PUBLIC_ACCESS_TOKEN}
      LOGFLARE_PRIVATE_ACCESS_TOKEN: ${LOGFLARE_PRIVATE_ACCESS_TOKEN}

      LOGFLARE_URL: http://analytics:4000
      NEXT_PUBLIC_ENABLE_LOGS: true
      # Comment to use Big Query backend for analytics
      NEXT_ANALYTICS_BACKEND_PROVIDER: postgres
      # Uncomment to use Big Query backend for analytics
      # NEXT_ANALYTICS_BACKEND_PROVIDER: bigquery
      SNIPPETS_MANAGEMENT_FOLDER: /app/snippets
      EDGE_FUNCTIONS_MANAGEMENT_FOLDER: /app/edge-functions
    volumes:
      - ./volumes/snippets:/app/snippets:Z
      - ./volumes/functions:/app/edge-functions:Z

  kong:
    container_name: supabase-kong
    image: kong:2.8.1
    restart: unless-stopped
    ports:
      - ${KONG_HTTP_PORT}:8000/tcp
      - ${KONG_HTTPS_PORT}:8443/tcp
    volumes:
      # https://github.com/supabase/supabase/issues/12661
      - ./volumes/api/kong.yml:/home/kong/temp.yml:ro,z
    depends_on:
      analytics:
        condition: service_healthy
    environment:
      KONG_DATABASE: "off"
      KONG_DECLARATIVE_CONFIG: /home/kong/kong.yml
      # https://github.com/supabase/cli/issues/14
      KONG_DNS_ORDER: LAST,A,CNAME
      KONG_PLUGINS: request-transformer,cors,key-auth,acl,basic-auth,request-termination,ip-restriction
      KONG_NGINX_PROXY_PROXY_BUFFER_SIZE: 160k
      KONG_NGINX_PROXY_PROXY_BUFFERS: 64 160k
      SUPABASE_ANON_KEY: ${ANON_KEY}
      SUPABASE_SERVICE_KEY: ${SERVICE_ROLE_KEY}
      DASHBOARD_USERNAME: ${DASHBOARD_USERNAME}
      DASHBOARD_PASSWORD: ${DASHBOARD_PASSWORD}
    # https://unix.stackexchange.com/a/294837
    entrypoint: bash -c 'eval "echo \"$$(cat ~/temp.yml)\"" > ~/kong.yml && /docker-entrypoint.sh kong docker-start'

  auth:
    container_name: supabase-auth
    image: supabase/gotrue:v2.185.0
    restart: unless-stopped
    healthcheck:
      test:
        [
          "CMD",
          "wget",
          "--no-verbose",
          "--tries=1",
          "--spider",
          "http://localhost:9999/health"
        ]
      timeout: 5s
      interval: 5s
      retries: 3
    depends_on:
      db:
        # Disable this if you are using an external Postgres database
        condition: service_healthy
      analytics:
        condition: service_healthy
    environment:
      GOTRUE_API_HOST: 0.0.0.0
      GOTRUE_API_PORT: 9999
      API_EXTERNAL_URL: ${API_EXTERNAL_URL}

      GOTRUE_DB_DRIVER: postgres
      GOTRUE_DB_DATABASE_URL: postgres://supabase_auth_admin:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}

      GOTRUE_SITE_URL: ${SITE_URL}
      GOTRUE_URI_ALLOW_LIST: ${ADDITIONAL_REDIRECT_URLS}
      GOTRUE_DISABLE_SIGNUP: ${DISABLE_SIGNUP}

      GOTRUE_JWT_ADMIN_ROLES: service_role
      GOTRUE_JWT_AUD: authenticated
      GOTRUE_JWT_DEFAULT_GROUP_NAME: authenticated
      GOTRUE_JWT_EXP: ${JWT_EXPIRY}
      GOTRUE_JWT_SECRET: ${JWT_SECRET}

      GOTRUE_EXTERNAL_EMAIL_ENABLED: ${ENABLE_EMAIL_SIGNUP}
      GOTRUE_EXTERNAL_ANONYMOUS_USERS_ENABLED: ${ENABLE_ANONYMOUS_USERS}
      GOTRUE_MAILER_AUTOCONFIRM: ${ENABLE_EMAIL_AUTOCONFIRM}

      # Uncomment to bypass nonce check in ID Token flow. Commonly set to true when using Google Sign In on mobile.
      # GOTRUE_EXTERNAL_SKIP_NONCE_CHECK: true

      # GOTRUE_MAILER_SECURE_EMAIL_CHANGE_ENABLED: true
      # GOTRUE_SMTP_MAX_FREQUENCY: 1s
      GOTRUE_SMTP_ADMIN_EMAIL: ${SMTP_ADMIN_EMAIL}
      GOTRUE_SMTP_HOST: ${SMTP_HOST}
      GOTRUE_SMTP_PORT: ${SMTP_PORT}
      GOTRUE_SMTP_USER: ${SMTP_USER}
      GOTRUE_SMTP_PASS: ${SMTP_PASS}
      GOTRUE_SMTP_SENDER_NAME: ${SMTP_SENDER_NAME}
      GOTRUE_MAILER_URLPATHS_INVITE: ${MAILER_URLPATHS_INVITE}
      GOTRUE_MAILER_URLPATHS_CONFIRMATION: ${MAILER_URLPATHS_CONFIRMATION}
      GOTRUE_MAILER_URLPATHS_RECOVERY: ${MAILER_URLPATHS_RECOVERY}
      GOTRUE_MAILER_URLPATHS_EMAIL_CHANGE: ${MAILER_URLPATHS_EMAIL_CHANGE}

      GOTRUE_EXTERNAL_PHONE_ENABLED: ${ENABLE_PHONE_SIGNUP}
      GOTRUE_SMS_AUTOCONFIRM: ${ENABLE_PHONE_AUTOCONFIRM}
      # Uncomment to enable custom access token hook. Please see: https://supabase.com/docs/guides/auth/auth-hooks for full list of hooks and additional details about custom_access_token_hook

      # GOTRUE_HOOK_CUSTOM_ACCESS_TOKEN_ENABLED: "true"
      # GOTRUE_HOOK_CUSTOM_ACCESS_TOKEN_URI: "pg-functions://postgres/public/custom_access_token_hook"
      # GOTRUE_HOOK_CUSTOM_ACCESS_TOKEN_SECRETS: "<standard-base64-secret>"

      # GOTRUE_HOOK_MFA_VERIFICATION_ATTEMPT_ENABLED: "true"
      # GOTRUE_HOOK_MFA_VERIFICATION_ATTEMPT_URI: "pg-functions://postgres/public/mfa_verification_attempt"

      # GOTRUE_HOOK_PASSWORD_VERIFICATION_ATTEMPT_ENABLED: "true"
      # GOTRUE_HOOK_PASSWORD_VERIFICATION_ATTEMPT_URI: "pg-functions://postgres/public/password_verification_attempt"

      # GOTRUE_HOOK_SEND_SMS_ENABLED: "false"
      # GOTRUE_HOOK_SEND_SMS_URI: "pg-functions://postgres/public/custom_access_token_hook"
      # GOTRUE_HOOK_SEND_SMS_SECRETS: "v1,whsec_VGhpcyBpcyBhbiBleGFtcGxlIG9mIGEgc2hvcnRlciBCYXNlNjQgc3RyaW5n"

      # GOTRUE_HOOK_SEND_EMAIL_ENABLED: "false"
      # GOTRUE_HOOK_SEND_EMAIL_URI: "http://host.docker.internal:54321/functions/v1/email_sender"
      # GOTRUE_HOOK_SEND_EMAIL_SECRETS: "v1,whsec_VGhpcyBpcyBhbiBleGFtcGxlIG9mIGEgc2hvcnRlciBCYXNlNjQgc3RyaW5n"

  rest:
    container_name: supabase-rest
    image: postgrest/postgrest:v14.3
    restart: unless-stopped
    depends_on:
      db:
        # Disable this if you are using an external Postgres database
        condition: service_healthy
      analytics:
        condition: service_healthy
    environment:
      PGRST_DB_URI: postgres://authenticator:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}
      PGRST_DB_SCHEMAS: ${PGRST_DB_SCHEMAS}
      PGRST_DB_ANON_ROLE: anon
      PGRST_JWT_SECRET: ${JWT_SECRET}
      PGRST_DB_USE_LEGACY_GUCS: "false"
      PGRST_APP_SETTINGS_JWT_SECRET: ${JWT_SECRET}
      PGRST_APP_SETTINGS_JWT_EXP: ${JWT_EXPIRY}
    command:
      [
        "postgrest"
      ]

  realtime:
    # This container name looks inconsistent but is correct because realtime constructs tenant id by parsing the subdomain
    container_name: realtime-dev.supabase-realtime
    image: supabase/realtime:v2.72.0
    restart: unless-stopped
    depends_on:
      db:
        # Disable this if you are using an external Postgres database
        condition: service_healthy
      analytics:
        condition: service_healthy
    healthcheck:
      test:
        [
          "CMD-SHELL",
          "curl -sSfL --head -o /dev/null -H \"Authorization: Bearer ${ANON_KEY}\" http://localhost:4000/api/tenants/realtime-dev/health"
        ]
      timeout: 5s
      interval: 30s
      retries: 3
      start_period: 10s
    environment:
      PORT: 4000
      DB_HOST: ${POSTGRES_HOST}
      DB_PORT: ${POSTGRES_PORT}
      DB_USER: supabase_admin
      DB_PASSWORD: ${POSTGRES_PASSWORD}
      DB_NAME: ${POSTGRES_DB}
      DB_AFTER_CONNECT_QUERY: 'SET search_path TO _realtime'
      DB_ENC_KEY: supabaserealtime
      API_JWT_SECRET: ${JWT_SECRET}
      SECRET_KEY_BASE: ${SECRET_KEY_BASE}
      ERL_AFLAGS: -proto_dist inet_tcp
      DNS_NODES: "''"
      RLIMIT_NOFILE: "10000"
      APP_NAME: realtime
      SEED_SELF_HOST: "true"
      RUN_JANITOR: "true"
      DISABLE_HEALTHCHECK_LOGGING: "true"

  # To use S3 backed storage: docker compose -f docker-compose.yml -f docker-compose.s3.yml up
  storage:
    container_name: supabase-storage
    image: supabase/storage-api:v1.33.5
    restart: unless-stopped
    volumes:
      - ./volumes/storage:/var/lib/storage:z
    healthcheck:
      test:
        [
          "CMD",
          "wget",
          "--no-verbose",
          "--tries=1",
          "--spider",
          "http://storage:5000/status"
        ]
      timeout: 5s
      interval: 5s
      retries: 3
    depends_on:
      db:
        # Disable this if you are using an external Postgres database
        condition: service_healthy
      rest:
        condition: service_started
      imgproxy:
        condition: service_started
    environment:
      ANON_KEY: ${ANON_KEY}
      SERVICE_KEY: ${SERVICE_ROLE_KEY}
      POSTGREST_URL: http://rest:3000
      PGRST_JWT_SECRET: ${JWT_SECRET}
      DATABASE_URL: postgres://supabase_storage_admin:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}
      REQUEST_ALLOW_X_FORWARDED_PATH: "true"
      FILE_SIZE_LIMIT: 52428800
      STORAGE_BACKEND: file
      FILE_STORAGE_BACKEND_PATH: /var/lib/storage
      TENANT_ID: stub
      # TODO: https://github.com/supabase/storage-api/issues/55
      REGION: stub
      GLOBAL_S3_BUCKET: stub
      ENABLE_IMAGE_TRANSFORMATION: "true"
      IMGPROXY_URL: http://imgproxy:5001

  imgproxy:
    container_name: supabase-imgproxy
    image: darthsim/imgproxy:v3.30.1
    restart: unless-stopped
    volumes:
      - ./volumes/storage:/var/lib/storage:z
    healthcheck:
      test:
        [
          "CMD",
          "imgproxy",
          "health"
        ]
      timeout: 5s
      interval: 5s
      retries: 3
    environment:
      IMGPROXY_BIND: ":5001"
      IMGPROXY_LOCAL_FILESYSTEM_ROOT: /
      IMGPROXY_USE_ETAG: "true"
      IMGPROXY_ENABLE_WEBP_DETECTION: ${IMGPROXY_ENABLE_WEBP_DETECTION}
      IMGPROXY_MAX_SRC_RESOLUTION: 16.8

  meta:
    container_name: supabase-meta
    image: supabase/postgres-meta:v0.95.2
    restart: unless-stopped
    depends_on:
      db:
        # Disable this if you are using an external Postgres database
        condition: service_healthy
      analytics:
        condition: service_healthy
    environment:
      PG_META_PORT: 8080
      PG_META_DB_HOST: ${POSTGRES_HOST}
      PG_META_DB_PORT: ${POSTGRES_PORT}
      PG_META_DB_NAME: ${POSTGRES_DB}
      PG_META_DB_USER: supabase_admin
      PG_META_DB_PASSWORD: ${POSTGRES_PASSWORD}
      CRYPTO_KEY: ${PG_META_CRYPTO_KEY}

  functions:
    container_name: supabase-edge-functions
    image: supabase/edge-runtime:v1.70.0
    restart: unless-stopped
    volumes:
      - ./volumes/functions:/home/deno/functions:Z
    depends_on:
      analytics:
        condition: service_healthy
    environment:
      JWT_SECRET: ${JWT_SECRET}
      SUPABASE_URL: http://kong:8000
      SUPABASE_ANON_KEY: ${ANON_KEY}
      SUPABASE_SERVICE_ROLE_KEY: ${SERVICE_ROLE_KEY}
      SUPABASE_DB_URL: postgresql://postgres:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}
      # TODO: Allow configuring VERIFY_JWT per function. This PR might help: https://github.com/supabase/cli/pull/786
      VERIFY_JWT: "${FUNCTIONS_VERIFY_JWT}"
    command:
      [
        "start",
        "--main-service",
        "/home/deno/functions/main"
      ]

  analytics:
    container_name: supabase-analytics
    image: supabase/logflare:1.30.3
    restart: unless-stopped
    ports:
      - 4000:4000
    # Uncomment to use Big Query backend for analytics
    # volumes:
    #   - type: bind
    #     source: ${PWD}/gcloud.json
    #     target: /opt/app/rel/logflare/bin/gcloud.json
    #     read_only: true
    healthcheck:
      test:
        [
          "CMD",
          "curl",
          "http://localhost:4000/health"
        ]
      timeout: 5s
      interval: 5s
      retries: 10
    depends_on:
      db:
        # Disable this if you are using an external Postgres database
        condition: service_healthy
    environment:
      LOGFLARE_NODE_HOST: 127.0.0.1
      DB_USERNAME: supabase_admin
      DB_DATABASE: _supabase
      DB_HOSTNAME: ${POSTGRES_HOST}
      DB_PORT: ${POSTGRES_PORT}
      DB_PASSWORD: ${POSTGRES_PASSWORD}
      DB_SCHEMA: _analytics
      LOGFLARE_PUBLIC_ACCESS_TOKEN: ${LOGFLARE_PUBLIC_ACCESS_TOKEN}
      LOGFLARE_PRIVATE_ACCESS_TOKEN: ${LOGFLARE_PRIVATE_ACCESS_TOKEN}
      LOGFLARE_SINGLE_TENANT: true
      LOGFLARE_SUPABASE_MODE: true

      # Comment variables to use Big Query backend for analytics
      POSTGRES_BACKEND_URL: postgresql://supabase_admin:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/_supabase
      POSTGRES_BACKEND_SCHEMA: _analytics
      LOGFLARE_FEATURE_FLAG_OVERRIDE: multibackend=true
      # Uncomment to use Big Query backend for analytics
      # GOOGLE_PROJECT_ID: ${GOOGLE_PROJECT_ID}
      # GOOGLE_PROJECT_NUMBER: ${GOOGLE_PROJECT_NUMBER}

  # Comment out everything below this point if you are using an external Postgres database
  db:
    container_name: supabase-db
    image: supabase/postgres:15.8.1.085
    restart: unless-stopped
    ports:
      - "54322:5432"
    volumes:
      - ./volumes/db/realtime.sql:/docker-entrypoint-initdb.d/migrations/99-realtime.sql:Z
      # Must be superuser to create event trigger
      - ./volumes/db/webhooks.sql:/docker-entrypoint-initdb.d/init-scripts/98-webhooks.sql:Z
      # Must be superuser to alter reserved role
      - ./volumes/db/roles.sql:/docker-entrypoint-initdb.d/init-scripts/99-roles.sql:Z
      # Initialize the database settings with JWT_SECRET and JWT_EXP
      - ./volumes/db/jwt.sql:/docker-entrypoint-initdb.d/init-scripts/99-jwt.sql:Z
      # PGDATA directory is persisted between restarts
      - ./volumes/db/data:/var/lib/postgresql/data:Z
      # Changes required for internal supabase data such as _analytics
      - ./volumes/db/_supabase.sql:/docker-entrypoint-initdb.d/migrations/97-_supabase.sql:Z
      # Changes required for Analytics support
      - ./volumes/db/logs.sql:/docker-entrypoint-initdb.d/migrations/99-logs.sql:Z
      # Changes required for Pooler support
      - ./volumes/db/pooler.sql:/docker-entrypoint-initdb.d/migrations/99-pooler.sql:Z
      # Use named volume to persist pgsodium decryption key between restarts
      - db-config:/etc/postgresql-custom
    healthcheck:
      test:
        [
        "CMD",
        "pg_isready",
        "-U",
        "postgres",
        "-h",
        "localhost"
        ]
      interval: 5s
      timeout: 5s
      retries: 10
    depends_on:
      vector:
        condition: service_healthy
    environment:
      POSTGRES_HOST: /var/run/postgresql
      PGPORT: ${POSTGRES_PORT}
      POSTGRES_PORT: ${POSTGRES_PORT}
      PGPASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      PGDATABASE: ${POSTGRES_DB}
      POSTGRES_DB: ${POSTGRES_DB}
      JWT_SECRET: ${JWT_SECRET}
      JWT_EXP: ${JWT_EXPIRY}
    command:
      [
        "postgres",
        "-c",
        "config_file=/etc/postgresql/postgresql.conf",
        "-c",
        "log_min_messages=fatal" # prevents Realtime polling queries from appearing in logs
      ]

  vector:
    container_name: supabase-vector
    image: timberio/vector:0.28.1-alpine
    restart: unless-stopped
    volumes:
      - ./volumes/logs/vector.yml:/etc/vector/vector.yml:ro,z
      - ${DOCKER_SOCKET_LOCATION}:/var/run/docker.sock:ro,z
    healthcheck:
      test:
        [
          "CMD",
          "wget",
          "--no-verbose",
          "--tries=1",
          "--spider",
          "http://vector:9001/health"
        ]
      timeout: 5s
      interval: 5s
      retries: 3
    environment:
      LOGFLARE_PUBLIC_ACCESS_TOKEN: ${LOGFLARE_PUBLIC_ACCESS_TOKEN}
    command:
      [
        "--config",
        "/etc/vector/vector.yml"
      ]
    security_opt:
      - "label=disable"

  # Update the DATABASE_URL if you are using an external Postgres database
  supavisor:
    container_name: supabase-pooler
    image: supabase/supavisor:2.7.4
    restart: unless-stopped
    ports:
      - ${POSTGRES_PORT}:5432
      - ${POOLER_PROXY_PORT_TRANSACTION}:6543
    volumes:
      - ./volumes/pooler/pooler.exs:/etc/pooler/pooler.exs:ro,z
    healthcheck:
      test:
        [
          "CMD",
          "curl",
          "-sSfL",
          "--head",
          "-o",
          "/dev/null",
          "http://127.0.0.1:4000/api/health"
        ]
      interval: 10s
      timeout: 5s
      retries: 5
    depends_on:
      db:
        condition: service_healthy
      analytics:
        condition: service_healthy
    environment:
      PORT: 4000
      POSTGRES_PORT: ${POSTGRES_PORT}
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      DATABASE_URL: ecto://supabase_admin:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/_supabase
      CLUSTER_POSTGRES: true
      SECRET_KEY_BASE: ${SECRET_KEY_BASE}
      VAULT_ENC_KEY: ${VAULT_ENC_KEY}
      API_JWT_SECRET: ${JWT_SECRET}
      METRICS_JWT_SECRET: ${JWT_SECRET}
      REGION: local
      ERL_AFLAGS: -proto_dist inet_tcp
      POOLER_TENANT_ID: ${POOLER_TENANT_ID}
      POOLER_DEFAULT_POOL_SIZE: ${POOLER_DEFAULT_POOL_SIZE}
      POOLER_MAX_CLIENT_CONN: ${POOLER_MAX_CLIENT_CONN}
      POOLER_POOL_MODE: transaction
      DB_POOL_SIZE: ${POOLER_DB_POOL_SIZE}
    command:
      [
        "/bin/sh",
        "-c",
        "/app/bin/migrate && /app/bin/supavisor eval \"$$(cat /etc/pooler/pooler.exs)\" && /app/bin/server"
      ]

volumes:
  db-config:

Step 3. 컨테이너 실행

$ docker-compose up -d

Step 4. 접속 테스트 및 환경 확인

http://localhost:3000  (Supabase Studio 접속)
http://localhost:5432  (PostgreSQL 접속, ID: postgres, PW: postgres)
http://localhost:8000/rest/v1  (자동 생성된 API)

언제 Go 언어가 괜찮을까?

추억을 백앤드하자 — Tue, 20 Jan 2026 10:18:10 +0900

Go 언어

Go 언어는 goroutine 기반 병행성 모델과 빠른 컴파일 속도를 바탕으로 I/O 중심 서버에 강점을 가진다.
Spring Boot 환경에서 운영 중인 서비스 중 일부는 Go로 전환했을 때 성능과 비용 측면에서 더 큰 이점을 얻을 수 있다.
필자는 Spring Boot 를 주로 사용하는데 그러면 만약 Go로 전환하면 가장 효과가 좋은 영역은 어디인가?

✅ 1. 트래픽 많고 단순한 API 서버

예

조회(Read) 위주의 API
단순 CRUD
인증 토큰 검증
외부 시스템 중계 API (Proxy)

왜 Go가 좋은가

JVM 힙/GC 부담 없음
메모리 사용량 작음
빠른 cold start → 컨테이너/서버리스에 유리
TPS 대비 비용 효율 좋음

Spring Boot API Gateway / Edge API → Go
(특히 BFF, API Gateway 성격이면 매우 좋음)

✅ 2. 메시지 기반 Consumer / Worker

예

Kafka / RabbitMQ / IBM MQ Consumer
이벤트 처리기
비동기 작업 Worker
로그 처리, 변환기

왜 Go가 좋은가

goroutine으로 동시성 처리 매우 쉬움
long-running process에 안정적
CPU/메모리 효율 뛰어남
컨테이너로 여러 개 띄우기 쉬움

Spring @KafkaListener / @JmsListener → Go Consumer

✅ 3. 배치성 작업 / 스케줄러

예

정기 데이터 수집
파일 변환
외부 API polling
ETL 전처리

왜 Go가 좋은가

단일 바이너리 배포
크론 + Go 조합 단순
Spring Batch 대비 구조 단순

Spring Batch → Go CLI / Worker

2️⃣ Go로 전환해도 되지만 신중해야 할 영역

⚠️ 4. 비즈니스 로직이 복잡한 핵심 도메인

예

결제
정산
복잡한 트랜잭션
DDD 기반 도메인 로직

이유

Spring의 강점:
- 트랜잭션 관리
- AOP
- Validation
- JPA/Hibernate
Go는 직접 다 만들어야 함

이 영역은 Spring 유지 + 주변부만 Go 전환 추천

⚠️ 5. 관리자 페이지 / 백오피스

Spring + JPA + Security 조합이 생산성 좋음
Go는 ORM, Admin UI 모두 직접 구성 필요

3️⃣ 거의 안 건드리는 게 좋은 영역

❌ 6. 복잡한 ORM 기반 대규모 CRUD

JPA Entity 많음
Lazy loading 의존
복잡한 연관관계

이걸 Go로 옮기면 생산성 급감

go 설치

1.Go 설치

https://go.dev/dl/

2.환경변수

go를 설치할때 기본적으로 c드라이브에 설치하면 환경변수 작업을 안해줘도 되지만 내가 원하는 위치에 설치하고 싶을 경우 환경변수 설정을 해줘야 한다.

필자는 d드라이브에 설치했기 때문에 GOROOT 변수에 대한 경로를 잡아줘야 한다.

참고)원하는 위치에 go 설치시 go 폴더를 먼저 만들어주고 그 안에 go를 설치해야 한다.

3.vs code에서 확인하기

main.go 파일을 만들어주고 터미널에서 go 버전을 확인하자.

정상확인이 되었으면 잘 세팅 되었다는것이다.

$ go version

4.go의 폴더구조

go 1.10 이전버전(GOPATH 방식)

go에서 프로젝트 파일을 만드려고 한다면 일단

src 하위에 만들어야 한다.

그리고 주로 도메인/유저이름 구조로 생성되도록 권장된다.

GOPATH
 └─ src
     └─ github.com
         └─ username
             └─ myapp
                 └─ main.go

1.17+(GO Modules 방식)

D:\projects\myapp
 ├─ go.mod
 ├─ main.go
 └─ internal/

✔ GOPATH 필요 없음
✔ src 필요 없음
✔ 디렉토리 자유

go 모듈으로 실행시 초기설정

go mod init learngo //루트 폴더 설정

go 문법

접근자

대문자로 시작하는 메서드는 public 메서드이다.

something.go

package something

import "fmt"

/*
*  private
*/
func sayBye() {
    fmt.Println("Bye")
}

/*
*  public
*/
func SayHello() {
    fmt.Println("Hello")
}

main.go

package main

import (
    "fmt"

    "github.com/learngo/something"
)

func main() {
    fmt.Println("Hello World!")
    something.SayHello()
}

변수와 상수

go는 타입언어이다.

상수

package main

import "fmt"

func main() {
    const name string = "jyj"
    //const name = "jyj"  이런식으로 타입 추론도 가능
    fmt.Println(name)
}

//결과
jyj

상수로 선언했기 때문에 변경할 수 없고 변경시 에러가 발생한다.

func main() {
    const name string = "jyj"
    name = "test" //컴파일 단계 에러 발생
    fmt.Println(name)
}

변수

방법1

func main() {
    var name string = "jyj"
    name = "test"
    fmt.Println(name)
}

//결과
test

방법2

아래와 같이 타입 추론을 이용하여 선언도 가능하다.

package main

import "fmt"

func main() {
    name := "jyj"
    name = "test"
    fmt.Println(name)
}

변수의 타입추론시 첫번째 값을 기준으로 추론되기 때문에

name 값을 string으로 선언했가 때문에 다음에 name에 bool 값인 false를 넣으면 에러가 난다.

package main

import "fmt"

func main() {
    name := "jyj"
    name = false //컴파일 단계 에러 발생
    fmt.Println(name)
}

다양한 타입들

https://go101.org/article/type-system-overview.html

파라미터와 반환값

파라미터와 반환값에는 모두 타입이 명시되어 있어야 한다.

package main

import "fmt"

func multiply(a int, b int) int {
    return a * b
}

func main() {
    fmt.Println(multiply(2, 2))
}

파라미터 a,b의 타입이 같다면 아래와 같이 작성 가능하다.

func multiply(a,b int) int {
    return a * b
}

멀티 value

go는 다른 언어와 달리 다양한 타입을 동시에 return 해줄 수 있다.

package main

import (
    "fmt"
    "strings"
)

func lenAndUpper(name string) (int, string) {
    return len(name), strings.ToUpper(name)
}

func main() {
    totalLength, upperName := lenAndUpper("yjy")
    fmt.Println(totalLength, upperName)
}

//결과 
3 YJY

리턴 개수가 여러개일때 1개의 값만 받고 싶다면, 언더바(_)를 이용하자

func main() {
    totalLength, _ := lenAndUpper("yjy")
    fmt.Println(totalLength)
}

//결과 
3

여러개의 파라미터 처리

파라미터에 ... 선언만 해주면 여러 파라미터를 받을 수 있다.

package main

import "fmt"

func repeatMe(words ...string) {
    fmt.Println(words)
}

func main() {
    repeatMe("yjy", "test", "hi", "hello")
}

//결과
[yjy test hi hello]

naked return

return 만 적어주고 대상을 선언 할 필요가 없다

일반적인 V1을 naked return을 적용해 V2로 만들었다.

import (
    "fmt"
    "strings"
)

func lenAndUpperV1(name string) (int, string) {
    return len(name), strings.ToUpper(name)
}

func lenAndUpperV2(name string) (lenght int, uppercase string) {
    lenght = len(name)
    uppercase = strings.ToUpper(name)
    return
}

func main() {
    totalLength, upperName := lenAndUpperV2("yjy")
    fmt.Println(totalLength, upperName)
}

//결과
3 YJY

defer

function이 끝났을때 다른 작업을 실행시키고 싶을때

lenAndUpperV2의 작업이 모두 끝나고 나서 defer fmt.Println("I'm done")이 실행된다.

package main

import (
    "fmt"
    "strings"
)

func lenAndUpperV2(name string) (lenght int, uppercase string) {
    defer fmt.Println("I'm done")
    lenght = len(name)
    uppercase = strings.ToUpper(name)
    return
}

func main() {
    totalLength, upperName := lenAndUpperV2("yjy")
    fmt.Println(totalLength, upperName)
}

//결과
I'm done
3 YJY

for, range, ...args

go의 기본 loop는 오로지 for만 존재한다.

for 사용

package main

import (
    "fmt"
)

func superAdd(numbers ...int) int {
    for i := 0; i < len(numbers); i++ {
        fmt.Println(i)
    }
    return 1
}

func main() {
    superAdd(1, 2, 3, 4, 5, 6)
}
//결과
0
1
2
3
4
5

range 키워드 사용

인덱스만 출력

package main

import (
    "fmt"
)

func superAdd(numbers ...int) int {
    for number := range numbers {
        fmt.Println(number)
    }
    return 1
}

func main() {
    superAdd(1, 2, 3, 4, 5, 6)
}

//결과
0
1
2
3
4
5

인덱스와 값 같이 출력

package main

import (
    "fmt"
)

func superAdd(numbers ...int) int {
    for index, number := range numbers {
        fmt.Println(index, number)
    }
    return 1
}

func main() {
    superAdd(1, 2, 3, 4, 5, 6)
}

//결과
0 1
1 2
2 3
3 4
4 5
5 6

값만 출력하고 싶을 경우

func superAdd(numbers ...int) int {
    for _, number := range numbers {
        fmt.Println(index, number)
    }
    return 1
}

합계를 구하자

package main

import "fmt"

func superAdd(numbers ...int) int {
    total := 0
    for _, number := range numbers {
        total += number
    }
    return total
}

func main() {
    result := superAdd(1, 2, 3, 4, 5, 6)
    fmt.Println(result)
}

//결과
21

if, else

package main

import "fmt"

func canIDrink(age int) bool {
    if age < 18 {
        return false
    } else {
        return true
    }
}

func main() {
    fmt.Println(canIDrink(16))
}

//결과
false

if에 변수 적용

package main

import "fmt"

func canIDrink(age int) bool {
    if koreanAge := age + 2; koreanAge < 18 {
        return false
    } else {
        return true
    }
}

func main() {
    fmt.Println(canIDrink(16))
}
//결과
true

Switch

package main

import "fmt"

func canIDrinkV1(age int) bool {
    switch age {
    case 10:
        return false
    case 18:
        return true
    }
    return false
}

func canIDrinkV2(age int) bool {
    switch {
    case age < 18:
        return false
    case age == 18:
        return true
    case age > 50:
        return false
    }
    return false
}

func canIDrinkV3(age int) bool {
    switch koreanAge := age + 2; koreanAge {
    case 10:
        return false
    case 18:
        return true
    }
    return false
}

func main() {
    fmt.Println(canIDrinkV1(18))
    fmt.Println(canIDrinkV2(18))
    fmt.Println(canIDrinkV3(18))
}

//결과
true
true
false

Pointer

&는 메모리 주소

func main() {
    a := 2
    b := &a
    a = 10

    fmt.Println(a, b)
    fmt.Println(&a, b)
}

//결과
10 0xc00000a098
0xc00000a098 0xc00000a098

*은 메모리 주소가 가르키는 실제값을 가르킨다.

package main

import "fmt"

func main() {
    a := 2
    b := &a
    a = 5

    fmt.Println(*b)
}

//결과
5

func change(x *int) {
    *x = 20
}

a := 10
change(&a)
fmt.Println(a) // 20

package main

import "fmt"

func main() {
    a := 2
    b := &a
    *b = 20

    fmt.Println(a) //20
}

Arrays and Slices

Arrays

package main

import "fmt"

func main() {
    //사이즈 선언
    namesV1 := [3]string{"yjy", "hi", "hello"}
    namesV1[3] = "lala" //에러

    //사이즈 미선언시 slice 라고도 부른다
    namesV2 := []string{"yjy", "hi", "hello"}
    namesV2[3] = "lala"

    fmt.Println(namesV1)
    fmt.Println(namesV2)
}

Slices

package main

import "fmt"

func main() {
    names := []string{"yjy", "hi", "hello"}
    fmt.Println(names)

    names = append(names, "test")
    fmt.Println(names)
}

//결과
[yjy hi hello]
[yjy hi hello test]

Maps

map[키의타입 선언]value의타입선언

package main

import "fmt"

func main() {
    yjy := map[string]string{"name": "yjy", "age": "30"}
    fmt.Println(yjy)
}

추가

요소확인 여부

struct

package main

import "fmt"

type person struct {
    name    string
    age     int
    favFood []string
}

func main() {
    favFood := []string{"chicken, pizza"}
    // 가독성 좋음
    yjy := person{name: "yjy", age: 30, favFood: favFood}
    // 가독성 않좋음
    // yjy := person{"yjy", 30, favFood}
    fmt.Println(yjy)
}

struct에서도 소문자면 private 대문자면 public 이다

struct의 속성도 마찬가지이다.

//private
type person struct {
    name    string
    age     int
    favFood []string
}

//public
type Person struct {
    Name    string
    Age     int
    FavFood []string
}

function을 이용한 생성자 개념만들기

go에는 생성자가 따로 없다. 그래서 만들어 줘야 한다.

accounts.go

package accounts

// Account struct
type Account struct {
    owner   string
    balance int
}

// NewAccount creates Account
// &account을 리턴함으로서 새로 만들어진 account의 주소값을 반환한다.
// 늘 복사하면 프로그램 속도는 느려진다.
func NewAccount(owner string) *Account {
    account := Account{owner: owner, balance: 0}
    return &account
}

/*
    ✔️ 값 타입으로 리턴하면
    func NewAccount(owner string) Account {
        return Account{owner: owner, balance: 0}
    }


    호출 시점에 Account 전체가 복사
    필드가 많아질수록 복사 비용 증가
    이후 수정 시 또 복사 발생 가능

    ✔️ 포인터로 리턴하면
    주소값(8바이트)만 복사
    구조체 크기와 무관
    동일 객체를 여러 곳에서 공유 가능
      그래서 구조체가 클수록 포인터 반환이 유리
*/

main.go

package main

import (
    "fmt"

    "github.com/learngo/accounts"
)

func main() {
    account := accounts.NewAccount("yjy")
    fmt.Println(account)
}

//결과
&{yjy 0}

receiver

Deposit 이라는 함수는 a라는 receiver를 갖고있다.

receiver는 struct의 첫 글자를 따서 소문자로 지어야 한다.

struct 가 Account 라면은 a 로 지어야 한다.

메서드 개념이라고 생각하면 편하다.

accounts.go

Deposit 이라는 메서드를 만들었다.

func NewAccount(owner string) *Account {
    account := Account{owner: owner, balance: 0}
    return &account
}

func (a Account) Deposit(amount int) {
    a.balance += amount
}

main.go

package main

import (
    "fmt"

    "github.com/learngo/accounts"
)

func main() {
    account := accounts.NewAccount("yjy")
    account.Deposit(10)

    fmt.Println(account.Balance())
}

//결과
0

결과가 0이 나왔다 왜그럴까?

NewAccount를 통해서 account 값을 먼저 만들었다. 그리고 Deposit을 통해 balance를 증가시키려고 한다. 아래 Deposit의 (a Account)에서 go는 복사값을 만든다. 그래서 원본값이 변하지 않는것이다.

func NewAccount(owner string) *Account {
    account := Account{owner: owner, balance: 0}
    return &account
}

func (a Account) Deposit(amount int) {
    a.balance += amount
}

때로는 메서드안에서 안전하게 복사값을 만들어서 핸들링하고 싶다면 이처럼 써도 되지만 원본값이 변경되야 하는 경우는 변경되야한다.

변경후

func (a *Account) Deposit(amount int) {
    a.balance += amount
}

main.go

...
func main() {
    account := accounts.NewAccount("yjy")
    account.Deposit(10)

    fmt.Println(account.Balance())
}

//결과
10

결과가 10으로써 의도대로 동작한다!.

error 핸들링

go는 exception이 따로 없기 때문에 error를 직접 핸들링 해줘야 한다.

accounts.go

...
// Withdraw x amount from your account
func (a *Account) Withdraw(amount int) error {
    if a.balance < amount {
        return errors.New("돈이 부족합니다")
    }
    a.balance -= amount
    return nil
}

main.go

package main

import (
    "fmt"
    "github.com/learngo/accounts"
)

func main() {
    account := accounts.NewAccount("yjy")
    account.Deposit(10)

    fmt.Println(account.Balance())

    err := account.Withdraw(20)
    //프로그램 종료
    //log.Fatalln(err)

    //주로 error 핸들링 방법
    if err != nil {
        fmt.Println(err)
    }

    fmt.Println(account.Balance())
}

//결과
10
돈이 부족합니다
10

다양한 에러들이 존재한다면?

error 들을 변수로 선언하고 사용하자

...
var errNoMoney = errors.New("돈이 없습니다.")

// Withdraw x amount from your account
func (a *Account) Withdraw(amount int) error {
    if a.balance < amount {
        return errNoMoney
    }
    a.balance -= amount
    return nil
}

참고사항) nil에 대해

`nil`이 될 수 있는 타입들

Go에서 nil은 “아무것도 가리키지 않음(없음)” 을 의미하는 미리 정의된 식별자(predeclared identifier) 입니다.

✅ nil 가능

포인터 (*T)
슬라이스 ([]T)
맵 (map[K]V)
채널 (chan T)
함수 (func)
인터페이스 (interface)

❌ nil 불가

기본 타입: int, string, bool, struct, array

String 재정의

obj 호출시 go는 내부적으로 String 함수를 호출하게 되는데 해당 함수를 재정의할 수 있다.

accounts.go

...
func (a Account) String() string {
    return fmt.Sprint(a.Owner(), "'s account. \nHas: ", a.Balance())
}

main.go

func main() {
    account := accounts.NewAccount("yjy")

    fmt.Println(account)
}

//결과
yjy's account. 
Has: 10

Dictionary

struct 말고도 Dictionary를 통해 타입을 만들 수 있다.

mydict.go

package mydict

// Dictionary  type
type Dictionary map[string]string

main.go

package main

import (
    "fmt"

    "github.com/learngo/mydict"
)

func main() {
    dictionary := mydict.Dictionary{"first": "First word"}
    fmt.Println(dictionary)
}

//결과
map[first:First word]

Dictionary만의 메서드 만들기

Search라는 메서드를 만들었다.

mydict.go

package mydict

import "errors"

// Dictionary  type
type Dictionary map[string]string

var errNotFound = errors.New("Not Found")

// Search for a word
func (d Dictionary) Search(word string) (string, error) {
    value, exists := d[word]
    if exists {
        return value, nil
    }
    return "", errNotFound
}

main.go

package main

import (
    "fmt"

    "github.com/learngo/mydict"
)

func main() {
    dictionary := mydict.Dictionary{"first": "First word"}
    definition, err := dictionary.Search("second")
    if err != nil {
        fmt.Println(err)
    } else {
        fmt.Println(definition)
    }
}


//결과
Not Found

Add 메서드 만들기

mydict.go

...
var errNotFound = errors.New("Not Found")
var errWordExists = errors.New("Word already Exists")

func (d Dictionary) Add(word, def string) error {
    _, err := d.Search(word)
    switch err {
    case errNotFound:
        d[word] = def
    case nil:
        return errWordExists
    }
    return nil
}

main.go

package main

import (
    "fmt"
    "github.com/learngo/mydict"
)

func main() {
    dictionary := mydict.Dictionary{"first": "First word"}
    word := "hello"
    definition := "Greeting"

    err := dictionary.Add(word, definition)
    if err != nil {
        fmt.Println(err)
    }

    hello, _ := dictionary.Search(word)
    fmt.Println("found", word, ", definition:", hello)

    err2 := dictionary.Add(word, definition)
    if err2 != nil {
        fmt.Println(err2)
    }

}

Update 메서드 만들기

mydict.go

...
var errNotFound = errors.New("Not Found")
var errWordExists = errors.New("Word already Exists")
var errCantUpdate = errors.New("Cant update non-existing word")

// Update a word
func (d Dictionary) Update(word, def string) error {
    _, err := d.Search(word)
    switch err {
    case nil:
        d[word] = def
    case errNotFound:
        return errCantUpdate
    }
    return nil
}

main.do

package main

import (
    "fmt"

    "github.com/learngo/mydict"
)

func main() {
    dictionary := mydict.Dictionary{"first": "First word"}
    word := "hello"

    dictionary.Add(word, "First")
    dictionary.Update(word, "Second")

    result, _ := dictionary.Search(word)
    fmt.Println(result)
}

//결과
Second

Delete 메서드 만들기

mydict.go

...
func (d Dictionary) Delete(word string) {
    delete(d, word)
}

main.go

package main

import (
    "fmt"

    "github.com/learngo/mydict"
)

func main() {
    dictionary := mydict.Dictionary{"first": "First word"}
    word := "hello"

    dictionary.Add(word, "First")
    dictionary.Update(word, "Second")
    result, _ := dictionary.Search(word)
    fmt.Println(result)

    dictionary.Delete(word)
    result, err := dictionary.Search(word)
    if err != nil {
        fmt.Println(err)
    } else {
        fmt.Println(result)
    }
}

//결과
Second
Not Found

URL Checker 만들기

하나씩 순서대로 URL을 처리하는 기능을 만들었다.

main.go

package main

import (
    "errors"
    "fmt"
    "net/http"
)

func main() {
    var results = map[string]string{}

    urls := []string{
        "https://www.google.com/",
        "https://www.naver.com/",
        "https://www.reddit.com/",
        "https://www.airbnb.com/",
    }

    for _, url := range urls {
        result := "OK"
        err := hitUrl(url)
        if err != nil {
            result = "FAILED"
        }
        results[url] = result
    }

    for url, result := range results {
        fmt.Println(url, result)
    }
}

var errRequestFailed = errors.New("Request Failed")

func hitUrl(url string) error {
    fmt.Println("Checing: ", url)
    resp, err := http.Get(url)
    if err != nil || resp.StatusCode >= 400 {
        fmt.Println(err, resp.StatusCode)
        return errRequestFailed
    }
    return nil

}

//결과
Checing:  https://www.google.com/
Checing:  https://www.naver.com/
Checing:  https://www.reddit.com/
Checing:  https://www.airbnb.com/
https://www.google.com/ OK
https://www.naver.com/ OK
https://www.reddit.com/ OK
https://www.airbnb.com/ OK

여기서 알면 좋은 부분은 아래부분을

var results = map[string]string{}

이렇게 써도 된다.

var results = make(map[string]string)

capacity 값이 고정이라면 이렇게도 가능하다.

results := make(map[string]string, 1000)

아래와 같은 케이스도 있다.

var results map[string]string

fmt.Println(results == nil) // true
results["a"] = "1"          // panic!

초기화를 하지 않고 선언을 할 수 있다. 선언만 하면 아무의미 없는 값으로 nil 이라는 값을 갖고 있지만 값을 추가하는 행동따윈 할 수 없다.

Goroutines

고루틴이란 기본적으로 다른 함수와 동시에 실행시키는 함수

아래와 같이 순차적으로 동작하는 Top-down 방식이 일반적인 프로그래밍 방식이다. 총 20초가 걸렸다.

main.go

package main

import (
    "fmt"
    "time"
)

func main() {
    sexyCount("yjy")
    sexyCount("kkk")
}

func sexyCount(person string) {
    for i := 0; i < 10; i++ {
        fmt.Println(person, "is sexy", i)
        time.Sleep(time.Second)
    }
}

//결과
yjy is sexy 0
yjy is sexy 1
yjy is sexy 2
yjy is sexy 3
yjy is sexy 4
yjy is sexy 5
yjy is sexy 6
yjy is sexy 7
yjy is sexy 8
yjy is sexy 9
kkk is sexy 0
kkk is sexy 1
kkk is sexy 2
kkk is sexy 3
kkk is sexy 4
kkk is sexy 5
kkk is sexy 6
kkk is sexy 7
kkk is sexy 8
kkk is sexy 9

고루틴을 적용하면 병행처리하여 10초에 처리할 수 있다.

앞에 go 키워드만 추가해주면 된다.

func main() {
    go sexyCount("yjy")
    sexyCount("kkk")
}
...

//결과
kkk is sexy 0
yjy is sexy 0
yjy is sexy 1
kkk is sexy 1
kkk is sexy 2
yjy is sexy 2
yjy is sexy 3
kkk is sexy 3
kkk is sexy 4
yjy is sexy 4
yjy is sexy 5
kkk is sexy 5
kkk is sexy 6
yjy is sexy 6
yjy is sexy 7
kkk is sexy 7
kkk is sexy 8
yjy is sexy 8
yjy is sexy 9
kkk is sexy 9

다만 주의할 점이 있다. 이렇게 go 키워드를 모두 추가하여 더이상 main 함수가 할일이 없어지게되면 main 함수 자체가 바로 종료되어서 아무 작업도 할 수 없게 된다. 이것의 고루틴의 약속이다.

func main() {
    go sexyCount("yjy")
    go sexyCount("kkk")
}
...

아래와 같은 방식은 고루틴이 yjy를 담당하고 kkk를 main이 작업을 담당했기 때문에 가능햇던것이다.

func main() {
    go sexyCount("yjy")
    sexyCount("kkk")
}

둘다 go 키워드를 적용해보고 main에게 따로 할일을 주면 동작할 것이다.

main에게 5초동안 기다리라는 작업을 주었고 정말 5초동안 고루틴에의해 병렬동시 실행이 된것을 확인할 수 있다.

func main() {
    go sexyCount("yjy")
    go sexyCount("kkk")
    time.Sleep(time.Second * 5)
}

//결과
kkk is sexy 0
yjy is sexy 0
yjy is sexy 1
kkk is sexy 1
kkk is sexy 2
yjy is sexy 2
yjy is sexy 3
kkk is sexy 3
kkk is sexy 4
yjy is sexy 4

func main(){
    go playYadong()
    go sex()
    time.Sleep(time.Second * 5)
}

Channels

channel은 고루틴과 메인함수 사이 혹은 고루틴끼리의 정보를 전달하기 위한 방법이다.

고루틴이 동작하기 위해서는 결국 main 함수가 어떤일을 하고 있어야만 실행이 가능한데 항상 sleep만 하고 있을수는 없는일이다.

때문에 channel을 이용하여 고루틴으로 부터 완료된 내용을 수신하는 역할을 main 함수가 하면 될것이다.

그래서 핵심은 main 함수에게 할일을 주어 고루틴의 작업이 멈추지 않도록 하는것.

main.go

package main

import (
    "fmt"
    "time"
)

func main() {
    c := make(chan bool) // bool 타입의 결과를 받을 채널 선언

    people := [4]string{"yjy", "kkk", "jjj", "mmm"}
    for _, person := range people {
        go isSexy(person, c)
    }

    for i := 0; i < len(people); i++ {
        fmt.Println(<-c) // 채널로부터 값을 가져오는 오퍼레이션은 blocking 오퍼레이션이다,
    }
}

func isSexy(person string, c chan bool) {
    time.Sleep(time.Second * 5)
    c <- true // 채널에게 true값을 전달
}

//결과
waiting for  0
mmm is sexy
waiting for  1
jjj is sexy
waiting for  2
kkk is sexy
waiting for  3
yjy is sexy

고루틴의 Concurrency 때문에 people의 배열 순서와 결과값의 순서가 같지 않게됨을 확인 할 수 있다.

참고)

헷갈리지 말자 c<-"data" 데이터를 채널에 넣는다. <-c 데이터를 채널에서 가져온다.

고루틴,채널을 적용하여 URL Checker 다시 만들어보기

기존 main.go

package main

import (
    "errors"
    "fmt"
    "net/http"
)

func main() {
    var results = map[string]string{}

    urls := []string{
        "https://www.google.com/",
        "https://www.naver.com/",
        "https://www.reddit.com/",
        "https://www.airbnb.com/",
    }

    for _, url := range urls {
        result := "OK"
        err := hitUrl(url)
        if err != nil {
            result = "FAILED"
        }
        results[url] = result
    }

    for url, result := range results {
        fmt.Println(url, result)
    }
}

var errRequestFailed = errors.New("Request Failed")

func hitUrl(url string) error {
    fmt.Println("Checing: ", url)
    resp, err := http.Get(url)
    if err != nil || resp.StatusCode >= 400 {
        fmt.Println(err, resp.StatusCode)
        return errRequestFailed
    }
    return nil
}

고루틴 적용후 main.go

package main

import (
    "errors"
    "fmt"
    "net/http"
)

type result struct {
    url    string
    status string
}

var errRequestFailed = errors.New("Request Failed")

func main() {
    results := map[string]string{}
    c := make(chan result)

    urls := []string{
        "https://www.google.com/",
        "https://www.naver.com/",
        "https://www.reddit.com/",
        "https://www.airbnb.com/",
    }

    for _, url := range urls {
        go hitUrl(url, c)
    }

    for i := 0; i < len(urls); i++ {
        result := <-c
        results[result.url] = result.status
    }

    for url, status := range results {
        fmt.Println(url, status)
    }
}

// 해당 채널은 받을 수는 없고 보내기만 가능(c chan<- result)
func hitUrl(url string, c chan<- result) {
    fmt.Println("Checing: ", url)
    // fmt.Println(<-c), 에러발생!, 채널을 c chan<- result 이런식으로 받을수만 있게 선언했기 때문에 채널에서 꺼내올수는 없다.

    resp, err := http.Get(url)
    status := "OK"
    if err != nil || resp.StatusCode >= 400 {
        status = "FAILED"
    }

    c <- result{url: url, status: status}
}

BY 윤주영.

출처:

https://nomadcoders.co/go-for-beginners/

기억의 파편들

로컬 LLM 기반 AI Code Reviewer 구축기 - 단순 코드 리뷰를 넘어 아키텍처 리뷰까지

로컬 LLM 기반 AI Code Reviewer 구축기 - 단순 코드 리뷰를 넘어 아키텍처 리뷰까지

들어가며

시스템 아키텍처

왜 Diff만으로는 부족했을까?

코드 리뷰와 아키텍처 리뷰를 분리하다

Code Review

Architecture Review

AGENTS.md 도입

변경 파일 전체 코드 수집

프로젝트 규칙을 모르는 AI는 좋은 리뷰어가 아니다

앞으로 개선할 내용

RAG 기반 프로젝트 컨텍스트 검색

테스트 결과 기반 리뷰

프로젝트 히스토리 기반 리뷰

마치며

PolyCARP를 활용한 드론 Geofence/Area 공간 판단 구현기 - 좌표계, 경계선 그리고 수많은 삽질들

PolyCARP를 활용한 드론 Geofence/Area 공간 판단 구현기 - 좌표계, 경계선 그리고 수많은 삽질들

왜 PolyCARP를 선택했는가

첫 번째 문제 - 위경도는 생각보다 계산하기 어렵다

두 번째 문제 - GeoJSON 좌표 순서 함정

세 번째 문제 - Polygon 내부 판정 버그

네 번째 문제 - 고도 단위(ft / m)

다섯 번째 문제 - Geofence와 Area는 복귀 방향이 반대다

최종 구조

마무리

드론 안전 제어 시스템을 설계하며 고민했던 것들

첫 번째 고민: 모든 판단을 하나의 서비스에서 처리할 것인가

도메인별로 책임을 분리하기

판단과 부수효과를 분리하기

MQ 장애가 안전 판단을 막아서는 안 된다

가장 어려웠던 부분은 우선순위였다

마무리

쿠버네티스 정리2

Controller

Controller 옵션

Template

Replicas

Selector

Deployment

ReCreate

Rolling Update

Blue/Green

Canary

Controller - DaemonSet, Job ,CronJob

목적

DaemonSet

Job, CronJob

특징

DaemonSet

Job

CronJob

쿠버네티스 정리1

쿠버네티스

Overview

Pod

Service

ClusterIP

NodePort

Controller Service (외부 노출)

Volume

[K8s] 쿠버네티스 사설 레지스트리 구축 및 x509: certificate signed by unknown authority 에러 해결 가이드

[K8s] 쿠버네티스 사설 레지스트리 구축 및 x509: certificate signed by unknown authority 에러 해결 가이드

사설 TLS 인증서 생성 (OpenSSL)

인증서 생성 명령어

왜 subjectAltName이 중요한가요?

쿠버네티스 Secret 등록

1. 사설 레지스트리(Private Registry) 배포 설정

Registry Deployment & Service YAML

2. 트러블슈팅: x509 인증서 에러 해결 (CentOS/RHEL)

단계 1: 시스템 인증서 저장소에 등록

단계 2: containerd 설정 최적화 (핵심 포인트)

단계 3: 서비스 완전 재시작

3. 대규모 환경에서의 자동화 (Ansible)

4. 서비스 노출 시 포트 매핑 이해

요약 및 결론

Next.js에서 통합 테스트 환경 구축하기 (Vitest)

Next.js에서 Supabase 실무 통합 테스트 환경 구축하기 (Vitest)

️ 1. 필수 패키지 설치

왜 `subjectAltName`이 중요한가요?

`vitest.config.ts` 생성

`vitest.setup.ts` 생성

`.env.test` 파일 예시

`package.json` 스크립트 추가

`supabaseService.ts` (원본 코드)

`supabaseService.test.ts` (테스트 코드)

Step 2. `.env` 파일 핵심 설정 (필수 수정)

`nil`이 될 수 있는 타입들