87 lines
5.7 KiB
Markdown
Executable File
87 lines
5.7 KiB
Markdown
Executable File
# MH Dashboard Organization 배포 가이드
|
|
|
|
## 1. "도메인 발급/등록"이란?
|
|
- 도메인은 사용자가 브라우저에 입력하는 주소입니다. 예를 들면 `orgdash.intra.company.local` 같은 형태입니다.
|
|
- 사내망에서는 보통 IT팀이나 인프라 담당자가 이 주소를 실제 Ubuntu 서버 IP와 연결하는 DNS 설정을 등록합니다.
|
|
- 아직 사내 DNS 등록 절차가 없다면, 우선은 `http://10.10.10.15:8080` 같은 IP 주소로 먼저 접속하고 나중에 도메인을 붙여도 됩니다.
|
|
|
|
## 2. 이 프로젝트의 권장 구성
|
|
- `proxy`: 사내 접속용 단일 진입점 역할을 하는 Nginx 리버스 프록시
|
|
- `frontend`: 화면상 로그인과 허브 화면을 제공하는 정적 프론트엔드
|
|
- `backend`: 구성원 데이터, 이미지 업로드, 스냅샷 생성을 처리하는 FastAPI 서버
|
|
- `db`: 영구 저장을 담당하는 PostgreSQL 데이터베이스
|
|
|
|
## 3. 왜 이 구조가 지금 프로젝트에 맞는가
|
|
- 기존 조직도 HTML 화면을 그대로 레거시 모듈로 유지할 수 있습니다.
|
|
- 프로필 사진 업로드를 서버에 저장할 수 있습니다.
|
|
- 월말 조직 데이터 스냅샷을 서버에서 생성하고 보관할 수 있습니다.
|
|
- 요청하신 대로 로그인은 우선 화면상으로만 구현해 둘 수 있습니다.
|
|
|
|
## 4. Ubuntu 서버 준비
|
|
- 사내망 안에 Ubuntu 24.04 서버를 새로 준비합니다.
|
|
- 사내망에서 필요한 포트만 열어둡니다. 보통 `80` 또는 `8080` 정도면 시작할 수 있습니다.
|
|
- Docker Engine과 Docker Compose 플러그인을 설치합니다.
|
|
- 이 저장소를 서버로 복사합니다.
|
|
- `.env.example`을 기준으로 `.env` 파일을 만들고 실제 DB 비밀번호를 넣습니다.
|
|
|
|
## 4-1. 현재 로컬 PC 기준 WSL 작업 표준
|
|
- 현재 로컬 개발 서버는 `WSL2 + Ubuntu-24.04` 기준으로 구성했습니다.
|
|
- 기본 작업 사용자는 `hyunho` 입니다.
|
|
- 앞으로의 기준 작업 경로는 아래입니다.
|
|
- `/home/hyunho/projects/mh-dashboard-organization`
|
|
- Windows 폴더는 원본 참고용으로 남아 있을 수 있지만, 실제 실행과 개발 기준은 WSL 내부 경로로 맞추는 것을 권장합니다.
|
|
|
|
## 4-2. VS Code는 어떤 경로를 열어야 하나
|
|
- VS Code 좌측 아래에 `WSL: Ubuntu-24.04` 가 보이는 상태로 여는 것이 가장 안전합니다.
|
|
- VS Code에서 `Remote-WSL: Reopen Folder in WSL` 기능으로 다시 열 수 있습니다.
|
|
- 다시 열어야 할 권장 경로는 아래입니다.
|
|
- `/home/hyunho/projects/mh-dashboard-organization`
|
|
- 이렇게 열면 Docker, Python, Linux 경로, 실행 환경이 실제 서버와 가장 비슷하게 맞춰집니다.
|
|
|
|
## 5. Docker 설치 관련 메모
|
|
- 메신저에 공유된 명령어는 Ubuntu 서버에 Docker를 설치하기 위한 절차입니다.
|
|
- 최종 기준 문서는 Docker 공식 문서를 보는 것을 권장합니다.
|
|
https://docs.docker.com/engine/install/ubuntu/
|
|
- 회사에서 apt 미러나 보안 기준을 따로 관리한다면, 패키지 소스를 바꾸기 전에 그 정책을 먼저 확인하는 것이 좋습니다.
|
|
|
|
## 6. 최초 배포 순서
|
|
1. `.env.example`을 `.env`로 복사합니다.
|
|
2. `POSTGRES_PASSWORD` 값을 실제 비밀번호로 수정합니다.
|
|
3. `docker compose build`를 실행합니다.
|
|
4. `docker compose up -d`를 실행합니다.
|
|
5. 브라우저에서 `http://SERVER_IP:8080` 으로 접속합니다.
|
|
6. `docker compose ps` 에서 `backend`, `frontend`, `proxy`, `db` 가 모두 `healthy` 인지 확인합니다.
|
|
7. `http://SERVER_IP:8080/api/health` 응답에서 `status`, `checks`, `member_count` 를 확인합니다.
|
|
|
|
## 7. 현재 단계의 데이터 및 백업 정책
|
|
- 데이터베이스: PostgreSQL 볼륨 `postgres_data`
|
|
- 업로드 파일: Docker 볼륨 `uploads_data`
|
|
- 월말 스냅샷 파일: Docker 볼륨 `snapshots_data`
|
|
- 백업 주기: 월말 스냅샷 생성 + DB 볼륨 백업
|
|
- 복구 기준: 아직 정해지지 않았으므로, 우선은 수동 복구 절차를 먼저 문서화하고 이후에 기준을 구체화합니다.
|
|
|
|
## 8. 현재 구조의 한계
|
|
- 로그인은 화면상 동작만 구현되어 있고, 아직 백엔드 보호 기능은 없습니다.
|
|
- 레거시 조직도 화면은 현재 DB 기반 API를 사용하도록 전환했지만, 운영 환경에서 전체 업로드/재기동/스냅샷 흐름 검증이 추가로 필요합니다.
|
|
- 레거시 화면은 CDN 자산을 사용합니다. 사내망이 외부 인터넷 접속을 막는 환경이라면 추후 로컬 자산으로 바꿔야 합니다.
|
|
|
|
## 9. 다음 구현 권장 순서
|
|
1. Docker Compose 기준 운영 검증과 스냅샷 검증을 완료합니다.
|
|
2. 4개 기능 통합 대시보드 프레임과 공통 헤더를 준비합니다.
|
|
3. 프로필 사진 업로드 UI를 `/api/uploads/profile-photo` 와 연결합니다.
|
|
4. 사무실 자리배치 좌표 저장 기능을 추가합니다.
|
|
5. 인증 정책이 정해지면 화면상 로그인 대신 실제 로그인으로 교체합니다.
|
|
|
|
## 10. 현재 로컬 테스트 접속 정보
|
|
- 접속 주소: `http://localhost:8080`
|
|
- 상태 확인 API: `http://localhost:8080/api/health`
|
|
- WSL 내부 실행 경로:
|
|
- `/home/hyunho/projects/mh-dashboard-organization`
|
|
|
|
## 11. 운영 검증 체크포인트
|
|
- 엑셀 또는 CSV 업로드 후 `GET /api/members` 에서 데이터가 조회되는지 확인합니다.
|
|
- `docker compose restart backend proxy` 이후에도 데이터가 유지되는지 확인합니다.
|
|
- `POST /api/snapshots/monthly` 호출 시 `YYYY-MM` 형식만 허용되는지 확인합니다.
|
|
- 같은 월에 대해 중복 스냅샷 생성 시 409 에러가 반환되는지 확인합니다.
|
|
- `docker compose down` 후 다시 `up -d` 했을 때 DB/업로드/스냅샷 데이터가 유지되는지 확인합니다.
|