1. 설치/폴더 구성/운영 명령어

TechNote · NGINX · 01

설치·폴더 구성·운영 명령어: “운영자가 매일 쓰는 것”만 정리

설치 이후 운영자가 자주 만지는 폴더 구조와 기본 명령어만 골라서, 실무 기준으로 정리해 드립니다.

대상: 운영자 포커스: 설치/운영 키워드: 폴더 구조

이 글은 이런 분에게
① NGINX를 “일단 띄웠는데” 어디를 만져야 할지 헷갈리는 경우
② 설정이 많아질수록 파일이 혼란스러워지기 쉬운 상황이 되는 것을 미리 막고 싶은 경우
③ 장애/변경 때 검증 → 반영 → 롤백 루틴을 만들고 싶은 경우

1) 설치(Ubuntu/Debian)

# 패키지 설치
sudo apt update
sudo apt install -y nginx

# 부팅 시 자동 시작
sudo systemctl enable --now nginx

# 상태 확인
systemctl status nginx --no-pager

RHEL/CentOS 계열(예: Rocky/Alma 등)에서 설치할 때는, 배포판 기본 저장소 대신 nginx.org 레포를 붙여서 설치하는 경우가 많습니다(안정판(stable) / 메인라인(mainline) 선택 가능).

예시 흐름(레포 등록 → 설치)

# 1) 레포 등록(예시)
sudo tee /etc/yum.repos.d/nginx.repo <<'EOF'
[nginx-stable]
name=nginx stable repo
baseurl=http://nginx.org/packages/<OS>/$releasever/$basearch/
gpgcheck=1
enabled=1
gpgkey=https://nginx.org/keys/nginx_signing.key
EOF

# 2) 설치
sudo yum install -y nginx
sudo systemctl enable --now nginx

※ <OS> 자리에 배포판 경로(예: rhel, centos)를 맞춰야 하고, 환경에 따라 dnf/yum 명령이 달라질 수 있습니다.

폐쇄망(인터넷 차단)은 보통 아래 흐름으로 갑니다. 핵심은 패키지 + 의존성을 외부에서 확보하고, 내부에서 검증 후 설치하는 것입니다.

폐쇄망(인터넷 차단)에서 NGINX 설치 흐름(개념도)

폐쇄망 설치 팁

• 단발성이라면 로컬 설치(rpm/deb)로도 가능하지만, 장기 운영이라면 내부 로컬 레포(미러)를 만들어 두는 편이 훨씬 편합니다.
• 반입 시에는 가능하면 해시(sha256)나 서명(gpg)으로 무결성 검증을 해두시는 것을 권장드립니다.

2) 폴더 구조: “여기부터 정리하면 미래가 편해진다”

/etc/nginx 폴더 구조(개념도)

배포판 기본 구조(대표 예시):

• /etc/nginx/nginx.conf : 전역(http 블록 포함) + include
• /etc/nginx/sites-available/ : 사이트(가상호스트) 설정 파일 보관
• /etc/nginx/sites-enabled/ : 활성화된 설정(보통 symlink)
• /etc/nginx/conf.d/ : 공통 조각(로그 포맷, 맵, 공통 헤더 등)
• /var/log/nginx/ : access.log / error.log

/etc/nginx/nginx.conf전역 설정 + include 로 조각 합침/etc/nginx/conf.d/*.conf공통 조각(로그 포맷, 맵, 헤더)/etc/nginx/sites-enabled/*활성 사이트(보통 symlink)/etc/nginx/sites-available/*.conf사이트 원본(여기를 수정)

3) 운영 명령어 10개(진짜 실무에서 쓰는 것)

# 1) 설정 문법 검사(반드시 먼저)
sudo nginx -t

# 2) 리로드(무중단에 가까운 반영)
sudo systemctl reload nginx

# 3) 재시작(최후의 수단)
sudo systemctl restart nginx

# 4) 전체 설정 덤프(Include 포함해서 한 번에 보기)
sudo nginx -T | less

# 5) 빌드 옵션/모듈 확인
nginx -V 2>&1 | tr ' ' '\n' | sed -n '1,120p'

# 6) 최근 에러로그 확인
sudo tail -n 200 /var/log/nginx/error.log

# 7) 접근로그 실시간 보기
sudo tail -f /var/log/nginx/access.log

# 8) 포트 리슨 확인
sudo ss -lntp | grep nginx

# 9) 설정 파일 어디서 읽는지 확인(패키지마다 다를 수 있음)
ps aux | grep '[n]ginx'

# 10) 특정 호스트로 실제 요청 테스트
curl -i http://127.0.0.1/

4) 운영자용 “파일 분리 템플릿”(추천)

아래처럼 쪼개면, 나중에 서비스가 늘어도 유지보수가 무너지지 않습니다.

# /etc/nginx/nginx.conf (요지는 include 전략)
http {
  include       /etc/nginx/mime.types;
  default_type  application/octet-stream;

  # 공통(로그포맷/맵/헤더)
  include /etc/nginx/conf.d/10-log-format.conf;
  include /etc/nginx/conf.d/20-common-headers.conf;
  include /etc/nginx/conf.d/30-realip.conf;

  # 사이트(서비스)들
  include /etc/nginx/sites-enabled/*;
}

5) 자주 터지는 포인트(짧게 예방)

• 변경 후 바로 reload 하지 말고, 무조건 nginx -t 먼저
• 리버스프록시에서 원격 IP가 다 NGINX IP로 찍히면 realip 설정을 의심
• 경로(/api 같은 subpath) 프록시에서 슬래시(/) 하나로 라우팅이 망가지는 케이스가 흔함(2편에서 정리)
• WS(WebSocket) 안 되면 Upgrade 헤더/HTTP 버전(1.1) 확인

---

다음 글: TechNote/NGINX (2) — 옵션별 설정 “실무 세트(proxy_pass/헤더/realip/로그/WS/RateLimit/보안헤더)”

참고 자료(설치/패키징)

• 공식 패키지(nginx.org) 설치 가이드
• NGINX Open Source 설치(공식 가이드)
• [참고 글] NGINX 설치(인터넷/폐쇄망)(soonmin.tistory.com)