TBM 웹앱 운영 배포 배경
▶ 지난 글에서 이어집니다(https://www.gpters.org/nocode/post/-SqmGwJZLdzm758P)
지난 글에서는 종이 TBM 일지를 조별 QR + 휴대폰 손서명 웹앱으로 바꾸는 과정을 기획부터 독립 검증까지 정리했습니다.
그 글 마지막 "솔직하게: 아직 안 된 것"에 이렇게 적었습니다.
· 실제 서버 배포(Supabase·Vercel)는 아직 안 했습니다. 지금까지의 검증은 모두 제 PC 기준입니다.
· 개천절·한글날 같은 휴무일을 입력 해야 그날이 "미실시"로 잡히지 않습니다.
이번에 이 두 가지를 끝냈습니다. 제 PC에서만 돌던 앱을 조원들이 자기 휴대폰으로 QR을 찍어 쓰는 운영 주소까지 올린 기록입니다.
▶ 목표
· 공휴일·회사 휴무일에 TBM이 없어도 "누락"으로 잡히지 않게 한다.
· 개발 지식 없이 실제 인터넷 주소에 배포하고, 휴대폰 서명부터 PDF까지 운영 환경에서 직접 확인한다.
· 돈은 쓰지 않는다(무료 플랜으로).
━━━━━━━━━━━━━━━━━━━━
TBM 웹앱 운영 배포 과정
사용한 도구
· Claude Code (데스크톱 앱) + gatekit: 휴무일 기능 기획·빌드·검증, 배포 준비 코드 수정, 단계별 안내
· GitHub (비공개 저장소): 코드 보관. 여기에 올리면 Vercel이 자동으로 다시 배포
· Supabase (무료): 데이터베이스(조·조원·서명 기록)와 서명 이미지 저장소
· Vercel (Hobby, 무료): 웹앱을 실제 인터넷 주소로 띄우는 곳
전체 흐름
1단계 휴무일 관리
기획 추가 → 완료 기준 승인 → 빌드 → 독립 검증 → 남은 문제 수정
→ 작업 1개 추가(총 10개), 완료 기준 8개 모두 ok
2단계 첫 배포
배포 대비 코드 수정 → GitHub → Supabase → Vercel 첫 배포
→ 운영 주소에서 로그인 화면이 뜸
3단계 운영 확인
운영 확인 6항목, 운영에서만 난 오류 3개 해결, 테스트 데이터 삭제
→ 실사용 준비 완료
━━━━━━━━━━━━━━━━━━━━
1단계. 휴무일 관리 기능 추가
왜 먼저 했나
앱은 평일에 TBM 기록이 없으면 관리 화면 에 "미실시", 서명이 없으면 "누락"으로 띄웁니다. 그런데 개천절이나 한글날에는 원래 TBM이 없으니, 휴무일을 모르면 쉬는 날마다 9개 조가 전부 누락으로 뜹니다. 배포보다 이걸 먼저 하기로 했습니다.
AI가 "법정 공휴일은 다 쉬나요?"라고 물어서, 대부분 쉬지만 특근하는 날도 있고 단체연차 같은 회사 휴무도 있다고 답했습니다. 그 답으로 화면이 이렇게 정해졌습니다.
· 법정 공휴일 불러오기: 연도를 고르고 버튼 하나를 누르면, 오늘 이후 공휴일 중 아직 없는 날이 들어갑니다. 넣기 전에 날짜 목록을 보여 주고 확인을 받습니다. 대체공휴일도 들어가고, 올해부터 공휴일이 된 노동절·제헌절도 반영했습니다.
· 회사 휴무 추가: 날짜와 이름(예: 단체연차)을 넣습니다.
· 특근일은 삭제: 공휴일인데 일하는 날은 목록에서 지웁니다. 이미 지난 날짜면 "지난 기록의 누락 숫자가 바뀐다"고 경고합니다.
[📷 이미지 첨부: 08-holidays.png]
이름과 전화번호 목록이 포함된 웹사이트의 스크린샷
gatekit으로 한 바퀴 더
새 기능도 지난번과 같은 순서로 진행했습니다.
1. 기획서·화면 명세·작업 목록에 휴무일 화면을 추가하고, 완료 기준에 휴무일 테스트를 넣었습니다.
2. 승인 전에 지금 코드로 기준을 한 번 돌려 봅니다. 화면 캡처 기준만 fail이 나왔습니다(휴무일 화면이 아직 없으니 당연). 저는 "응 승인해줘" 한마디로 승인했습니다.
3. 빌드: 작업 1개, 게이트 3개(단위 테스트·E2E·색 규칙) 통과.
4. 독립 평가자 검증: 완료 기준 8개 모두 ok. 평가자가 직접 눌러 본 결과도 남겨 줬습니다.
· 2027년 불러오기 → 24일 추가. 한 번 더 누르면 "새로 넣을 공휴일이 없습니다"가 뜨고 버튼이 꺼짐
· 단체연차 를 넣으면 "회사 지정"으로 표시되고, 그날 오늘 현황에 휴무일 안내가 뜸
평가자가 "통과는 했지만 이상한 점"으로 남긴 세 가지도 바로 고쳐 달라고 했습니다.
💬 휴무일 스크린샷 대기 조건과 화면 잔여 문제(스켈레톤 잔존, 다시 시도, 해제 이력 이름) 먼저 고쳐줘
· 불러오기가 실패해도 회색 로딩 칸이 계속 남아 있던 것
· "다시 시도"를 누르면 실패한 동작이 아니라 목록만 다시 읽던 것
· 휴무일을 지운 변경 이력에 어떤 휴무일인지 이름이 안 남던 것 (점검 때 "뭘 지웠는지"가 보여야 하니까요)
테스트 파일이 바뀌면 gatekit은 완료 기준을 다시 승인받기 전까지 결과를 인정하지 않습니다. 재승인 후 8개 모두 ok가 나왔습니다.
━━━━━━━━━━━━━━━━━━━━
2단계. GitHub → Supabase → Vercel 첫 배포
시작은 "다음작업 시작해보자" 한 줄이었습니다. 제 계정 상황은 GitHub·Vercel은 있고 Supabase는 없음이었고, AI가 GitHub에 올리면 Vercel이 자동으로 배포하는 방식을 추천했습니다.
① AI가 먼저 한 일: 배포에서 터질 만한 것 미리 고치기
제가 계정을 만지기 전에 AI가 코드부터 손봤습니다.
· PDF에 넣는 한글 글꼴 파일이 Vercel 배포 묶음에서 빠지지 않도록 포함 설정
· Supabase 데이터베이스에 암호화 연결로 붙도록 설정
· 서버 위치를 서울로 고정
· 따라 하기만 하면 되는 배포 안내서(docs/deploy.md) 작성
그다음 첫 커밋을 하고, 이후는 AI가 한 단계씩 안내하고 저는 브라우저에서 클릭하는 방식으로 갔습니다.
② GitHub — 주소만 붙여 넣기
비공개 저장소 만드는 법을 칸별로 알려 줬고, 저는 만든 저장소 주소만 채팅에 붙여 넣었습니다. 연결과 업로드는 AI가 했습니다.
③ Supabase — 캡처 한 장으로 칸별 안내
gitHub 계정으로 바로 가입이 됐습니다. 프로젝트 만들기 화면을 캡처해서 보냈더니 칸마다 뭘 넣을지 알려 줬습니다.
· DB 비밀번호는 영문·숫자만. 특수문자가 있으면 나중에 연결 문자열이 깨질 수 있다고 했습니다.
· 지역은 서울
· 외부에서 DB를 직접 여는 기능(Data API)은 끔. 이 앱은 서버만 DB에 접속하니까요.
· 서명 이미지 저장 공간(버킷) tbm은 비공개로
④ 비밀값은 내가 직접 만든다
관리자 비밀번호와 세션 비밀값이 필요했는데, AI가 이렇게 안내했습니다.
🤖 이 비밀값은 제가 만들지 않고, 직접 터미널에서 만들어 메모장에 적어 두시는 게 안전합니다. 그래야 값이 대화 기록에 남지 않습니다.
명령어를 받아 제가 터미널에 붙여 넣고 나온 값을 메모장에 적었습니다. 배포 내내 AI는 키·비밀번호는 채팅에 붙이지 말고 각 서비스 화면에만 넣으라고 반복했습니다.
⑤ Vercel — 환경변수 6개
안내서에는 "환경변수 6개를 넣으라"고만 돼 있어서 입력하는 곳이 따로 있는 줄 알았습니다. 실제로는 Key/Value 칸에 하나씩 넣고 "Add More"로 칸을 늘리는 방식이었습니다. 비밀번호 해시에 $ 문자가 있어서 한꺼번에 붙여 넣는 기능 대신 하나씩 넣으라는 조언도 받았습니다.
[📷 이미지 첨부: 09-vercel-env.png]
Azure sys 콘솔의 스크린샷
Google 계정 로그인 페이지의 스크린샷
Deploy를 누르고 몇 분 뒤, 미리보기에 제 앱의 로그인 화면이 떴습니다.
[📷 이미지 첨부: 10-vercel-deployed.png]
Google 계정 로그인 페이지의 스크린샷
⑥ "이 주소인가?" — 주소가 두 종류
아니었습니다. Vercel은 주소를 두 종류 줍니다.
· 프로젝트이름.vercel.app (고정 주소): 누구나, 로그인 없이
· 프로젝트이름-해시-계정.vercel.app (배포마다 생기는 주소): Vercel 계정 주인만 (로그인 요구)
QR에는 고정 주소를 써야 한다는 설명을 들었는데, 이 차이를 운영 확인 때 한 번 더 겪었습니다.
━━━━━━━━━━━━━━━━━━━━
3단계. 운영 확인 6항목과 운영에서만 난 오류 3개
AI가 운영 확인 항목을 6개로 정리해 줬고, 하나씩 확인했습니다.
· 관리자 로그인: ✅
· 조·조원 등록, QR 주소: ✅ (오류 1·3 해결 후)
· 휴대폰 서명 → 오늘 현황 반영: ✅
· 휴무일(공휴일 불러오기): ✅
· PDF(한글·서명 이미지): ✅ (오류 2 해결 후)
· Supabase에 서명 이미지 저장: ✅
🔥 오류 1. 로그인은 되는데 저장이 하나도 안 됨
💬 일단 관리자 로그인해서 하는중인대 조 만들기나 이런거 저장은 안되던대 아직은 이게 맞는거야 ??
AI가 운영 주소에 직접 요청을 보내 보더니, DB를 거치지 않는 요청은 정상이고 DB를 거치는 요청만 500 오류라고 원인을 좁혔습니다. Vercel 화면의 Logs 탭에서 빨간 줄을 복사해 붙여 넣으니 한 줄로 끝났습니다.
💬 error: password authentication failed for user "postgres"
연결 문자열 속 DB 비밀번호가 틀렸다는 뜻 이었습니다. 해결은 간단했습니다. Supabase에서 비밀번호를 새로 정하고(영문·숫자만), 연결 문자열을 다시 만들어 Vercel에 넣고, 다시 배포하면 됩니다.
그런데 여기서 제일 오래 헤맸습니다.
· "database를 못찾겠는대 ?" → Supabase 메뉴 위치가 안내와 달랐습니다. AI가 설정 화면으로 바로 가는 주소를 줬습니다.
· "상단 connect는 찾았는대 저옆에껄 못찾았어" → 연결 문자열은 Connect 버튼을 누른 뒤 뜨는 창 안에 있었습니다.
· "2번 1. variables가 안보여" → Vercel 화면이 바뀌어서 환경변수가 Environments → Production 안으로 들어가 있었습니다.
· 다시 배포 버튼을 찾다가 엉뚱한 화면(배포 보호 설정)에 들어갔고, AI가 "여기서는 아무것도 바꾸지 마세요"라고 막아 줬습니다.
· 다시 배포해서 초록색 Ready까지 떴는데 "같은거로 나와 오류".
AI는 연결 문자열을 제 PC에서 직접 시험해 보는 점검 스크립트까지 만들었는데, 원인은 결국 제가 보낸 캡처 한 장에서 나왔습니다. 오른쪽 위에 "Updated 5h ago"(5시간 전 수정). 아까 Save를 눌렀다고 생각했는데 실제로는 저장이 안 돼서 처음 넣은 틀린 값이 그대로 있었던 겁니다.
[📷 이미지 첨부: 11-vercel-updated-5h.png]
Google 애드워즈 계정의 스크린샷
값을 다시 넣고 맨 아래 Save를 확실히 누른 뒤 다시 배포하니 바로 해결됐습니다.
🔥 오류 2. 내 PC에서는 되던 PDF가 운영에서만 실패
조원 등록과 휴대폰 서명은 잘 됐는데 PDF 내려받기가 안 됐습니다. AI가 증상을 A(버튼이 회색)·B(빨간 오류 문구)·C(한참 멈춤)로 나눠 물었고, 저는 "B야"라고만 답했습니다. 로그를 보니 PDF 라이브러리의 기본 영문 글꼴 파일을 못 찾는 오류였습니다.
한글 글꼴은 배포 준비 때 미리 배포 묶음에 넣어 뒀는데, 라이브러리가 자체로 쓰는 기본 글꼴이 빠져 있었습니다. 제 PC에는 파일이 다 있어서 테스트로는 절대 안 잡히는 문제였습니다. 포함 설정을 한 줄 추가하고, 완료 기준 8개를 다시 돌려 통과한 뒤 GitHub에 올리니 Vercel이 알아서 다시 배포했습니다.
💬 재배포 후 PDF 내려받기 됐고 한글·서명 이미지 다 잘 나와. Storage에도 서명 PNG 있어.
🔥 오류 3. 조원이 QR을 찍었는데 Vercel 로그인이 뜸
운영 확인이 다 끝난 줄 알았는데, 가장 중요한 문제가 남아 있었습니다.
💬 조원 들 qr로 로기인할때 vercel 로그인 해야됬는대 사원분들은 이거 가입하는거 자체가 엄청 진입장벽이거든 ?? 그냥 설문조사처럼 로그인없이 하는방법은 없어 ?
답은 "이 앱은 원래 조원 로그인이 없다"였습니다. 원인은 배포 때 들은 주소 두 종류였습니다. 제가 관리 화면을 Vercel의 Visit 버튼으로 열었는데, 그게 배포마다 생기는 주소(로그인 걸린 주소)였습니다. QR은 관리 화면을 연 주소를 그대로 따라 만들어지니 QR에도 그 주소가 들어간 겁니다.
같은 실수가 다시 안 나게 코드를 고쳐 달라고 했습니다.
💬 QR 주소가 항상 ○○○.vercel.app으로 나오게 코드 고쳐줘.
· 관리 화면을 어떤 주소로 열든 QR은 항상 운영 고정 주소로 만들어집니다.
· QR 아래에 주소를 글자로 표시해서, 인쇄하기 전에 눈으로 확인할 수 있게 했습니다.
· 이미 잘못 뽑은 QR 종이는 버리고 새로 인쇄했습니다.
그 밖에 헷갈렸던 것들
· 관리자 비밀번호가 admin 아니었나? → admin은 제 PC의 테스트 서버용입니다. 운영은 배포 때 직접 정한 비밀번호입니다.
· 조원 이름을 잘못 넣었는데 수정이 안 됨 → 이름 수정 기능이 없습니다. 지금은 "비활성"으로 돌리고 새로 추가합니다.
· 내 휴대폰으로 다른 이름을 못 고름 → 남의 이름으로 대신 서명하는 걸 막으려고, 휴대폰이 한 번 고른 이름을 기억하게 만든 것입니다. 테스트는 시크릿 창으로 했습니다.
· 주말에 한 서명이 PDF에 안 나옴 → 주말은 조장이 체크리스트를 저장한 날만 근무일로 칩니다. 의도한 동작입니다.
마무리: 테스트 데이터 지우기
💬 이제 그 샘플로 등록한거 삭제는 어떻게해 ?
Supabase의 SQL 화면에 명령 하나를 붙여 넣고 실행하고, 저장소의 서명 이미지 폴더를 지우면 끝이었습니다. 휴무일은 남기고 조·조원·서명·이력만 지웁니다. AI가 제 PC의 임시 DB에서 이 명령을 먼저 돌려 보고 안내했습니다. (서명 기록은 앱에서 지울 수 없게 막아 둔 상태라, 막힌 걸 확인한 뒤 통째로 비우는 방법을 썼습니다)
💬 일단 필요없는건 다 지웠고 다했어 이제 어느정도 완성이 된거야 ?
"네, 바로 실제로 쓸 수 있는 상태입니다."
━━━━━━━━━━━━━━━━━━━━
TBM 웹앱 운영 배포 결과와 배운 점
결과
· 지난 글의 "아직 안 된 것" 두 가지(휴무일, 운영 배포)를 끝냈습니다.
· 운영 주소에서 관리자 로그인 → 조·조원 등록 → QR → 휴대폰 서명 → 오늘 현황 → PDF → 휴무일까지 6항목을 직접 확인했습니다.
· 비용 0원: GitHub 비공개 저장소, Supabase 무료, Vercel Hobby.
· 이제 코드를 고치고 GitHub에 올리기 만 하면 Vercel이 자동으로 다시 배포합니다. 운영 확인 중에도 수정 2번을 이렇게 반영했습니다.
시행착오 정리
· 로그인은 되는데 저장 전부 실패
원인: DB 비밀번호 불일치 + 환경변수 Save가 실제로 안 됨
해결: 비밀번호 재설정(영문·숫자) → 다시 저장 → "Updated" 시각 확인 → 재배포
· 운영에서만 PDF 실패
원인: PDF 라이브러리 기본 글꼴 파일이 배포 묶음에서 빠짐
해결: 포함 설정 추가 후 재배포
· 조원 QR에 Vercel 로그인
원인: 관리 화면을 배포별 주소로 열어 QR에 그 주소가 들어감
해결: QR을 운영 고정 주소로 고정, QR 아래 주소 표시
· 휴무일 빌드 첫 판정 실패
원인: 테스트 서버가 안 떠 있어 E2E가 60초 만에 timeout
해결: 서버를 먼저 띄우고 재판정
배운 점
1. 화면이 안내와 다르면 캡처부터 보내세요. Supabase도 Vercel도 메뉴 위치가 안내와 달랐습니다. 말로 설명하는 것보다 캡처 한 장이 빨랐고, 결정적인 원인("Updated 5h ago")도 캡처에서 나왔습니다.
2. 500 오류가 나면 Vercel Logs의 빨간 줄 첫 줄을 붙여 넣으세요. DB 비밀번호 문제도, PDF 글꼴 문제도 로그 한 줄로 원인이 나왔습니다.
3. 환경변수는 "저장 → 다시 배포" 두 번입니다. 그리고 저장됐는지는 "Updated ..." 시각으로 확인하세요. 저는 이걸 몰라서 한참 돌았습니다.
4. Vercel 주소는 두 종류입니다. 남에게 줄 주소(QR, 링크)는 반드시 프로젝트이름.vercel.app 고정 주소로. 관리 화면도 즐겨찾기한 고정 주소로만 여세요.
5. "내 PC에서 테스트 통과"와 "운영에서 동작"은 다릅니다. 지난 글에서 "테스트 통과 ≠ 쓸 만하다"를 배웠다면, 이번에는 "로컬 통과 ≠ 운영 동작"을 배웠습니다. 운영 확인 항목을 미리 정해 두고 하나씩 직접 눌러 보는 게 필요했습니다.
6. 비밀값은 채팅에 붙이지 마세요. 비밀번호 해시와 세션 값은 터미널에서 직접 만들고 서비스 화면에만 넣었습니다. AI가 먼저 그렇게 안내해 줬습니다.
솔직하게: 아직 남은 것
· 무료 플랜의 한계: Supabase 무료는 7일 동안 아무도 안 쓰면 DB가 일시정지됩니다(연휴 주의). Vercel Hobby는 약관상 개인·비상업용이라, 회사 업무로 정식 운영하려면 Pro(월 20달러) 전환을 회사와 상의해야 합니다.
· 백업: 무료 플랜은 DB 백업이 거의 없어서, 월말마다 기록 화면에서 PDF를 내려받아 보관하기로 했습니다.
· 없는 기능: 조원 이름 수정, 휴대폰에서 "이름 다시 고르기"
· 휴무일 수정 뒤 독립 평가자의 화면 판정은 다시 돌리지 않았습니다(완료 기준 8개는 ok).
· 지난 글에서 남긴 개인정보 동의서 필요 여부, TBM 기록 보관 기간도 아직 확인 중입니다.
앞으로의 계획
1. 한 조에서 먼저 시범 운영 → 문제없으면 9개 조 전체로
2. 쓰다가 필요하면 조원 이름 수정, 이름 다시 고르기 추가
3. 외국인 근로자용 다국어 표시소개
