hyunho/MH-DashBoard-organization

Files

hyunho d9023abed6 Initial dashboard organization setup

2026-03-25 10:26:33 +09:00

4.8 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. 현재 로컬 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. 최초 배포 순서

.env.example을 .env로 복사합니다.
POSTGRES_PASSWORD 값을 실제 비밀번호로 수정합니다.
docker compose build를 실행합니다.
docker compose up -d를 실행합니다.
브라우저에서 http://SERVER_IP:8080 으로 접속합니다.

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

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

8. 현재 구조의 한계

로그인은 화면상 동작만 구현되어 있고, 아직 백엔드 보호 기능은 없습니다.
레거시 조직도 화면은 iframe으로 연결만 해둔 상태이며, DB 기반 API와 완전히 연동되지는 않았습니다.
레거시 화면은 CDN 자산을 사용합니다. 사내망이 외부 인터넷 접속을 막는 환경이라면 추후 로컬 자산으로 바꿔야 합니다.

9. 다음 구현 권장 순서

프로필 사진 업로드 UI를 /api/uploads/profile-photo 와 연결합니다.
구성원 데이터를 브라우저 메모리 방식에서 PostgreSQL 기반 API 저장 방식으로 전환합니다.
사무실 자리배치 좌표 저장 기능을 추가합니다.
인증 정책이 정해지면 화면상 로그인 대신 실제 로그인으로 교체합니다.

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

접속 주소: http://localhost:8080
상태 확인 API: http://localhost:8080/api/health
WSL 내부 실행 경로:
- /home/hyunho/projects/mh-dashboard-organization