글
2026
- 트러블슈팅
PostgreSQL에서 OFFSET이 음수면 'must not be negative'로 쿼리가 실패한다
페이지 번호를 0이나 음수로 받으면 (page-1)*size 계산이 음수 OFFSET을 만들어 PostgreSQL이 쿼리를 거부하고 목록 API가 500을 반환한다. 원인과, 페이지 번호를 서버에서 유효 범위로 보정하는 해결을 정리한다.
- 인사이트
노출 기간이 있는 데이터는 클라이언트에서 다시 판정하지 마라
서버가 '지금 노출할' 항목만 내려줬는데 클라이언트가 start/end 시각으로 다시 필터링하면, 시계가 틀어진 브라우저에서만 항목이 사라지는 재현 불가 버그가 생긴다. 시간 기반 노출 판정을 서버 단일 시계로 통일하는 이유와 경계 조건을 정리한다.
- 트러블슈팅
Next.js 16에서 hydration mismatch가 나는 진짜 이유
서버와 클라이언트의 렌더 결과가 갈리는 대표 원인 4가지와, 각각을 어떻게 특정하고 고치는지 실제 스택트레이스로 정리한다.
- 인사이트
pnpm에서 ERR_MODULE_NOT_FOUND가 뜰 때: strict 격리와 peer dependency
npm에서는 되던 코드가 pnpm에서만 모듈을 못 찾는 이유를 node_modules 구조 차이로 설명하고, 올바른 해결책과 피해야 할 우회책을 구분한다.
2025
- 트러블슈팅
docker login에서 'server gave HTTP response to HTTPS client'가 날 때
HTTP로 띄운 Harbor에 docker login을 하면 Docker가 HTTPS로 접속을 시도해 실패한다. daemon.json의 insecure-registries에 레지스트리를 등록해 해결하는 방법과, 이미지 태그·push·pull 경로 규칙을 정리한다.
- 노트
Docker 설치와 베이스 이미지 만들기 — JDK 21 / Node 20 공통 이미지
Ubuntu에 Docker Engine과 Compose를 설치하고, 여러 서비스의 Dockerfile이 공통으로 재사용할 베이스 이미지를 만드는 과정을 정리한다. 베이스 이미지를 따로 두는 이유와 실제 빌드 결과 크기까지 다룬다.
- 노트
VM에 GitLab 설치하고 root 비밀번호 재설정하기
Ubuntu VM에 gitlab-ee를 설치하고 external_url을 설정해 접속하기까지의 과정, 그리고 initial_root_password 파일이 24시간 뒤 삭제된 상황에서 gitlab-rails console로 root 비밀번호를 재설정하는 방법을 정리한다.
- 노트
GitLab과 SonarQube 연동하기 — sonar-scanner·gitlab-runner 설치부터 Quality Gate까지
GitLab CI 파이프라인에서 SonarQube 정적 분석을 돌리기까지 필요한 설정을 순서대로 정리한다. SonarQube의 GitLab 연동, project analysis token 발급, gitlab-runner 등록, CI/CD 변수 주입, 그리고 Gradle·JS 프로젝트별 스캐너 설정을 다룬다.
- 노트
Harbor 설치와 프로젝트 생성 — offline installer로 컨테이너 레지스트리 띄우기
Harbor offline installer로 사설 컨테이너 레지스트리를 구성하는 과정을 정리한다. harbor.yml의 hostname·port·admin 비밀번호 설정, install.sh 실행, 그리고 기동된 9개 컨테이너 확인과 프로젝트 생성까지 다룬다.
- 노트
Jenkins에 GitLab 연동 설정하기 — API token과 저장소 인증 자격증명 두 개가 필요하다
Jenkins와 GitLab을 붙일 때 필요한 자격증명은 하나가 아니라 둘이다. GitLab 연결용 API token과 Job이 저장소를 clone할 때 쓰는 Username with password를 각각 등록해야 하는 이유와 등록 위치를 정리한다.
- 노트
Ubuntu에 Jenkins 설치하기 — 포트 변경과 journald 로그 확인
Ubuntu에 OpenJDK 21과 Jenkins를 설치하고 기본 포트를 8080에서 바꾸는 방법, 그리고 Jenkins 로그가 파일로 남지 않는 이유와 journalctl로 확인하는 방법을 정리한다.
- 노트
Jenkins Job 3개로 백엔드 이미지를 빌드해 Harbor에 push하기
Gradle 빌드, Docker 이미지 빌드, 레지스트리 push를 하나의 Job에 몰지 않고 세 개의 FreeStyle Job으로 쪼개서 연결한 구성을 정리한다. artifact 전달은 Archive the artifacts와 Copy artifacts from another project로 처리한다.
- 노트
Jenkins Job 3개로 프런트엔드 이미지를 빌드해 Harbor에 push하기
NodeJS 툴 설정부터 pnpm 빌드, Docker 이미지 빌드, Harbor push까지 프런트엔드 파이프라인을 세 개의 FreeStyle Job으로 나눠 구성한 과정을 정리한다. 백엔드 구성과 다른 지점은 NodeJS 설치와 dist 산출물 전달이다.
- 노트
SonarQube 설치하기 — PostgreSQL 15 연동과 vm.max_map_count 설정
Ubuntu에 PostgreSQL 15와 SonarQube Community 버전을 설치하고 연결하는 과정을 정리한다. DB·사용자 생성부터 sonar.properties의 JDBC 설정, 그리고 SonarQube가 요구하는 vm.max_map_count 커널 파라미터까지 다룬다.
2024
- 노트
axios interceptors로 JWT 인증과 공통 에러 처리를 한곳에 모으기
axios의 request/response interceptor가 then·catch보다 먼저 끼어드는 지점을 이용해 Authorization 헤더 주입과 401·5xx 공통 처리를 한곳에 모은 baseQuery 구성을 정리한다. 인증이 필요한 인스턴스와 불필요한 인스턴스를 분리하는 이유도 함께 다룬다.
- 트러블슈팅
react-query: Type 'string[]' has no properties in common with type 'InvalidateQueryFilters'
invalidateQueries에 쿼리 키 배열을 그대로 넘기면 ts(2559) 타입 에러가 난다. v5에서 인자 형태가 객체로 바뀌었기 때문이며, queryKey 속성을 가진 객체로 감싸면 해결된다.
- 트러블슈팅
vite + react + typescript에서 svg를 React 컴포넌트로 import하는 방법
svg를 컴포넌트로 쓰려고 import하면 Cannot find module ... or its corresponding type declarations(ts2307)가 난다. vite-plugin-svgr 설치만으로는 부족하고 타입 선언까지 갖춰야 하는 이유와, 쿼리 접미사 대소문자가 왜 중요한지 정리한다.
- 트러블슈팅
jsconfig.json의 checkJs와 JSON 주석이 만든 세 가지 문제
VS Code의 자동 import가 안 되던 문제를 checkJs 옵션으로 해결했지만, 같은 옵션이 js 파일에 타입 검사를 걸어 새 문제를 만들었다. 그리고 그 옵션을 JSON에서 주석 처리한 것이 yarn start를 죽였다. 세 문제의 연결 관계를 정리한다.
- 트러블슈팅
zsh: command not found: tsc — TypeScript는 프로젝트마다 설치돼 있어도 전역에는 없다
여러 프로젝트에서 TypeScript를 써 왔더라도 tsc 명령은 전역에 없을 수 있다. 프로젝트 로컬 설치와 전역 설치가 다른 이유, 그리고 tsc를 실행 가능하게 만드는 세 가지 방법을 정리한다.
- 노트
selenium과 BeautifulSoup으로 유튜브 댓글을 수집해 워드클라우드 만들기
유튜브 댓글을 수집해 형태소 분석과 워드클라우드까지 처리한 과정을 정리한다. 댓글이 무한 스크롤로 로드되는 구조를 어떻게 다뤘는지, 그리고 유튜브 DOM이 수시로 바뀌어 어제 되던 코드가 오늘 안 되는 문제를 함께 남긴다.