앱 만들고 배포하기
웹 콘솔 · 클로드 앱 · 터미널 중 편한 방법으로 첫 앱을 만들어 배포까지 끝내요.
이 문서를 따라 하면 첫 앱을 만들어 배포까지 끝나요.
세 가지 방법 중 편한 것 하나만 고르면 되고, 어느 쪽이든 결과는 같아요.
템플릿 코드가 담긴 GitHub 저장소와, 접속 주소가 있는 앱이 생겨요.
공통 준비물
- AxHub 계정 — AxHub를 쓰는 회사의 구성원이어야 해요. 계정이 없다면 소속 회사의
tenant_admin(회사의 AxHub를 관리하는 사람)에게 초대를 요청하세요. - GitHub 계정 — 앱 코드는 GitHub에 저장돼요. axhub GitHub App을 설치할 수 있는 개인 계정이면 되고, 회사 조직(org) 계정이어도 돼요.
클로드 앱 방법은 Claude Desktop, 터미널 방법은 Claude Code가 추가로 필요해요 — 각 탭에서 설치부터 안내해요.
만드는 방법 고르기
브라우저만 있으면 돼요. AxHub 웹 콘솔의 앱 만들기 페이지에서 템플릿을 고르고 완료를 한 번 누르면, 저장소 생성부터 첫 배포까지 AxHub가 알아서 해요.
기본 정보 입력
앱 메뉴에서 앱 만들기를 누르고, 맨 위 기본 정보의 세 칸을 채워요.
앱 이름부터 입력하면 그 이름을 바탕으로 서브 도메인과 슬러그가 자동으로 채워져요. 마음에 안 들면 각 칸을 직접 고치면 돼요.
| 항목 | 무엇인가요 | 규칙 |
|---|---|---|
| 앱 이름 | 동료가 알아볼 표시 이름이에요 | 1~100자, 한글도 OK |
| 서브 도메인 | 앱에 접속할 인터넷 주소예요 — {서브도메인}.{회사}.axhub.ai 형태로 만들어져요 | 영문 소문자로 시작, 소문자 · 숫자 · 하이픈, 2~32자 |
| 슬러그 | 회사 안에서 앱을 구분하는 짧은 영문 이름이에요. 관리 화면과 명령어에서 이 앱을 가리킬 때 써요 | 영문 소문자로 시작, 소문자 · 숫자 · 하이픈, 3~50자 |
앱 이름을 한글로 적으면 서브 도메인 · 슬러그가 자동으로 채워지지 않아요. 그 두 칸은 영문으로 직접 입력하세요. (예: 이름 내 할일 → 서브 도메인 · 슬러그 my-todo)
템플릿 고르기
어떤 코드로 시작할지 고르는 단계예요. 고른 템플릿의 코드가 새 저장소에 그대로 들어가서, 빈 화면이 아니라 이미 동작하는 앱으로 시작해요.
| 템플릿 | 어떤 앱에 좋아요 |
|---|---|
| Vite + React SPA | 화면만 있는 앱 — 가장 빠른 시작이에요. 브라우저에서만 돌지만 외부 API를 불러오는 건 가능해요 |
| Next.js App Router | 화면과 서버가 함께 필요한 앱 — 서버에서 데이터를 읽고 저장할 수 있어요 |
| Astro | 글이 중심인 사이트 · 블로그 — 기본은 고정된 화면이고, 필요한 부분만 움직이게 해요 |
고민되면 — 화면+서버가 함께 필요한 웹앱은 Next.js App Router, 가벼운 단일 화면 위주면 Vite + React SPA로 시작하면 무난해요.
Git 저장소 연결
앱 코드를 둘 GitHub 저장소를 만드는 단계예요.
GitHub App 설치 (처음 한 번)
저장소 이름 정하기
같은 이름의 저장소가 이미 있으면 실패해요(repo_exists). 다른 이름으로 다시 시도하세요.
완료 — 한 번에 배포까지
완료를 누르면 진행 화면이 뜨고, 아래 순서로 자동 진행돼요. 중간에 뭘 더 누를 필요는 없어요.
앱 생성 → 저장소 생성 → 템플릿 코드 넣기 → 연결 → 배포끝나면 개발중 탭으로 이동하고 앱 주소(URL)가 생겨요.
공통: 배포 확인
어느 방법으로 만들었든 확인은 같아요.
앱 주소로 들어가 보기 — 앱마다 주소가 하나씩 생겨요. {서브도메인}.{회사}.axhub.ai 형태예요. 브라우저에서 열어 템플릿 화면이 떠 있으면 성공이에요.
콘솔에서 보기 — 회사 콘솔({회사}.axhub.ai, 예: jocodingax.axhub.ai)에 들어가 내 앱을 열면 방금 만든 앱이 카드로 보여요.
카드를 누르면 그 앱의 앱 콘솔이 열려요. 배포 상태와 로그, 환경변수, 데이터가 모두 여기 있어요.
만든 뒤 관리하기
앱 콘솔에서 아래를 전부 다뤄요.
| 하고 싶은 일 | 콘솔 위치 | 문서 |
|---|---|---|
| 배포가 잘 됐는지 보고 되돌리기 | 배포 탭 | 배포 관리 |
| 회사 사람들에게 공개하기 | 배포 탭 안의 공개 범위 | 공개 · 접근 관리 |
| 쌓인 데이터 표로 보기 | 리소스 탭 → 테이블 | 데이터베이스 연결하기 |
| 올라간 파일 보기 | 리소스 탭 → 스토리지 | 스토리지 연결하기 |
| 비밀값 넣고 빼기 | 리소스 탭 → 환경변수 | 환경변수 설정하기 |
| 앱에 들어올 사람 정하기 | 앱 사용자 탭 | 공개 · 접근 관리 |
| 데이터 스냅샷 남기고 되돌리기 | 백업 탭 | 백업하고 복원하기 |
테이블 · 스토리지 · 환경변수는 리소스 탭 하나에 묶여 있고, 탭 안에서 셋을 오가며 봐요.
회사에 사람을 들이고 권한을 나누는 건 앱이 아니라 회사 단위라서, 관리자 콘솔의 사용자 · 팀에서 해요 — 팀원 초대 · 권한 나누기에 있어요.
코드에 기능 더하기
이제 만들어진 저장소를 Claude Code로 열어 기능을 더해 가면 돼요. 이 저장소는 이미 AxHub용으로 세팅(포트 · 구조)돼 있어요. 이렇게 부탁해 보세요.
할 일 목록 화면을 추가해줘. 제목과 마감일을 입력해 저장하고,
목록에서 완료 체크할 수 있게 해줘.수정한 코드를 커밋해 GitHub에 올리면(push) 배포가 다시 시작돼요.
막히면
- 플러그인을 쓴다면 — "방금 배포 왜 실패했는지 알려줘"라고 물어보세요. 실패한 배포의 기록(로그)을 가져와 원인을 짚어줘요.
- 터미널이라면 —
axhub deploy status <id> --app <앱>과axhub deploy logs <id> --app <앱>을 실행해 어디서 멈췄는지 봐요. - 증상별 해결법은 문제 해결에 있어요.