[IT] 클로드 코드와 함께 만든 첫걸음: Python + Vue.js + Firebird "Hello World"

[IT] 클로드 코드와 함께 만든 첫걸음: Python + Vue.js + Firebird "Hello World"

안녕하세요, 가야태자 @talkit 입니다. ^^

오늘은 MacBook에서 클로드 코드(Claude Code)와 함께 Python + Vue.js + Firebird의 Hello World를 만들어 보았습니다.

클로드 코드가 음… 도커까지 생성해주고 띄워줘서 살짝 놀라긴 했습니다만, 덕분에 아주 수월하게 첫걸음을 뗄 수 있었습니다. 지난 글들에서 기술 스택(Firebird + FastAPI + Vue.js)을 다 정해두었으니, 이제 이 셋이 실제로 서로 대화하는지 눈으로 확인해 볼 차례였거든요.

🎯 오늘의 목표

거창한 도커 컴포즈로 클라우드 배포부터 고민하기보다는, "천리길도 한걸음부터"라는 마음으로 로컬 PC에서 3계층이 서로 통신하는 최소 예제를 만드는 것이 목표였습니다.

흐름은 이렇습니다.

Vue (Vite :5173)  →  /api/hello  →  FastAPI (:8000)  →  SQLAlchemy  →  Firebird (:3050)

화면에 뜨는 "Hello World" 메시지가 하드코딩이 아니라 Firebird DB에서 읽어온 값이어야 진짜 성공인 거죠. ^^

🏗️ 구성

계층	기술	실행 위치
Database	Firebird 5.0	Docker
Backend	Python FastAPI + SQLAlchemy	Docker
Frontend	Vue 3 + Vite	로컬 (npm)

여기서 클로드 코드가 좋은 판단을 하나 해줬습니다. Firebird의 파이썬 드라이버는 fbclient라는 네이티브 라이브러리가 필요한데, 이걸 macOS에 직접 설치하려면 은근히 번거롭습니다. 그래서 DB와 백엔드는 도커 컨테이너 안에서 실행하고(fbclient 문제를 아예 회피), 앞으로 계속 손보게 될 프론트엔드만 로컬에서 핫리로드로 실행하는 구성으로 잡아주더군요. 합리적이었습니다.

🔥 클로드 코드가 도커까지 알아서

제일 놀란 부분입니다. 제가 파일을 하나하나 만들 필요 없이, 클로드 코드가

• docker-compose.yml (Firebird + 백엔드)
• 백엔드 Dockerfile (libfbclient2 포함)
• FastAPI 코드 (main.py, database.py)
• Vue 프론트엔드 (Vite 프록시 설정까지)

를 쭉 만들고, 심지어 직접 컨테이너를 빌드하고 띄운 뒤, 브라우저 화면까지 캡처해서 "동작합니다"라고 확인시켜 줬습니다. 사람이 "실행해봤어?"라고 되물을 필요가 없었어요. ^^

🐛 도중에 만난 문제 3가지 (그리고 해결)

역시 처음부터 순탄하지만은 않았습니다. 오히려 이 삽질들이 더 기억에 남네요.

1. Firebird 도커 이미지 태그가 없다
firebirdsql/firebird:5.0 으로 받으려니 "그런 태그 없음" 에러. 도커 허브 태그 목록을 뒤져서 실제로 존재하는 5.0.4 로 교체했습니다.

2. 파이썬 드라이버 버전 충돌
firebird-driver가 의존하는 firebird-base의 최신 버전(2.0)이 breaking change라, import 단계에서 TypeError가 터졌습니다. firebird-base<2 로 버전을 고정해서 해결했습니다. (최신이 항상 답은 아니네요 ^^;)

3. DB 접속 경로 문제
macdown.fdb 라는 별칭(alias)으로 접속하려니 "그런 파일 없음" 에러. 컨테이너 안을 들여다보니 별칭이 등록되어 있지 않더군요. 결국 절대 경로(//var/lib/firebird/data/macdown.fdb)로 접속해서 해결했습니다.

이 세 가지를 클로드 코드가 로그를 읽고 원인을 짚어가며 하나씩 고쳐나가는 과정이 꽤 인상적이었습니다.

💡 환경 관련 소소한 발견

• 제 맥은 도커 데스크톱이 아니라 Colima로 도커를 돌리고 있어서, colima start로 먼저 시동을 걸었습니다.
• docker compose(플러그인)가 연결이 안 되어 있어서, 독립형 docker-compose 명령을 사용했습니다.

✅ 결과

Hello World! 🔥 Firebird + FastAPI + Vue 3계층 연결 성공!

브라우저 화면에 Firebird DB에서 읽어온 이 메시지가 초록색(성공) 표시와 함께 딱 떴을 때, 어찌나 반갑던지요. ^^ 백엔드부터 프론트까지 전력이 다 갖춰졌다는 게 이제야 실감이 납니다.

📝 마치며

작지만 중요한 첫걸음을 성공적으로 뗐습니다. 이 뼈대가 있으니 이제 진짜 프로젝트가 시작되는 셈이죠.

다음 단계는 이 위에 실제 마크다운 에디터 UI(Marked / Markdown-it)와 문서 저장 API를 얹는 작업이 될 것 같습니다. 초경량 설치형 마크다운 에디터를 향해, 차근차근 나아가 보겠습니다.

클로드 코드와 함께라면 생각보다 든든하네요. 앞으로의 과정도 많은 관심과 응원 부탁드립니다!

감사합니다. ^^