JOURNAL / ENTRY
Ubuntu 서버에 KitchenAsty 개발환경 구축하기
Ubuntu 서버에 KitchenAsty 원본 개발환경을 구축하고, Windows에서 SSH Tunnel과 VS Code Remote SSH로 개발하는 전 과정을 정리했습니다.
이번에는 오픈소스 식당 운영 플랫폼 KitchenAsty를 Ubuntu Linux 서버에 설치하고, Windows PC의 웹브라우저에서 실제 화면을 확인하면서 개발할 수 있는 환경을 만들어 보겠습니다.
최종 목표는 다음과 같습니다.
Windows PC
│
├─ VS Code
│ └─ SSH → Ubuntu 서버의 KitchenAsty 코드 편집
│
└─ Chrome / Edge
└─ SSH Tunnel
├─ localhost:5173 → 관리자 화면
├─ localhost:5174 → 고객용 화면
└─ localhost:3000 → API
Ubuntu Server
│
├─ Node.js 22
├─ KitchenAsty
│ ├─ Express API :3000
│ ├─ React Admin :5173
│ └─ React Storefront :5174
│
└─ Docker
└─ PostgreSQL 16 :5432
KitchenAsty를 한국 식당 환경에 맞게 리팩터링하기 전에 원본 프로그램이 정상적으로 실행되는 개발환경부터 만드는 것이 첫 번째 목표입니다.
1. KitchenAsty 개발환경 구성
KitchenAsty는 TypeScript 기반의 모노레포 프로젝트입니다.
주요 구성은 다음과 같습니다.
Backend
Node.js + Express + TypeScript
Frontend
React + Vite + TypeScript
Database
PostgreSQL + Prisma
Realtime
Socket.IO
Development
npm workspaces
Database container
Docker
개발 시에는 모든 프로그램을 Docker로 실행하지 않고 다음과 같이 구성하는 것이 편리합니다.
PostgreSQL → Docker
Express API → Node.js 개발 서버
React Admin → Vite 개발 서버
React Storefront → Vite 개발 서버
이렇게 하면 React 코드를 수정했을 때 브라우저에 변경 내용이 바로 반영되는 HMR 기능을 사용할 수 있습니다.
2. Ubuntu 기본 개발도구 설치
Ubuntu 서버에 SSH로 접속합니다.
ssh 사용자명@서버IP
패키지를 업데이트합니다.
sudo apt update
필요한 기본 개발도구를 설치합니다.
sudo apt install -y \
git \
curl \
ca-certificates \
build-essential \
tmux \
unzip
설치를 확인합니다.
git --version
curl --version
3. Node.js 22 설치
KitchenAsty는 Node.js 22 이상을 기준으로 개발되어 있습니다.
Ubuntu 기본 apt 패키지보다 Node 버전을 쉽게 관리할 수 있는 nvm을 사용하는 것이 좋습니다.
nvm을 설치합니다.
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.7/install.sh | bash
설정 파일을 다시 불러옵니다.
source ~/.bashrc
설치 여부를 확인합니다.
nvm --version
Node.js 22를 설치합니다.
nvm install 22
기본 Node 버전으로 설정합니다.
nvm alias default 22
확인합니다.
node -v
npm -v
정상적인 경우 다음과 비슷하게 표시됩니다.
v22.x.x
10.x.x
4. Docker 설치
KitchenAsty에서는 PostgreSQL을 Docker로 실행합니다.
이미 Docker가 설치되어 있다면 다음 명령으로 먼저 확인합니다.
docker --version
docker compose version
정상적으로 버전이 나온다면 Docker 설치 과정은 건너뛰어도 됩니다.
Docker가 없다면 먼저 필요한 패키지를 설치합니다.
sudo apt update
sudo apt install -y ca-certificates curl
Docker 키 저장소를 만듭니다.
sudo install -m 0755 -d /etc/apt/keyrings
Docker 공식 GPG Key를 가져옵니다.
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
-o /etc/apt/keyrings/docker.asc
권한을 설정합니다.
sudo chmod a+r /etc/apt/keyrings/docker.asc
Docker 저장소를 등록합니다.
sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
패키지 정보를 갱신합니다.
sudo apt update
Docker를 설치합니다.
sudo apt install -y \
docker-ce \
docker-ce-cli \
containerd.io \
docker-buildx-plugin \
docker-compose-plugin
테스트합니다.
sudo docker run hello-world
5. sudo 없이 Docker 사용하기
개발 중 매번 sudo docker를 입력하는 것은 불편합니다.
현재 사용자를 Docker 그룹에 추가합니다.
sudo usermod -aG docker $USER
현재 셸에 바로 적용하려면 다음을 실행합니다.
newgrp docker
확인합니다.
docker ps
오류가 없다면 정상입니다.
6. KitchenAsty Clone
개발 프로그램을 보관할 디렉터리를 만듭니다.
mkdir -p ~/apps
이동합니다.
cd ~/apps
KitchenAsty 저장소를 Clone 합니다.
git clone https://github.com/mighty840/kitchenasty.git
프로젝트 폴더로 이동합니다.
cd kitchenasty
확인합니다.
ls
대략 다음과 같은 구조가 보입니다.
packages
prisma
e2e
docker-compose.yml
package.json
package-lock.json
README.md
...
7. 한국형 리팩터링 브랜치 만들기
원본 main 브랜치를 직접 수정하지 않는 것이 좋습니다.
한국형 리팩터링 전용 브랜치를 만듭니다.
git switch -c korea-refactor
확인합니다.
git branch
다음과 같이 나오면 됩니다.
* korea-refactor
main
앞으로 한국형 KitchenAsty 개발은 이 브랜치에서 진행합니다.
8. Node 패키지 설치
프로젝트 최상위 디렉터리에서 실행합니다.
cd ~/apps/kitchenasty
패키지를 설치합니다.
npm install
KitchenAsty는 npm workspace 방식이므로 루트 디렉터리에서 한 번 설치하면 다음 패키지들이 함께 처리됩니다.
packages/server
packages/admin
packages/storefront
packages/shared
packages/docs
9. Shared 패키지 빌드
KitchenAsty의 공통 TypeScript 코드는 packages/shared에 들어 있습니다.
처음 설치한 후 한 번 빌드합니다.
npm run build -w packages/shared
이 단계는 최초 실행 전에 해두는 것이 좋습니다.
10. PostgreSQL 실행
KitchenAsty는 PostgreSQL 16을 사용합니다.
기본 개발 DB 설정은 다음과 같습니다.
DATABASE : kitchenasty
USER : kitchenasty
PASSWORD : kitchenasty
PORT : 5432
개발 단계에서는 전체 Docker Compose 서비스를 실행하지 않고 PostgreSQL만 실행합니다.
docker compose up -d postgres
상태를 확인합니다.
docker compose ps
또는
docker ps
다음과 비슷하게 나타나면 정상입니다.
kitchenasty-db
postgres:16-alpine
Up
11. PostgreSQL 외부 공개 막기
원본 Docker Compose 설정에서는 PostgreSQL이 다음과 같이 되어 있습니다.
ports:
- "5432:5432"
인터넷에 연결된 개발 서버에서는 DB를 외부에 공개할 필요가 없습니다.
가능하면 다음과 같이 변경합니다.
ports:
- "127.0.0.1:5432:5432"
이렇게 하면 PostgreSQL은 Ubuntu 서버 내부에서만 접근할 수 있습니다.
12. 서버 환경변수 설정
KitchenAsty에는 예제 환경설정 파일이 있습니다.
cp packages/server/.env.example packages/server/.env
수정합니다.
nano packages/server/.env
기본적인 개발환경은 다음과 같이 구성합니다.
PORT=3000
NODE_ENV=development
CORS_ORIGINS=http://localhost:5173,http://localhost:5174
DATABASE_URL=postgresql://kitchenasty:kitchenasty@localhost:5432/kitchenasty
JWT_SECRET=여기에랜덤문자열
JWT_EXPIRES_IN=7d
JWT Secret은 직접 생성하는 것이 좋습니다.
openssl rand -hex 32
출력된 문자열을 다음 부분에 넣습니다.
JWT_SECRET=
nano 저장 방법은 다음과 같습니다.
Ctrl + O
Enter
Ctrl + X
13. 데이터베이스 테이블 생성
Prisma Migration을 실행합니다.
npx -w packages/server prisma migrate dev \
--schema ../../prisma/schema.prisma
Migration 이름을 물어보면 예를 들어 다음처럼 입력합니다.
init
14. 초기 테스트 데이터 생성
DB에 초기 데이터를 넣습니다.
npx -w packages/server prisma db seed
KitchenAsty에는 기본 관리자 계정도 준비되어 있습니다.
ID
admin@kitchenasty.com
Password
admin123
테스트 고객 계정은 다음과 같습니다.
customer@example.com
customer123
개발용 계정이므로 실제 운영환경에서는 반드시 변경해야 합니다.
15. API 서버 실행
첫 번째 SSH 터미널을 엽니다.
cd ~/apps/kitchenasty
API 서버를 실행합니다.
npm run dev:server
API 서버 주소는 다음과 같습니다.
http://localhost:3000
KitchenAsty 서버는 tsx watch를 사용하므로 TypeScript 서버 코드를 변경하면 자동으로 재시작됩니다.
16. 관리자 화면 실행
두 번째 SSH 터미널에서 실행합니다.
cd ~/apps/kitchenasty
npm run dev:admin
관리자 개발 서버는 다음 포트를 사용합니다.
http://localhost:5173
17. 고객용 홈페이지 실행
세 번째 SSH 터미널에서 실행합니다.
cd ~/apps/kitchenasty
npm run dev:storefront
고객용 홈페이지는 다음 포트를 사용합니다.
http://localhost:5174
현재 서버에는 다음 세 개의 프로그램이 실행되고 있습니다.
3000 → Express API
5173 → 관리자 React
5174 → 고객 React
18. Windows에서 SSH Tunnel 연결
개발 포트를 인터넷에 직접 공개하기보다는 SSH Tunnel을 사용하는 것이 안전하고 편리합니다.
Windows PowerShell에서 다음과 같이 실행합니다.
ssh -L 5173:127.0.0.1:5173 \
-L 5174:127.0.0.1:5174 \
-L 3000:127.0.0.1:3000 \
사용자명@서버IP
PowerShell에서 한 줄로 입력하려면 다음과 같습니다.
ssh -L 5173:127.0.0.1:5173 -L 5174:127.0.0.1:5174 -L 3000:127.0.0.1:3000 사용자명@서버IP
SSH 포트가 기본 22번이 아니라면 다음처럼 사용합니다.
ssh -p SSH포트 -L 5173:127.0.0.1:5173 -L 5174:127.0.0.1:5174 -L 3000:127.0.0.1:3000 사용자명@서버IP
19. Windows 브라우저에서 확인
이제 Windows의 Chrome 또는 Edge를 실행합니다.
고객용 식당 홈페이지:
http://localhost:5174
관리자 페이지:
http://localhost:5173
관리자 로그인:
admin@kitchenasty.com
admin123
API 문서:
http://localhost:3000/api/docs
여기까지 정상적으로 보인다면 KitchenAsty 개발환경 구축은 성공입니다.
20. VS Code Remote SSH 사용
KitchenAsty를 개발할 때 가장 편리한 구조는 다음과 같습니다.
Windows
│
├─ VS Code
│ │
│ └─ Remote SSH
│ ↓
│ Ubuntu Server
│ ↓
│ ~/apps/kitchenasty
│
└─ Chrome
├─ localhost:5173
└─ localhost:5174
소스코드는 Ubuntu에만 저장합니다.
Windows의 VS Code는 SSH로 Ubuntu의 소스코드를 직접 열어서 수정합니다.
파일을 저장하면:
VS Code
↓
Ubuntu 파일 변경
↓
Vite 변경 감지
↓
React 자동 컴파일
↓
Chrome 자동 갱신
이 흐름이 만들어집니다.
웹 프로그램을 개발할 때 상당히 편리한 방식입니다.
21. 주요 소스 디렉터리
KitchenAsty를 수정할 때 자주 사용하게 될 위치입니다.
고객 화면:
packages/storefront/src/
관리자 화면:
packages/admin/src/
백엔드 API:
packages/server/src/
공통 TypeScript 코드:
packages/shared/src/
DB Schema:
prisma/schema.prisma
예를 들어 고객 화면을 수정한 후 저장하면 Vite가 변경사항을 감지하여 브라우저를 자동 갱신합니다.
22. Shared 패키지 자동 빌드
한국형 리팩터링이 본격화되면 packages/shared도 자주 수정하게 됩니다.
이때 별도의 터미널에서 다음 명령을 실행합니다.
npm run dev -w packages/shared
그러면 Shared TypeScript 코드도 자동 컴파일됩니다.
본격적인 개발 단계에서는 대략 다음 네 개의 개발 프로세스가 실행됩니다.
shared
└─ TypeScript Watch
server
└─ Express + tsx watch
admin
└─ React + Vite
storefront
└─ React + Vite
그리고 PostgreSQL은 Docker로 실행됩니다.
23. 개발 서버 종료
Node 개발 서버들은 각각 해당 터미널에서 다음을 누릅니다.
Ctrl + C
PostgreSQL을 멈추려면:
docker compose stop postgres
다시 시작하려면:
docker compose start postgres
상태 확인:
docker compose ps
주의해야 할 명령이 있습니다.
docker compose down -v
개발 중에는 가능하면 사용하지 않는 것이 좋습니다.
-v 옵션은 PostgreSQL 데이터가 들어있는 Docker Volume까지 삭제할 수 있기 때문입니다.
24. 문제가 생겼을 때 확인 방법
3000, 5173, 5174, 5432 포트 확인:
sudo ss -lntp | grep -E ':(3000|5173|5174|5432)\b'
Docker 상태:
docker ps
PostgreSQL 로그:
docker logs kitchenasty-db
Node 버전:
node -v
npm 버전:
npm -v
Git 상태:
git status
Git Branch:
git branch
25. 최종 개발환경
최종적으로 다음과 같은 환경이 만들어집니다.
Ubuntu Server
│
├── ~/apps/kitchenasty
│
├── Node.js 22
│
├── Docker
│ └── PostgreSQL 16
│
├── npm run dev:server
│ └── :3000
│
├── npm run dev:admin
│ └── :5173
│
└── npm run dev:storefront
└── :5174
↓
SSH Tunnel
↓
Windows PC
│
├── VS Code
│ └── Remote SSH
│
└── Chrome
├── localhost:5173
│ └── 관리자
│
└── localhost:5174
└── 고객용 홈페이지
다음 단계: 한국형 KitchenAsty 만들기
개발환경이 정상적으로 동작하면 그 다음부터 본격적인 한국형 리팩터링을 시작할 수 있습니다.
제가 생각하는 작업 순서는 다음과 같습니다.
1. 한국어를 기본 언어로 변경
2. KRW / 원화 가격체계 적용
3. 한국 주소와 전화번호 형식 적용
4. DELIVERY / PICKUP 구조에
DINE_IN(매장식사) 추가
5. 한국 식당 영업시간 적용
- 브레이크타임
- 라스트오더
- 정기휴무
- 임시휴무
6. 한국형 테이블 예약 시스템
7. 예약금 및 노쇼 관리
8. 카카오 알림톡 / SMS
9. 국내 결제 시스템
- 토스페이먼츠
- 카카오페이
- 네이버페이
10. 네이버지도 / 카카오맵 연동
중요한 점은 한국형 기능부터 수정하지 않고 원본 KitchenAsty가 정상적으로 실행되는 상태를 먼저 확보하는 것입니다.
원본 프로그램이 정상적으로 실행되는 것을 확인했다면 다음과 같이 첫 번째 기준점을 만들어 두는 것도 좋습니다.
git status
변경 사항을 정리한 뒤:
git add .
git commit -m "chore: establish Korean refactor development baseline"
이 기준점이 있으면 이후 리팩터링 과정에서 문제가 발생하더라도 정상 동작하던 시점과 쉽게 비교할 수 있습니다.
다음 작업부터는 KitchenAsty의 화면을 실제 브라우저에서 확인하면서 한국어 UI부터 하나씩 변경해 볼 예정입니다.