Crewspace

외부 SaaS 형태의 프로젝트 관리 도구를 사용할 수 없는 환경을 위해 만든 셀프 호스팅 프로젝트 관리 시스템입니다. 보안 정책이나 네트워크 제약으로 Jira, Notion 같은 외부 서비스를 쓸 수 없는 팀이 자체 서버에 설치하여 사용할 수 있습니다.

칸반 보드, 타임라인(Gantt), 팀/프로젝트 관리, 대시보드 등 프로젝트 관리에 필요한 기능을 제공합니다.

화면

칸반 보드

카드를 드래그 앤 드롭으로 상태 변경하고, Epic > Story > Task > Sub-task 계층 구조로 작업을 관리합니다.

타임라인

Gantt 차트 형태로 일정을 시각화하고, 계층 구조를 트리 커넥터로 표현합니다.

주요 기능

• 칸반 보드 - 드래그 앤 드롭, 카드 계층 구조(Epic/Story/Task/Sub-task), 완료 카드 자동 숨김
• 타임라인 - Gantt 차트, 트리 커넥터, 드래그 앤 드롭 순서 변경
• 팀 관리 - 팀 생성, 멤버 초대, 역할 기반 접근 제어
• 대시보드 - 프로젝트/카드 현황, 기한 초과 경고, 마감 임박 알림
• 관리자 패널 - 시스템 전체 사용자 및 팀 관리 (Superadmin 전용)
• 필터/검색 - 카드 타입, 담당자, 우선순위 필터링, 통합 검색

사전 준비

Docker로 실행하는 경우

• Docker, Docker Compose

직접 실행하는 경우

• Python 3.12+
• Node.js 20+
• PostgreSQL 16+

설치 및 실행

1. 저장소 클론

git clone https://github.com/your-org/crewspace.git
cd crewspace

2. 환경 변수 설정

cp .env.example .env

.env 파일을 열어 아래 항목을 수정합니다.

# PostgreSQL
POSTGRES_HOST=postgres          # 직접 실행 시 localhost로 변경
POSTGRES_PORT=5432
POSTGRES_DB=crewspace
POSTGRES_USER=crewspace
POSTGRES_PASSWORD=changeme_strong_password

# Host Port Mapping (Docker 사용 시)
HOST_BACKEND_PORT=8000
HOST_FRONTEND_PORT=3000
HOST_POSTGRES_PORT=5432

# JWT
SECRET_KEY=changeme_jwt_secret_key_at_least_32_chars
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=60
REFRESH_TOKEN_EXPIRE_DAYS=30

# CORS
CORS_ORIGINS=http://localhost:3000,http://localhost:5173

# Email
EMAIL_DOMAIN=example.com

# Superadmin (최초 실행 시 자동 생성)
SUPERADMIN_EMAIL=admin@crewspace.local
SUPERADMIN_USERNAME=admin
SUPERADMIN_PASSWORD=changeme_admin_password
SUPERADMIN_FORCE_SYNC=false  # true면 매 기동마다 위 계정 정보로 강제 동기화

# Backend 기동 옵션 (선택, 기본값 사용 시 생략 가능)
MIGRATION_MAX_RETRIES=30     # DB 준비 대기용 마이그레이션 재시도 횟수
MIGRATION_RETRY_DELAY=2      # 재시도 간격(초)
UVICORN_WORKERS=2            # 백엔드 워커 프로세스 수

POSTGRES_PASSWORD, SECRET_KEY, SUPERADMIN_PASSWORD는 반드시 기본값에서 변경하는 것을 권장합니다.

3-A. Docker로 실행 (권장)

Docker로 실행하는 것을 권장합니다.

docker compose up -d --build

최초 실행 시 DB 마이그레이션이 자동으로 적용됩니다. 백엔드는 PostgreSQL이 완전히 준비된 뒤에 기동하며, 마이그레이션이 실패하면 MIGRATION_MAX_RETRIES 횟수만큼 재시도합니다.

# 코드 변경 없이 재시작 (이미지 재빌드 불필요)
docker compose up -d

# 로그 확인
docker compose logs -f backend

# 상태 확인
docker compose ps

# 중지 (데이터는 named volume에 보존됨)
docker compose down

--build는 코드나 의존성이 바뀐 경우에만 필요합니다. docker compose down -v는 DB 볼륨까지 삭제하므로 주의하세요.

3-B. 직접 실행

PostgreSQL이 실행 중이어야 합니다. .env의 POSTGRES_HOST를 localhost로 변경하세요.

Backend:

cd backend
pip install -r requirements.txt
alembic upgrade head                              # DB 마이그레이션
python -m uvicorn app.main:app --reload --port 8000

Frontend:

cd frontend
npm install
npm run dev       # localhost:5173에서 실행, /api 요청은 localhost:8000으로 프록시

4. 접속

항목	URL
Frontend	http://localhost:3000 (Docker) / http://localhost:5173 (직접 실행)
Backend API	http://localhost:8000
API 문서 (Swagger)	http://localhost:8000/docs

최초 로그인은 .env에 설정한 Superadmin 계정으로 합니다.

폐쇄망 배포

인터넷이 차단된 서버에 배포할 수 있도록, Docker 이미지와 스크립트를 하나의 tar.gz로 묶는 오프라인 배포 패키지를 제공합니다.

# 온라인 PC에서 패키지 생성 (이미지 빌드 + docker save + 패키징)
bash deploy/scripts/prepare-offline.sh

# 폐쇄망 서버에서 배포
tar xzf ax-team-task-manage-deploy-YYYYMMDD.tar.gz
cd deploy && bash scripts/deploy.sh

배포 시 이미지는 docker load로만 공급되며, Compose가 레지스트리에 접근하지 않도록 모든 서비스에 pull_policy: never가 설정되어 있습니다.

기존 DB 유지, 구버전 스택에서의 데이터 이관, 백업/복원, 문제 해결은 deploy/README.md 를 참고하세요.

기술 스택

구분	기술
Backend	Python 3.12, FastAPI, SQLAlchemy 2.0 (async), Alembic
Frontend	React 18, TypeScript, Ant Design 5, TanStack Query
Database	PostgreSQL 16
Auth	JWT (Access Token 60min + Refresh Token 30days)
Infra	Docker, Docker Compose, Nginx

라이선스

MIT License