hyunho/MH-DashBoard-organization

Files

hyunho f8ea345882 Refactor app structure and simplify team docs

2026-04-02 11:13:43 +09:00

4.6 KiB

Executable File

Raw Blame History

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. 로컬 개발 환경 원칙

로컬 개발은 Linux 계열 개발 환경을 권장합니다.
Docker, Python, 파일 경로가 실제 배포 환경과 최대한 비슷한 환경에서 작업하는 것이 안전합니다.
Windows 호스트를 사용하는 경우에도, 실제 실행 경로와 편집 경로가 어긋나지 않도록 주의합니다.

5. Docker 설치 관련 메모

메신저에 공유된 명령어는 Ubuntu 서버에 Docker를 설치하기 위한 절차입니다.
최종 기준 문서는 Docker 공식 문서를 보는 것을 권장합니다. https://docs.docker.com/engine/install/ubuntu/
회사에서 apt 미러나 보안 기준을 따로 관리한다면, 패키지 소스를 바꾸기 전에 그 정책을 먼저 확인하는 것이 좋습니다.

6. 최초 배포 순서

.env.example을 .env로 복사합니다.
POSTGRES_PASSWORD 값을 실제 비밀번호로 수정합니다.
docker compose build를 실행합니다.
docker compose up -d를 실행합니다.
브라우저에서 http://SERVER_IP:8080 으로 접속합니다.
docker compose ps 에서 backend, frontend, proxy, db 가 모두 healthy 인지 확인합니다.
http://SERVER_IP:8080/api/health 응답에서 status, checks, member_count 를 확인합니다.

7. 현재 단계의 데이터 및 백업 정책

데이터베이스: PostgreSQL 볼륨 postgres_data
업로드 파일: Docker 볼륨 uploads_data
백업 주기: DB 볼륨 백업
복구 기준: 아직 정해지지 않았으므로, 우선은 수동 복구 절차를 먼저 문서화하고 이후에 기준을 구체화합니다.

8. 현재 구조의 한계

로그인은 화면상 동작만 구현되어 있고, 아직 백엔드 보호 기능은 없습니다.
레거시 조직도 화면은 현재 DB 기반 API를 사용하도록 전환했지만, 운영 환경에서 전체 업로드/재기동 흐름 검증이 추가로 필요합니다.
레거시 화면은 CDN 자산을 사용합니다. 사내망이 외부 인터넷 접속을 막는 환경이라면 추후 로컬 자산으로 바꿔야 합니다.

9. 다음 구현 권장 순서

Docker Compose 기준 운영 검증을 완료합니다.
4개 기능 통합 대시보드 프레임과 공통 헤더를 준비합니다.
프로필 사진 업로드 UI를 /api/uploads/profile-photo 와 연결합니다.
사무실 자리배치 좌표 저장 기능을 추가합니다.
인증 정책이 정해지면 화면상 로그인 대신 실제 로그인으로 교체합니다.

10. 현재 로컬 테스트 접속 정보

접속 주소: http://localhost:8080
상태 확인 API: http://localhost:8080/api/health

11. 운영 검증 체크포인트

엑셀 또는 CSV 업로드 후 GET /api/members 에서 데이터가 조회되는지 확인합니다.
docker compose restart backend proxy 이후에도 데이터가 유지되는지 확인합니다.
docker compose down 후 다시 up -d 했을 때 DB/업로드 데이터가 유지되는지 확인합니다.