Hey + Emoji = Heymoji

개발자의 한마디 👨🏻‍💻

링크드인에서 매프 멤버들이 서로 토마토를 주는 이유는? 라는 글을 읽고, 슬랙 이모지(Emoji)로 멤버들에게 칭찬이나 리스펙 할 수 있는 문화가 생긴다면 재밌기도 하고 고마움도 표현할 수 있을 것 같았습니다.

그래서 이런 재미난 기능은 오픈소스로 공개하면 좋을 것 같다고 생각해서 토이 프로젝트로 만들어 보았습니다.
(근데 Nodejs로 만들어진게 이미 있었네요 heyburrito)

좀 더 재미난 기능 + 완성도 있는 프로젝트가 되기위해 유지보수는 지속적으로 할 예정입니다.💪
FastAPI에 구조나 프로젝트 관련된 추가기능, 개선사항 PR은 언제나 환영입니다!

👋 개요

Heymoji API서버는 Python 3.10, FastAPI 로 개발되었습니다.
그 외 버전에서 패키지 및 동작에 대한 호환은 보장하지 않습니다. (근데 거의 다 될거에요 python3.7 이상이면...아마두~😁 )
프론트엔드는 vuejs를 사용해서 간단히 만들어 봤습니다!

🛠 프로젝트 구조

처음 Heymoji를 개발할때는 DDD 구조가 아니었습니다.
DDD에 대한 스터디를 위해 구조를 변경했으며 https://github.com/Ermlab/python-ddd 를 참고하였습니다.
다소 복잡할 수 있으니 추후 유지보수와 여러 상태변경이 일어나는 경우 DDD가 좀 더 유연할 거라고 생각했습니다😁

├── apps
|   ├─ api 
|   |  ├── dependancy
|   |  └── router
|   ├─ applications 
|   |  └── services (Application Service)
|   ├─ domains
|   |  └─ user (도메인)
|   |     ├─ entities.py 
|   |     ├─ services.py (Domain Service)
|   |     ├─ repositories.py
|   |     └─ schemas.py	
|   ├─ infrastructure (infra 관련 정의 구조)
|   ├─ utils
|   ├─ tests
|   └─ main.py
├── conf
|   └── settings.py
├── scripts
├── migrations (alembic DB 마이그레이션 설정)
├── seed_work (프로젝트에서 기본적으로 제공해야하는 작업, 코드)
├── alembic.ini
├── requirements.txt
├── docker-compose.yaml
├── Dockerfile
├── web.Dockerfile
├── .env_sample
└── frontend (heymoji 웹페이지 관련 코드)

💾 세팅

.env_sample을 참고해서 .env파일을 생성합니다.
원하시는 세팅으로 환경변수들을 세팅합니다.
DB는 MySQL을 사용하며 비동기 처리를 위해 aiomysql라이브러리를 함께 사용합니다.
다른 DB 사용하려면 config 설정이 조금 달라질 수 있습니다.

이름	설명
ENV	배포환경 정의
ALLOW_ORIGINS	CORS를 허용할 ORIGIN 리스트
DB_HOST	DB 호스트
DB_PORT	DB 포트
DATABASE	DB 이름
DB_USERNAME	DB 접속 유저네임
DB_PASSWORD	DB 패스워드
SLACK_TOKEN	슬랙 토큰
BOT_NAME	슬랙봇 이름
ERROR_CHANNEL	슬랙 에러 리포팅 채널
SPECIAL_EMOJI	특별한 의미를 가진 이모지
LIMIT_GIVE_COUNT_OF_SPECIAL_EMOJI	매월 다른 멤버에게 줄 수 있는 SPECIAL_EMOJI 제한 개수
ALLOWED_REACTION_LIST	웹훅 리액션으로 허용된 이모지(reaction)들을 정의합니다.
ALLOWED_EMOJI_TYPES	핸들링할 이모지들을 정의합니다.
RANK_URL	랭킹 웹페이지 URK
DEFAULT_AVATAR_URL	기본 프로필 이미지 URL

🐳 Docker-Compose 실행

.env_sample을 참고하여.env파일을 생성한 뒤 docker-compose up -d 를 실행합니다.
api, web, db 컨테이너가 모두 실행 된 후 http://127.0.0.1:8080 에 접속하여 동작을 확인합니다.
❗️주의: 컨테이너가 뜨고 패키지 설치에 시간이 걸릴수 있어서 애플리케이션 실행까지 몇분이 소요 될 수 있습니다.

docker-comopse 실행 전에 README 하단에 있는 Slack Bot 설정을 먼저 보시고 SlackToken 같은 환경변수를 먼저 주입해주세요!

💡 로컬 실행

pip install -r requirements

root경로(/heymoji) 에 가서 uvicorn으로 서버를 실행시킵니다.
백그라운드로 실행하기 위해서는 &를 마지막에 붙여주세요.

uvicorn app.main:app --port 8080

만약 백그라운드에서 실행되고 있는 프로세스를 제거하고싶은 경우

1. ps aux | grep uvicorn
2. kill -9 {PID} 

잘못된 프로세스 kill을 주의하세요!

📝 API 문서 및 테스트

HOST_URL/docs로 접속하면 Swagger로 만들어진 web 페이지를 확인할 수 있습니다. (FastAPI는 swagger, redoc 지원)

👾 슬랙 맨션 명령어

이름	설명
help	커멘드 관련 help
create_user	user 생성
update_user	user 정보 업데이트
show_user	유저 is_display = True (노출)
hide_user	유저 is_display = False (숨김)
show_best_member	해당월 베스트 멤버 추출

🥳 멤버 등록
이름은 필수 입니다!
@EmojiBot --create_user --name=이름 --avatar_url=이미지URL --department=부서

🛠 멤버 정보 업데이트
업데이트할 정보만 적어주세요!
@EmojiBot --update_user --avatar_url=이미지URL

🎖 이번달 베스트 멤버 리스트 추출
@EmojiBot --show_best_member --year=2022 --month=1

🙈 유저 숨기기
@EmojiBot --hide_user --slack_id=슬랙ID

🙉 유저 보이기
@EmojiBot --show_user --slack_id=슬랙ID

🎖 show_best_member 예시

🚀 Postman 으로 유저 등록 예시

🧟‍♂️ 프로세스 Live 체크 (선택)

shell script로 간단하게 Live 체크를 진행 할 수 있습니다! 크론탭에 1분마다 실행하도록 등록.
로깅도 추가하면 좋습니다.

#! /bin/bash
PYTHON_PATH=/{{ path }}/venv/bin/python
SCRIPT_PATH=/{{ path }}/heymoji/app

checker=`ps aux | grep -v "grep" | grep "{{ 검색할 이름}}" | wc -l`

if [ "$checker" == "0" ]; then
	source '{{ path }}/venv/bin/activate'
	cd $SCRIPT_PATH && `uvicorn main:app --port 8080 &`
fi

🤖 Slack Bot 설정

https://api.slack.com/apps 에 접속하여 create app 버튼을 클릭한 후,
원하는 workspace에 app을 생성해주세요!

Basic Information 탭을 클릭후 하단에서 app의 프로필 이미지를 추가하고 Save 해줍니다.
이건 안해도 되지만 하는게 좋아요. 왜냐하면 멋있거든요😎

Add features and functionality에서 Event Subscriptions을 클릭합니다.

Event를 Enable(활성화) 시킨후 Requst URL을 넣어서 인증을 합니다.

위 화면에서 슬랙토큰을 copy하여 .env 파일에 추가합니다.

로컬에서 테스트 하기 위해 ngrok을 사용하시면 편합니다.실제 prod 환경에서는 Nginx + uvicorn으로 실행하면 되요!
Nginx Config 에서 proxy_pass 만 uvicorn으로 실행한 로컬 서버로 연결해주면 됩니다!

Heymoji는 슬랙 멤버들의 reaction_added, reaction_removed 이벤트와 bot을 호출하는 app_mention 이렇게 3가지 이벤트를 받습니다.

슬랙봇과 DM을 통해 명령어를 실행하기 위해서는 message.im을 선택하고 Message Tab 기능을 on 시켜주셔야 합니다.

마지막으로 app을 workspace에 설치(install)하면 설정한 이벤트가 일어날때마다 slack에서 Heymoji서버로 웹훅 api를 호출합니다.