프로젝트 기본사항

들어가기

kaistusc 프로젝트는 KAIST 학부 총학생회 사이트를 구축하여 총학생회 회원들의 원활한 참여를 보장하기 위해 시작되었습니다. 2016년 제30대 KAIST 학부 총학생회 <K’loud> 중앙집행국에서 프로젝트를 운영하였으며, 제31대 KAIST 학부 총학생회 <품>에게 인수인계를 하여 지속적으로 개발 중에 있는 상황입니다.

kaistusc 프로젝트는 단순한 공지 및 보드 형식의 일반적인 사이트와는 달리 몇 가지 차별화된 개발 원칙과 방향성을 갖고 있습니다.

  1. 다양한 서비스 개발을 위한 통합 플랫폼

총학생회의 여러 사업과 연계하여 단기간에 각 사업에 맞는 서비스를 개발하고 이를 사이트에 배포할 수 있도록 사이트 차원에서 손쉽게 개발을 할 수 있는 인프라를 조성합니다. 각각의 서비스는 Django 의 어플리케이션(app) 형식으로 개발되어 사이트에 탈부착 하기가 용이합니다. 서비스의 권한과 특성 관리를 위해 사이트 내의 서비스들을 통합하여 관리할 수 있는 시스템을 갖추었습니다.

또한, 서비스 개발 시 KAIST Portal 계정으로 통합된 유저모델이나 이미 구현된 사이트 내부 구성요소 view 등 여러 기능들을 자유롭게 활용하여 보다 빠르게 개발할 수 있고, 특히 유저 개개인의 권한이나 공통된 집단의 구성원을 묶은 그룹 등 Django에서 제공하는 강력한 기능들을 사용하실 수 있습니다.

  1. 다양한 구성원을 포용하는 다국어 지원

KAIST의 많은 국제학생들 역시 총학생회 활동에 소외되지 않도록 철저한 다국어 지원을 원칙으로 개발되었습니다. 고정된 페이지 컨텐츠의 경우 gettext 를, 사용자 입력 데이터의 경우 django-modeltranslation 을 이용하여 원활한 다국어 지원을 하고 있습니다.

  1. 다양한 실행환경을 대비한 반응형 웹디자인

노트북, 핸드폰 등 다양한 기기 지원을 위해 반응형 웹디자인을 적용하여 사용자 편의를 높였습니다. 한 번의 개발로 다양한 실행환경을 포괄할 수 있게 하여 신속한 서비스 구현을 가능케 합니다.

  1. 지속성 있는 유지보수를 위한 문서화

총학생회의 특성 상 세대교체가 빠르게 일어난다는 점에서 체계적인 인수인계는 필수적입니다. 역사적으로 보았을 때에도 수많은 홈페이지가 개발되었고, 그 중 상당수는 실질적인 서비스 시작을 하지도 못하고 사장되었습니다. 이번 사이트가 지속적 있는 총학생회 사이트로 남도록 하여 개발에 드는 불필요한 인력 및 자원 낭비를 매년의 총학생회가 하지 않도록 체계적인 문서화를 개발과 동시에 진행하고 있습니다.

프로젝트 기술 스택

배포환경

백엔드

프론트엔드

기타

프로젝트 구조

본 프로젝트 파일구조는 크게 배포환경 설정파일, 백엔드 소스, 프론트엔드 소스, 개발문서로 나뉩니다. 최상위 폴더(kaistusc)에 있는 낱개의 파일들은 보통 배포환경을 구축하기 위한 설정파일들이며, 백엔드 소스는 kaistusc/, apps/, middlewares/ 에 담겨있으며, 프론트엔드 소스는 static/src/ 에, 개발문서는 docs/ 에 위치해 있습니다.

아래는 프로젝트 최상위 폴더에 존재하는 디렉토리와 파일들에 대한 간략한 설명입니다. 알파벳 순으로 나열되어 있습니다.

  • apps/

Django 프로젝트 커스텀 앱을 모아놓는 디렉토리입니다. django-admin startapp 명령어를 통해 앱을 생성하면 기본적으로 프로젝트 최상위 폴더에 앱 디렉토리가 생기지만, 보다 원활한 관리를 위해 사용자가 제작한 커스텀 앱은 모두 apps 내부에 보관하는 것을 원칙으로 합니다.

기본적으로 게시판 기능을 구현한 board 앱, KAIST 단일인증서비스 를 이용하여 포탈 계정 로그인을 구현한 ksso 앱, 사이트 구조와 내부 서비스를 관리하고 접근권한을 설정하는 manager 앱 세 개가 포함되어 있습니다.

  • docs/

Sphinx로 생성한 사이트 개발문서가 들어있습니다. *.rst 파일들이 reStructuredText_ 로 작성된 문서 원본이며, make html 명령어를 실행하게 되면 docs/_build/html/ 내부에 HTML 파일들이 생성됩니다. Nginx 에서는 docs/_build/html/ 를 참조하여 개발문서 페이지를 제공합니다.

  • kaistusc/

Django 프로젝트 설정파일이 담겨있는 프로젝트 관리 디렉토리입니다. settings.py 나 urls.py, wsgi.py 등 django-admin startproject 를 실행하면 생성되는 기본 프로젝트 파일들이 있습니다.

  • locale/

외국어 번역 파일(*.po, *.mo)이 담겨 있습니다. 기본적으로 영어 번역이 존재하며, *.py, *.html, *.jinja 파일이 기본 번역 대상입니다.

  • middlewares/

Django 프로젝트에서 사용되는 커스텀 미들웨어가 들어있습니다. 기본으로 있는 locale.py 는 사용자가 설정한 언어로 페이지를 보여주는 기능을 지원합니다.

  • static/

프론트엔드 스태틱 파일과 소스가 담겨있습니다. static/src/ 에 프론트엔드 소스파일이 있으며, 이를 gulp 를 통해 배포 버전으로 빌드하게 되면 그 결과가 static/dist/ 에 저장됩니다. 물론 django의 collectstatic 명령은 static/ 전체 파일이 아닌, static/dist/ 내부 파일만 수집합니다. static/src/javascript/ 에는 자바스크립트 소스가, static/src/stylesheets/ 에는 Sass 소스가 담겨져 있습니다.

  • .dockerignore

Docker ignore 파일입니다.

  • .gitignore

Git ignore 파일입니다. 디펜던시들은 모두 무시되기 때문에 requirements.txt, package.json, bower.json 등을 통해 다운로드 및 설치를 진행해야 합니다.

  • Dockerfile

웹서버 이미지 빌드를 위한 도커 파일입니다. 기본적으로 우분투 16.04 환경에서 돌아가며, 아래 순서대로 빌드됩니다.

  1. 패키지 설치
  2. nginx.conf 를 이용한 웹서버 설정
  3. package.json 을 이용한 프론트엔드 빌드 도구 설치 및 bower.json 을 이용한 프론트엔드 라이브러리 다운로드
  4. 파이썬 가상환경 설정 및 requirements.txt 를 이용한 파이썬 라이브러리 설치
  5. 프로젝트 복사
  6. gulpfile.js 를 이용한 프론트엔드 소스 빌드 및 스태틱 수집
  7. 개발문서 생성
  8. Django 배포모드, 서버 인코딩, 포트 등 설정
  • README.md

프로젝트 설명 문서입니다.

  • bower.json

프론트엔드 디펜던시가 명시된 문서입니다. bower 를 통해 설치합니다.

  • docker-entrypoint.sh

도커 컨테이너가 실행될 때 수행되는 작업입니다. Django 마이그레이션을 진행하고 uWSGI, Nginx 를 실행합니다.

  • gulpfile.js

프론트엔드 소스파일을 배포환경에 맞게 빌드하는 gulp 파일입니다.

  • manage.py

Django 프로젝트 매니지 파일입니다.

  • mysql.cnf

MySQL 기본 설정파일입니다. 문자셋이나 바인드 주소에 관한 설정이 추가되어 있습니다.

  • nginx.conf

Nginx 설정파일입니다. 스태틱 파일, 미디어 파일, 개발문서를 제외한 나머지 요청은 UNIX 소켓으로 연결합니다. HTTPS 설정이 적용되어 있습니다.

  • package.json

프론트엔드 빌드 도구들이 명시된 파일입니다. npm 을 이용하여 설치합니다.

  • requirements.txt

파이썬 디펜던시가 명시된 파일입니다. pip 을 이용하여 일괄 설치할 수 있습니다.

  • uwsgi.ini

uWSGI 를 이용한 웹어플리케이션 서버 설정 파일입니다.

기여자 목록

  • 박항 <hangpark@kaist.ac.kr> - 프로그래밍, 문서화
  • 박병훈 - 웹디자인
  • 권용석 - 웹디자인