멀티테넌트 조직 관리 및 태스크 관리 플랫폼
| 구성요소 | 버전 | 용도 |
|---|---|---|
| Ruby | 3.4.5+ | 백엔드 언어 |
| Rails | 8.0.2+ | 웹 프레임워크 |
| Node.js | 18+ | 프론트엔드 빌드 도구 |
| PostgreSQL | 14+ | 메인 데이터베이스 |
| MongoDB | 6.0+ | 로그 데이터베이스 |
| Git | 2.0+ | 버전 관리 |
# 1️⃣ 저장소 클론
git clone https://github.com/YuJM/creatia-app.git
cd creatia-app
# 2️⃣ 환경변수 설정
cp env.example .env
# 3️⃣ 의존성 설치
bundle install && npm install
# 4️⃣ 데이터베이스 설정
bin/rails db:create db:migrate db:seed
# 5️⃣ MongoDB 시작 (새 터미널에서)
cd docker/mongodb && make up
# 6️⃣ 서버 실행
bin/rails server🎉 완료! http://localhost:3000 에서 앱을 확인하세요!
서버가 정상적으로 실행되었는지 확인:
# 헬스체크
curl http://localhost:3000/up
# 응답: {"status":"ok","timestamp":"2025-01-XX..."}시드 데이터로 생성된 기본 계정:
- 이메일:
[email protected] - 비밀번호:
password123 - 조직:
demo(http://demo.creatia.local:3000)
| 서브도메인 | URL | 용도 |
|---|---|---|
| 메인 | localhost:3000 |
랜딩 페이지, 사용자 등록 |
| 인증 | auth.creatia.local:3000 |
SSO, 로그인/로그아웃 |
| 조직 | {org}.creatia.local:3000 |
조직별 대시보드, 태스크 관리 |
| API | api.creatia.local:3000 |
REST API 엔드포인트 |
| 관리자 | admin.creatia.local:3000 |
시스템 관리 |
- 🏢 멀티테넌트 조직 관리: 완전한 데이터 격리
- 👥 사용자 관리: Devise 기반 인증, 역할 기반 권한 (RBAC)
- 📋 태스크 관리: 조직별 태스크 생성, 할당, 추적
- 🔐 보안: CanCanCan 권한 시스템, CSRF 보호
- 🌐 RESTful API: Alba 직렬화로 깔끔한 JSON API
- 📊 로깅: MongoDB 기반 활동/에러/API 로그 수집 및 분석
- 🔄 실시간 업데이트: Hotwire Turbo로 SPA 경험
- 🎨 모던 UI: Tailwind CSS 기반 반응형 디자인
| 데이터베이스 | 용도 | 저장 데이터 |
|---|---|---|
| PostgreSQL | 메타데이터, 관계형 데이터 | 사용자, 조직, 권한, 설정 |
| MongoDB | 실행 데이터, 로그, 실시간 협업 데이터 | 태스크, 스프린트, 활동로그, 성능지표 |
- Task: MongoDB 기반 실행 데이터, 스냅샷 기반 성능 최적화
- Sprint: 애자일 스프린트 관리, 번다운 차트
- Milestone: 프로젝트 마일스톤 추적
- Organization: 멀티테넌트 컨테이너, 서브도메인 기반
- User: Devise 인증, OAuth 지원 (Google, GitHub)
- Team: 팀 기반 협업, 권한 위임
- Role: 동적 역할 생성, 시스템/커스텀 역할
- Permission: 세분화된 권한 제어
- PermissionAuditLog: 권한 변경 추적
# Ruby 설치 (rbenv 권장)
brew install rbenv ruby-build
rbenv install 3.4.5
rbenv global 3.4.5
# Node.js 설치
brew install node@18
# PostgreSQL 설치
brew install postgresql@14
brew services start postgresql@14
# Podman 설치 (MongoDB용)
brew install podman podman-compose
podman machine init && podman machine start# Ruby 설치
curl -fsSL https://github.com/rbenv/rbenv-installer/raw/HEAD/bin/rbenv-installer | bash
rbenv install 3.4.5 && rbenv global 3.4.5
# Node.js 설치
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
# PostgreSQL 설치
sudo apt-get install postgresql postgresql-contrib
# Docker 설치 (MongoDB용)
sudo apt-get install docker.io docker-compose# 저장소 클론
git clone https://github.com/YuJM/creatia-app.git
cd creatia-app
# 환경변수 설정
cp env.example .env중요: .env 파일에서 다음 설정을 확인하세요:
# 데이터베이스 설정
DATABASE_HOST=localhost
DATABASE_USERNAME=postgres
DATABASE_PASSWORD=your_password
# MongoDB 설정
MONGODB_URI=mongodb://creatia_user:creatia_pass@localhost:27017/creatia_logs
# 도메인 설정
BASE_DOMAIN=creatia.local# Ruby gems 설치
bundle install
# Node.js 패키지 설치
npm install
# Rails 자산 컴파일
bin/rails assets:precompile# PostgreSQL 데이터베이스 생성 및 마이그레이션
bin/rails db:create
bin/rails db:migrate
bin/rails db:seed
# MongoDB 컨테이너 시작
cd docker/mongodb
make up
# MongoDB 연결 테스트
cd ../..
bin/rails mongoid:test_connection# 개발 서버 시작
bin/rails server
# 또는 백그라운드에서 실행
bin/rails server -d완전한 멀티테넌트 기능을 위해 서브도메인 설정:
# hosts 파일에 추가 (macOS/Linux)
sudo vim /etc/hosts
# 다음 라인들 추가:
127.0.0.1 creatia.local
127.0.0.1 auth.creatia.local
127.0.0.1 api.creatia.local
127.0.0.1 admin.creatia.local
127.0.0.1 demo.creatia.local# 개발 서버 (Hot Reload 포함)
bin/dev
# 또는 개별 프로세스
bin/rails server # 웹 서버
bin/rails tailwindcss:watch # CSS 컴파일
bin/caddy # 리버스 프록시 (서브도메인용)# 개발 서버 시작
bin/dev # 모든 서비스 (Rails + CSS + MongoDB)
# 디버깅
bin/rails console
> Rails.logger.level = :debug
# 코드 품질 검사
bundle exec rubocop
bundle exec brakeman📖 상세 가이드: 개발환경 설정 가이드에서 IDE 설정, 디버깅 도구, 성능 최적화 등을 확인하세요.
# 데이터베이스 관리
bin/rails db:reset # DB 초기화
bin/rails db:seed # 시드 데이터 로드
bin/rails console # Rails 콘솔
# MongoDB 관리
bin/rails mongoid:stats # 로그 통계
bin/rails mongoid:create_sample_logs # 샘플 로그 생성
bin/rails mongoid:clear_logs # 모든 로그 삭제
# 코드 품질
bundle exec rubocop # 코드 스타일 검사
bundle exec brakeman # 보안 검사
bundle exec rspec # 테스트 실행.env 파일에서 주요 설정:
# ===========================================
# 기본 애플리케이션 설정
# ===========================================
RAILS_ENV=development
APP_DOMAIN=localhost:3000
BASE_DOMAIN=creatia.local
USE_HTTPS=false
# ===========================================
# PostgreSQL 데이터베이스 (메타데이터)
# ===========================================
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USERNAME=postgres
DATABASE_PASSWORD=your_password
DATABASE_NAME=creatia_development
# ===========================================
# MongoDB (실행 데이터, 로그)
# ===========================================
MONGODB_URI=mongodb://creatia_user:creatia_pass@localhost:27017/creatia_logs
MONGODB_HOST=localhost
MONGODB_PORT=27017
MONGODB_DATABASE=creatia_logs
MONGODB_USERNAME=creatia_user
MONGODB_PASSWORD=creatia_pass
# ===========================================
# 인증 및 보안
# ===========================================
# JWT 시크릿 (SSO용)
JWT_SECRET=your_jwt_secret_key
# Devise 시크릿
SECRET_KEY_BASE=your_rails_secret_key
# OAuth 제공자 (선택사항)
GOOGLE_OAUTH_CLIENT_ID=your_google_client_id
GOOGLE_OAUTH_CLIENT_SECRET=your_google_client_secret
GITHUB_OAUTH_CLIENT_ID=your_github_client_id
GITHUB_OAUTH_CLIENT_SECRET=your_github_client_secret
# ===========================================
# 외부 서비스 통합
# ===========================================
# GitHub 웹훅 (선택사항)
GITHUB_WEBHOOK_SECRET=your_webhook_secret
# 알림 서비스 (선택사항)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=your_smtp_user
SMTP_PASSWORD=your_smtp_password
# ===========================================
# 보안 설정 (중요!)
# ===========================================
# 프로덕션에서는 반드시 강력한 비밀번호 사용
# 개발환경에서도 실제 서비스와 구별되는 값 사용
# Rails Master Key (config/master.key에서 자동 생성)
# RAILS_MASTER_KEY=your_master_key_here
# CORS 설정 (API 서브도메인용)
CORS_ORIGINS=https://creatia.local,https://app.creatia.local
# 로그 레벨 설정
LOG_LEVEL=info # debug, info, warn, error
# 세션 만료 시간 (분)
SESSION_TIMEOUT=480 # 8시간
# JWT 토큰 만료 시간
JWT_EXPIRATION=24h # 24시간# 보안 검사 도구
bundle exec brakeman # 보안 취약점 검사
bundle audit # 의존성 보안 검사
bundle exec rubocop --only Security/ # 코드 보안 규칙📖 상세 가이드: 보안 가이드에서 인증 보안, 네트워크 보안, 데이터베이스 보안 등 포괄적인 보안 설정을 확인하세요.
# 전체 테스트 실행
bundle exec rspec
# 시스템 통합 테스트 (권장)
bundle exec rspec spec/system/
# CI용 핵심 테스트
bundle exec rspec spec/system/ci_integration_spec.rb
# E2E 테스트 (Playwright)
npm run e2e
npm run e2e:headed # 브라우저에서 확인
npm run e2e:debug # 디버그 모드
# 커버리지 확인
open coverage/index.html| 테스트 타입 | 위치 | 용도 |
|---|---|---|
| Unit Tests | spec/models/, spec/services/ |
개별 컴포넌트 테스트 |
| Integration Tests | spec/requests/, spec/routing/ |
API 엔드포인트 테스트 |
| System Tests | spec/system/ |
전체 사용자 플로우 |
| Feature Tests | spec/features/ |
BDD 스타일 기능 테스트 |
| E2E Tests | e2e/ |
브라우저 자동화 테스트 |
# 테스트 데이터 생성
bundle exec rails db:seed RAILS_ENV=test
# 팩토리 데이터 확인
bundle exec rails console -e test
> FactoryBot.create(:user)
> FactoryBot.create(:organization)# Docker 이미지 빌드
docker build -t creatia-app .
# 컨테이너 실행
docker run -p 3000:3000 \
-e DATABASE_URL=postgresql://user:pass@host:5432/db \
-e MONGODB_URI=mongodb://user:pass@host:27017/logs \
creatia-app# Heroku CLI 설치
brew install heroku/brew/heroku
# 앱 생성 및 배포
heroku create your-app-name
heroku addons:create heroku-postgresql:hobby-dev
heroku addons:create mongolab:sandbox
git push heroku main# .do/app.yaml
name: creatia-app
services:
- name: web
source_dir: /
github:
repo: YuJM/creatia-app
branch: main
run_command: bundle exec rails server -p $PORT
environment_slug: ruby
instance_count: 1
instance_size_slug: basic-xxs
envs:
- key: RAILS_ENV
value: production
- key: DATABASE_URL
value: ${db.DATABASE_URL}# Kamal 설정
kamal setup
# 배포 실행
kamal deploy
# 롤백
kamal rollback# 포트 사용 프로세스 확인
lsof -i :3000
# 프로세스 종료
kill -9 $(lsof -ti:3000)# Gem 캐시 정리
bundle clean --force
rm -rf vendor/bundle
bundle install# node_modules 재설치
rm -rf node_modules package-lock.json
npm install# PostgreSQL 서비스 확인 (macOS)
brew services list | grep postgresql
# PostgreSQL 재시작
brew services restart postgresql@14
# 데이터베이스 재생성
bin/rails db:drop db:create db:migrate db:seed# MongoDB 컨테이너 상태 확인
cd docker/mongodb
make status
# MongoDB 재시작
make down && make up
# 연결 테스트
bin/rails mongoid:test_connection# 개발 로그 실시간 확인
tail -f log/development.log
# 에러 로그만 확인
tail -f log/development.log | grep ERROR
# 테스트 로그
tail -f log/test.log
# Rails 콘솔에서 로그 확인
bin/rails console
> Rails.logger.info "테스트 메시지"# Rails 콘솔
bin/rails console
# 데이터베이스 콘솔
bin/rails dbconsole
# Rails 환경 확인
bin/rails runner "puts Rails.env"
# 의존성 확인
bundle exec rails runner "puts Rails.version"- 📚 상세 문서 - 프로젝트 내 상세 가이드
- 🐛 Issues - 버그 리포트
- 💬 Discussions - 질문 및 토론
# Rails 콘솔에서
bin/rails console
# 새 조직 생성
org = Organization.create!(
name: "새로운 조직",
subdomain: "neworg",
owner: User.first
)# 조직에 사용자 추가
user = User.create!(email: "[email protected]", password: "password123")
org.users << user
# 사용자에게 역할 부여
user.add_role(:member, org)# 새 태스크 생성
task = Task.create!(
title: "새로운 태스크",
description: "태스크 설명",
organization: org,
assignee: user,
status: "todo"
)# 태스크 진행 상태 업데이트
task.update!(status: "in_progress")
task.update!(status: "completed")# 개발/테스트 환경에서 API 호출
curl -u "[email protected]:password123" \
http://localhost:3000/api/v1/tasks# 사용자 권한 확인
user.can?(:read, Task)
user.can?(:create, Task)
user.can?(:manage, org)# MongoDB에서 로그 조회
bin/rails console
> ActivityLog.where(action: "task.created").limit(10)
# 로그 통계
bin/rails mongoid:stats# API 호출 로그 확인
> ApiLog.where(endpoint: "/api/v1/tasks").count
> ApiLog.where(created_at: 1.day.ago..Time.current).countCreatia App은 RESTful API를 통해 모든 기능에 접근할 수 있습니다.
# 1. JWT 토큰 발급
curl -X POST http://api.creatia.local:3000/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "[email protected]", "password": "password123", "organization_subdomain": "demo"}'
# 2. API 호출
curl -H "Authorization: Bearer YOUR_TOKEN" \
http://api.creatia.local:3000/api/v1/tasks
# 3. 상태 확인
curl http://api.creatia.local:3000/api/v1/health/status📖 상세 가이드: API 사용 가이드에서 인증, 태스크 관리, 조직 관리 등 전체 API 사용법을 확인하세요.
| 문서 | 설명 |
|---|---|
| 🚀 API 사용 가이드 | JWT 인증, RESTful API 완전 가이드 |
| 🔒 보안 가이드 | 인증, 네트워크, DB 보안 체크리스트 |
| 🔧 개발환경 설정 | IDE 설정, 디버깅, 성능 최적화 |
| 🏗️ 데이터베이스 아키텍처 | PostgreSQL + MongoDB 하이브리드 |
| 문서 | 설명 |
|---|---|
| 앱 설치 및 문제 해결 | 설치 과정 및 트러블슈팅 |
| 시스템 통합 테스트 | 포괄적인 테스트 스위트 구현 |
| 멀티테넌트 가이드 | 멀티테넌트 아키텍처 설명 |
| 디자인 시스템 | UI 컴포넌트 가이드 |
| 문서 | 설명 |
|---|---|
| 프로젝트 구조 | 디렉토리 구조 및 책임 |
| 역할 및 권한 | RBAC 시스템 설명 |
| 시간 추적 시스템 | 시간 관리 기능 |
| 기술 | 버전 | 용도 |
|---|---|---|
| Ruby | 3.4.5+ | 프로그래밍 언어 |
| Rails | 8.0.2+ | 웹 프레임워크 |
| PostgreSQL | 14+ | 메인 데이터베이스 |
| MongoDB | 6.0+ | 로그 데이터베이스 |
| Devise | 4.9+ | 인증 시스템 |
| CanCanCan | 3.6+ | 권한 관리 |
| ActsAsTenant | 1.0+ | 멀티테넌트 |
| Alba | 3.5+ | JSON 직렬화 |
| 기술 | 버전 | 용도 |
|---|---|---|
| Hotwire | 8.0+ | SPA 경험 |
| Tailwind CSS | 4.1+ | 스타일링 |
| Stimulus | 3.0+ | JavaScript 프레임워크 |
| ViewComponent | 3.20+ | 컴포넌트 시스템 |
| 기술 | 용도 |
|---|---|
| RSpec | 테스트 프레임워크 |
| Factory Bot | 테스트 데이터 |
| Capybara | 통합 테스트 |
| Playwright | E2E 테스트 |
| SimpleCov | 코드 커버리지 |
| Rubocop | 코드 스타일 |
| Brakeman | 보안 검사 |
# 1. 저장소 포크 및 클론
git clone https://github.com/YOUR_USERNAME/creatia-app.git
cd creatia-app
# 2. 기능 브랜치 생성
git checkout -b feature/your-feature-name
# 3. 개발 및 테스트
# ... 코드 작성 ...
bundle exec rspec
npm run e2e
# 4. 커밋 및 푸시
git add .
git commit -m "feat: 새로운 기능 추가"
git push origin feature/your-feature-name
# 5. Pull Request 생성
# GitHub에서 Pull Request 생성# 코드 스타일 검사
bundle exec rubocop
# 자동 수정
bundle exec rubocop -A
# 보안 검사
bundle exec brakeman
# 테스트 실행
bundle exec rspec spec/system/ci_integration_spec.rbfeat: 새로운 기능 추가
fix: 버그 수정
docs: 문서 수정
style: 코드 스타일 변경
refactor: 코드 리팩토링
test: 테스트 추가/수정
chore: 빌드 프로세스 또는 도구 변경
| 지표 | 목표 | 모니터링 |
|---|---|---|
| 페이지 로드 시간 | < 3초 | ✅ |
| 데이터베이스 쿼리 | < 15개/페이지 | ✅ |
| 메모리 사용량 | 모니터링 중 | 🔄 |
| API 응답 시간 | < 500ms | ✅ |
# 앱 상태 확인
curl http://localhost:3000/up
# 응답: {"status":"ok","timestamp":"..."}
# 데이터베이스 연결 확인
curl http://localhost:3000/health/database
# MongoDB 연결 확인
curl http://localhost:3000/health/mongodb- 🚀 앱 설치 및 실행 환경 구축
- 🔧 라우팅 중복 문제 해결 (devise_for, root 라우트)
- 🔐 인증 오류 수정 (current_user 메서드 문제)
- 🧪 시스템 레벨 통합 테스트 구현
- 애플리케이션 부팅 검증
- HTTP 요청 플로우 테스트
- 서브도메인별 기능 테스트
- 인증 플로우 통합 테스트
- CI/CD용 핵심 테스트
- 📊 성능 및 보안 기준선 설정
- 📚 포괄적인 문서화
- ✅ 18개 시스템 테스트 중 17개 통과
- 🔍 설정 오류 조기 발견 시스템 구축
- 🚀 CI/CD 파이프라인 품질 보장
- 💪 개발 효율성 및 안정성 향상
- 🔄 실시간 알림 시스템
- 📱 모바일 앱 API
- 🔍 고급 검색 기능
- 📊 대시보드 분석
- 🌐 다국어 지원
이 프로젝트는 ISC License 하에 배포됩니다.
- Rails Community - 훌륭한 프레임워크 제공
- Contributors - 프로젝트에 기여해주신 모든 분들
- Open Source - 오픈소스 생태계에 감사드립니다
🚀 Creatia App: 안정적이고 확장 가능한 멀티테넌트 플랫폼을 구축하고 있습니다.
문서가 도움이 되었다면 ⭐ 스타를 눌러주세요!