"Gunicorn"이란?
- Gunicorn(Green Unicorn)은 Python WSGI(Web Server Gateway Interface) 애플리케이션을 UNIX 환경에서 서비스하기 위한 경량의 HTTP 서버이다.
- Django, Flask, FastAPI 등 WSGI 표준을 따르는 프레임워크와 호환되며, 프로덕션 환경에서 자주 사용된다.
- 기본적으로 내가 사용하는 Django는 runserver로 개발용 서버는 가능하지만 실제 서비스용으로는 안정성과 성능이 부족하기 때문에
WSGI(Web Server Gateway Interface)를 지원하는 Gunicorn이 등장했다.- "WSGI" = "Python 웹앱과 웹서버를 연결해주는 표준 규약"
Gunicorn의 역할
- Django를 실행시킴
- 요청을 받아 Django 로직 처리
- 응답을 생성
위 스크린샷은 systemd를 이용해 Gunicorn을 데몬(백그라운드 서비스)으로 실행하기 위한 서비스 파일이다.
주로/etc/systemd/system/gunicorn.service같은 경로에 저장되어 사용된다.
[Unit] 섹션
- 서비스의 메타 정보를 담고 있다.
Description=gunicorn daemon for TeamProject_BE-> 이 서비스의 설명, "systemctl status" 명렁어 등에 표시됨
After=network.target-> 이 서비스는 네트워크가 활성화된 이후에 실행되어야 함을 의미함
[Service] 섹션
- 서비스가 어떻게 동작할지에 대한 핵심 설정.
User=ubuntu-> 이 서비스를 실행할 사용자, 여기서 "ubuntu"는 EC2 인스턴스의 기본 사용자
Group=www-data-> 이 서비스가 속할 그룹, 웹 서버(Nginx)는 보통 www-data 그룹을 사용한다.
WorkingDirectory=/home/ubuntu/TeamProject_BE-> Gunicorn이 실행되는 디렉토리 (Django 프로젝트 루트)
[ExecStart]
- Gunicorn을 실제로 실행하는 명령어.
ExecStart=/home/ubuntu/.pyenv/versions/potato/bin/gunicorn-> pyenv로 설치한 가상환경 potato 안의 gunicorn 실행 경로
--access-logfile, --error-logfile-> 각각 access, error 로그의 저장 위치
--log-level info-> 로그 레벨 설정 (debug, info, warning 등)
--worker 3-> 워커 프로세스를 3개 실행 (병렬 처리 향상)
--bind unix:/srv/gunicorn/gunicorn.sock-> Unix 도메인 소켓으로 바인딩. 보통 Nginx와 연결할 때 사용
💡추가 팁: 왜 소켓을 /srv에 만들까?
/srv는 일반적으로 "서비스 데이터" 저장용 디렉토리
그래서 gunicorn.sock 파일을 /tmp 같은 임시 경로 대신 /srv/gunicorn/에 둠
이건 관습적인 거고, 사실 /run/이나 /var/run/ 같은 데 둬도 돼
중요한 건 Nginx와 Gunicorn이 같은 경로를 공유해야 한다는 것!config.wsgi:application-> Django의 WSGI 진입점. 보통 프로젝트이름/wsgi.py 내 application 객체를 가리킴
EnvironmentFile=/home/ubuntu/TeamProject_BE/envs/prod.env-> Gunicorn 실행 시 불러올 환경변수 파일 (.env 포맷, SECRET_KEY, DATABASE_URL등)
Environment="DJANGO_SETTINGS_MODULE=config.settings.prod"-> Django가 사용할 세팅 모듈을 지정. 예) config/settings/prod.py
StandardOutput=journal, StandardError=journal-> stdout/stderr 출력을 systemd journal 로그로 보냄 (journalctl로 조회 가능)
[Install] 섹션
- 서비스가 어떤 타겟에 포함될지 설정.
WantedBy=multi-user.target-> 다중 사용자 모드(멀티유저 환경)에서 자동 실행되도록 설정. (sudo systemctl enable gunicorn 했을 때 부팅 시 자동 실행)
✅ 정리
- 위의 파일은 Gunicorn을 systemd 서비스로 등록하고, 서버 부팅 시 자동으로 Django 백엔드를 실행할 수 있게 구성한 설정이다.
실제 적용 방법은 다음과 같다.
1. sudo cp gunicorn.service /etc/systemd/system/ -> 현재 디렉토리에 있는 gunicorn.service 파일을 시스템 서비스 디렉토리인 /etc/systemd/system/ 으로 관리자 권한으로 복사하라는 명령어
2. sudo systemctl daemon-reload -> 시스템 서비스 캐시 새로고침
3. sudo systemctl enable gunicorn -> 부팅 시 자동 실행 설정
4. sudo systemctl start gunicorn -> 서비스 시작
5. sudo systemctl status gunicorn -> 서비스 상태 확인
🧐 그렇다면 여기서 왜 systemd 서비스로 등록 해야 하는가?
- 리눅스 시스템에서
systemd는 부팅 시부터 다양한 백그라운드 작업(서비스, 데몬)을 관리하는 표준 서비스 매니저 - 운영체제 수준에서 애플리케이션을 안정적으로 관리하기 위함.
- 시작/중지/재시작 제어 가능
-> 서비스를 systemd에 등록하면 다음 명령어로 손쉽게 제어할 수 있음.sudo systemctl start gunicorn # 서비스 시작 sudo systemctl stop gunicorn # 서비스 중지 sudo systemctl restart gunicorn # 서비스 재시작
- 서버 부팅 시 자동 실행
->sudo systemctl enable gunicorn하면 서버가 재부팅되어도 자동으로 Gunicorn이 실행됨.
- 비정상 종료 시 자동 재시작
-> .service 파일에 Restart-always 같은 옵션을 주면, 앱이 꺼져도 systemd가 다시 실행 시켜줌.
- 로그 관리
->journalctl -u gunicorn명령어로 서비스 로그를 확인할 수 있어 디버깅이 편해진다.
🧐 왜 /etc/systemd/system/에 복사하는가?
sudo cp gunicorn.service /etc/systemd/system/명령어로 이렇게/etc/systemd/system/경로에 복사 하는 이유는/etc/systemd/system/가 사용자가 직접 작성한 서비스 파일을 저장하는 공식적인 위치이며, 여기에 복사해야 systemd가 그 파일을 하나의 서비스로 systemctl로 인식하고 실행/제어가 가능하기 때문이다.
