fossasia/eventyay

Eventyay는 FOSSASIA가 개발한 오픈 소스 이벤트 관리 플랫폼입니다. 이 플랫폼은 이벤트 티켓팅, 등록(registration), 참가자 모집(call for participation), 연사 및 세션 관리, 일정 계획, 온라인 이벤트 비디오, 참석자 체크인, 배지 인쇄, 주최자 관리 등 다양한 기능을 제공하며, API와 플러그인 기반 확장 기능도 지원합니다.

Eventyay는 2014년부터 개발되어 왔습니다. 시스템의 일부 구성 요소들은 역사적으로 티켓, 강연(talks), 비디오를 위한 별도의 컴포넌트에서 기원했습니다. 현재 리포지토리는 통합된 Eventyay 코드베이스를 담고 있습니다.

• 프로젝트 상태 및 브랜치 모델
• 주요 기능
• 기술 스택
• Docker를 사용한 빠른 시작
• Python 기반 로컬 개발
• 프론트엔드 개발
• 구성 개요
• 플러그인 및 확장 기능
• 별도의 Eventyay 컴포넌트
• 번역 워크플로우
• 공통 개발 명령어
• API 및 서비스 엔드포인트
• 리포지토리 레이아웃
• 기여자 아키텍처 규칙
• 문제 해결
• 배포
• 문서화
• 기여하기
• 법률 및 라이선스

Eventyay는 활발하게 개발되고 있습니다.

이 리포지토리는 다음 브랜치 모델을 사용합니다:

main은 프로덕션 준비가 된(production ready) 브랜치입니다. dev는 테스트 및 활성 개발 브랜치입니다.

풀 리퀘스트(Pull requests)는 일반적으로 dev를 대상으로 해야 합니다. 변경 사항은 여기서 테스트되고 안정화된 후에야 프로덕션 준비 릴리스를 위해 main으로 이동됩니다.

Eventyay가 포함하는 기능:

• 이벤트 티켓팅 및 등록
• 셔츠나 추가 상품 같은 이벤트 관련 품목 판매
• 주최자 및 이벤트 관리
• 참가 신청(Call for Participation) 워크플로우
• 연사, 제출물, 심사, 일정 관리
• 공개 이벤트 페이지
• 일정 표시 및 일정 편집기 프론트엔드
• 온라인 이벤트 및 비디오 관련 워크플로우
• Eventyay Checkin 컴포넌트를 통한 별도 체크인 스테이션 지원
• PDF 티켓 및 배지 관련 워크플로우
• REST API 엔드포인트
• OAuth 및 소셜 인증 지원
• 멀티 도메인 및 멀티 이벤트 처리
• 플러그인 검색 및 플러그인 URL 등록
• 결제, CRM, 전시회, 소셜 미디어, 팀 교대 근무, 통역, 공간 이벤트 통합을 위한 표준 플러그인 및 외부 플러그인 확장 기능
• 이메일, 알림, 예약 작업, 보고서, 통계, 체크인 목록
• 상태 확인(Health check) 및 메트릭 엔드포인트
• Hosted Weblate 기반 브라우저 번역 워크플로우를 갖춘 국제화 및 번역 인프라

백엔드:

• Python 3.12
• Django 5.2
• Django REST Framework
• PostgreSQL
• Redis
• Celery
• Django Channels
• Daphne / ASGI
• Pydantic settings
• uv for Python dependency management

프론트엔드:

• Vue 3
• Vite
• 프론트엔드 모듈에 따라 JavaScript 및 TypeScript 사용
• SCSS / Stylus
• 선택된 레거시 및 Django 통합 자산용 Django Compressor

로컬 개발과 초기 테스트를 위해 Docker가 권장되는 시작 방법입니다. 프로덕션 또는 셀프 호스팅 서버 배포는 아래의 Deployment 섹션과 DEPLOYMENT.md를 참조하세요.

.

로컬 Docker 스택은 Django 웹 서비스, Celery 워커, Celery beat, Redis, 그리고 PostgreSQL을 시작합니다. 또한 로컬 플러그인 개발을 위해 ./plugins를 마운트합니다.

요구 사항:

• Docker
• Docker Compose 플러그인
• Git

단계:

git clone https://github.com/fossasia/eventyay.git
cd eventyay
git switch dev
...

관리자 사용자 생성:

docker exec -ti eventyay-next-web python manage.py create_admin_user

로컬 사이트 열기:

로그 보기:

개발 스택 중지:

docker compose down

디렉터리 app/eventyay는 Docker 컨테이너에 마운트되므로 백엔드 코드를 라이브로 편집하는 것이 지원됩니다.

이 설정은 서비스를 직접 로컬 머신에서 실행하고 싶을 때 사용하세요.

필수 요구 사항:

• Python 3.12
• uv
• PostgreSQL
• Redis
• Node.js 및 npm
• deb-packages.txt에 나열된 Debian 또는 Ubuntu 패키지

또는 사용 중인 배포판에 맞는 동등한 패키지

리포지토리 클론:

git clone https://github.com/fossasia/eventyay.git
cd eventyay
git switch dev

Debian 또는 Ubuntu에서 외부 종속성 설치:

xargs -a deb-packages.txt sudo apt install

Nushell의 경우:

open deb-packages.txt | lines | sudo apt install ...$in

다른 Linux 배포판을 사용하는 경우, deb-packages.txt에서 해당 패키지를 설치하세요.

.
uv 설치.

사용하는 배포판에 따라 Redis를 설치하고 실행합니다.

PostgreSQL 데이터베이스 생성. 기본 로컬 데이터베이스 이름은 다음과 같습니다:

eventyay-db

Linux의 경우, 가장 간단한 로컬 개발 설정은 PostgreSQL peer 모드입니다. 자신의 Linux 사용자 이름과 동일한 이름으로 PostgreSQL 사용자를 생성하세요:

sudo -u postgres createuser -s "$USER"

그런 다음 자신의 사용자가 소유한 데이터베이스를 생성합니다:

createdb eventyay-db

이렇게 하면 비밀번호, 호스트 또는 포트를 지정하지 않고도 데이터베이스에 접근할 수 있습니다:

psql eventyay-db

PostgreSQL peer 모드를 사용할 수 없는 경우, 다음 데이터베이스 연결 값을 포함하는 app/eventyay.local.toml을 생성하세요:

postgres_user = "your_db_user"
postgres_password = "your_db_password"
postgres_host = "localhost"
...

앱 디렉터리로 이동:

cd app

Python 종속성 설치:

uv sync --all-extras --all-groups

가상 환경 활성화:

. .venv/bin/activate

마이그레이션 실행:

python manage.py migrate

관리자 사용자 생성:

python manage.py create_admin_user

프론트엔드 및 정적 자산 빌드:

make npminstall
python manage.py collectstatic --noinput
python manage.py compress --force

개발 서버 실행:

python manage.py runserver

Open:

백그라운드 작업을 처리할 때 Celery를 로컬에서 실행하려면:

celery -A eventyay worker -l info

Android 에뮬레이터에서 사이트를 테스트하려면 다음을 사용하세요:

이것은 Android가 호스트 머신의 localhost에 사용하는 별칭입니다.

만약 eventyay/static/CACHE에 대해 권한 오류가 발생한다면, 해당 디렉터리와 그 아래의 모든 파일들이 사용자 소유인지 확인하세요.

저장소에는 app/eventyay/webapp/ 경로 아래 여러 프론트엔드 애플리케이션이 포함되어 있습니다:

app/eventyay/webapp/
├── schedule/ 스케줄 표시 웹 컴포넌트
├── schedule-editor/ 스케줄 편집기 프론트엔드
...

루트 앱의 Makefile은 npm을 통해 이러한 프론트엔드 애플리케이션들을 설치하고 빌드하며, 컴파일된 에셋들을 Django 앱 데이터 디렉터리에 배치합니다.

체크인(Check-in) 기능은 별도의 eventyay-checkin 플러그인을 사용하며, Makefile의 npminstall 타겟으로는 빌드되지 않습니다.

기본적으로 Docker는 미리 빌드된 프론트엔드 에셋을 제공합니다. 프론트엔드 개발을 위해 핫 모듈 교체(Hot Module Replacement, HMR)를 활성화하려면 .env.dev 파일에 다음을 설정하세요:

EVY_NPM_DEV=1

.env.dev에서 EVY_NPM_DEV=1로 설정하면, Docker 이미지 빌드 시 make npminstall이 건너뛰어지고, Vite 개발 서버가 컨테이너 내부에서 자동으로 시작되며 필요한 npm 종속성을 설치하고 HMR과 함께 웹앱을 제공합니다.

schedule-editor는 포트 8080에서 실행됩니다.
.video는 포트 8880에서 실행됩니다.
.schedule는 포트 8082에서 실행됩니다.
.eventyay-checkin은 플러그인 체크아웃이 plugins/eventyay-checkin에 마운트될 때 포트 8085에서 실행됩니다.

일반적으로 이러한 포트들을 직접 방문할 필요는 없습니다. 프론트엔드는 핫 모듈 교체와 함께 http://localhost:8000과 함께 작동합니다.

환경 변경 사항이 적용되려면 컨테이너를 재시작하는 것이 아니라 재생성해야 합니다:
docker compose up -d --build web

기본값은 다음과 같습니다:
EVY_NPM_DEV=0

EVY_NPM_DEV=0인 경우, Django가 미리 빌드된 에셋을 제공하므로 프론트엔드 변경 후에는 make npminstall을 실행하세요. 프론트엔드 변경 사항을 제출하기 전에는 항상 기본값으로 프로덕션 에셋 빌드가 여전히 작동하는지 확인하세요:

Eventyay의 설정은 TOML 파일, 환경 변수(environment variables), dotenv 파일 및 비밀 파일(secret files)을 기반으로 합니다. 가능한 설정 키와 기본값을 확인하려면 app/eventyay/config/settings.py에 있는 BaseSettings 클래스를 확인하세요.

설정은 세 가지 실행 환경(running environments)으로 나뉩니다:

• development: eventyay.development.toml의 기본값을 사용합니다.
• production: eventyay.production.toml의 기본값을 사용합니다.
• testing: eventyay.testing.toml의 기본값을 사용합니다.

이 파일들의 값은 BaseSettings에 정의된 값을 덮어씁니다.

실행 환경은 EVY_RUNNING_ENVIRONMENT 환경 변수를 통해 선택됩니다. 이 변수는 manage.py, wsgi.py, 및 asgi.py에 미리 설정되어 있습니다.

예를 들어, production 환경에서 명령을 실행하려면 다음과 같이 합니다:
EVY_RUNNING_ENVIRONMENT=production ./manage.py command

설정 소스(Configuration sources)는 다음 우선순위로 로드됩니다:

1. .secrets/의 비밀 파일 (Secret files)
2. 현재 작업 디렉터리에 있는 EVY_ 접두사가 붙은 환경 변수 (eventyay.local.toml 포함)
3. eventyay.development.toml, eventyay.production.toml, 또는 eventyay.testing.toml과 같은 환경별 TOML 파일

manage.py 파일과 같은 폴더에 eventyay.local.toml이라는 파일을 생성하세요.

덮어쓰고 싶은 값만 추가합니다. 예를 들어, debug 값을 덮어쓰려면 다음과 같이 추가합니다:
debug = true

데이터베이스 연결 값의 경우, 로컬 덮어쓰기는 다음과 같을 수 있습니다:

postgres_user = "your_db_user"
postgres_password = "your_db_password"
postgres_host = "localhost"
...

리스트와 같은 복잡한 값의 경우, 환경 변수보다 TOML 파일을 선호하는 것이 좋습니다.

환경 변수를 통해서도 값을 덮어쓸 수 있습니다. 환경 변수 이름은 설정 키(setting keys)의 대문자 버전이며 EVY_가 접두사로 붙습니다.

예를 들어, debug 값을 덮어쓰려면 다음과 같습니다:

.env 파일도 지원됩니다.

.env에서 값을 가져오지만, 환경 변수에 의해 덮어쓰여집니다.

비밀번호나 API 키와 같은 민감한 데이터는 .secrets 디렉터리의 파일들을 통해 제공해야 하며, 키당 하나의 파일을 사용합니다. 파일 이름은 EVY_ 접두사가 붙은 환경 변수 이름과 동일한 패턴을 따릅니다. 파일 내용은 해당 값이 됩니다.

예를 들어, secret_key 설정을 위한 값을 제공하려면 다음 파일을 생성합니다:

.secrets/EVY_SECRET_KEY

앱을 Docker 컨테이너를 통해 배포하는 경우, Docker secrets를 통해 비밀 데이터를 제공할 수 있습니다.

개발 환경에서는 OpenCage나 MapQuest 키가 구성되지 않은 경우 Nominatim 지오코딩이 자동으로 사용됩니다. 프로덕션 배포 시에는 지오코딩 공급자를 설정하거나 전역 설정에서 공개 Nominatim 지오코딩을 명시적으로 활성화해야 합니다.

기본적으로 이메일은 콘솔 백엔드를 통해 터미널 로그에 출력됩니다.

실제 전달되는 이메일 관련 기능을 테스트하려면 SendGrid, Gmail SMTP 또는 다른 SMTP 공급자와 같은 메일 서버를 구성해야 합니다.

Gmail SMTP의 경우 다음을 사용합니다:

Host: smtp.gmail.com
Port: 587
TLS: enabled

Google 계정에 2FA(2단계 인증)가 활성화된 경우, 앱 비밀번호를 사용해야 할 수 있습니다.

Eventyay는 표준 설정의 일부인 여러 플러그인을 제공합니다. 이 내장 플러그인들은 인증, 보고서, 배지, 체크인 워크플로우, 예약 작업, 통계 및 티켓 출력에 대한 일반적인 기능을 제공합니다.

내장 및 표준 플러그인 영역에는 다음이 포함됩니다:

• 인증 및 소셜 인증(Authentication and social auth)
• 은행 송금(Bank transfer)
• 배지(Badges)
• Sendmail
• 통계(Statistics)
• 보고서(Reports)
• 체크인 목록(Check-in lists)
• 수동 결제(Manual payment)
• 리턴 URL(Return URLs)
• 예약 작업(Scheduled tasks)
• PDF 티켓 출력(PDF ticket output)

Eventyay는 또한 외부 플러그인 확장도 지원합니다. 이 플러그인들은 통합이나 이벤트별 특정 기능을 추가하기 위해 설치할 수 있습니다.

사용 가능한 플러그인 확장은 다음과 같습니다:

• eventyay-exhibition: 전시 부스 컴포넌트
• eventyay-interpretation: Voxbento와 같은 해석 서비스와의 통합
• eventyay-hubspot: HubSpot 통합
• eventyay-loungemesh: Loungemesh 통합
• eventyay-socialmedia: 소셜 미디어 공유 및 게시 통합
• eventyay-veditor: 비디오 리뷰, 트랜스코딩(transcode), 스튜디오 편집 통합
• eventyay-teamshifts: 팀 교대 근무 및 자원봉사자 교대 근무 관리 플러그인

사용 가능한 결제 플러그인은 다음과 같습니다:

• eventyay-bitpay: BitPay 암호화폐 결제 통합
• eventyay-paypal: PayPal 결제 통합
• eventyay-stripe: Stripe 결제 통합

새로운 Eventyay 플러그인을 생성하려면 eventyay 플러그인 cookiecutter 템플릿을 사용하세요.

Eventyay는 설치된 Django 앱 및 Python entry points를 통해 호환 가능한 플러그인을 자동으로 발견합니다. 플러그인 메타데이터와 URL 모듈이 사용 가능할 때 플랫폼은 플러그인 URL 패턴을 자동으로 등록할 수 있습니다.

플러그인을 개발하는 경우, 이 저장소의 루트에 plugins라는 디렉토리를 만드세요.
이 디렉토리는 gitignore되며 로컬 플러그인 체크아웃을 포함할 수 있습니다.

예시:

.
└── eventyay/
└── plugins/
...

로컬 플러그인 개발은 .env.dev의 두 가지 플래그에 의해 제어됩니다:

EVY_PLUGIN_DEV_MODE=1
(기본값): ./plugins/를 스캔하고 Python 플러그인을 편집 가능한 모드(editable mode)로 설치하여 코드 변경 사항이 즉시 반영되도록 합니다. 만약 EVY_NPM_DEV=1이고 ./plugins/eventyay-checkin