• 이미지 출처: anchor.dev

HTTPS 개발 서버 설정하는 방법

이 문서에서는 HTTPS 개발 서버를 설정하는 세 가지 방법을 소개한다.

1. OpenSSL을 이용한 커스텀 서버 설정
2. mkcert를 이용한 커스텀 서버 설정
3. Next.js의 자체 HTTPS 지원 기능 (-experimental-https 플래그)

---

개요

• HTTPS 개발 서버를 설정하는 방법에는 여러 가지가 있으며, 각 방법은 사용 목적에 따라 적합성이 다르다.
  • 커스텀 서버 설정(OpenSSL, mkcert) 호스트명, 포트, 인증서 관리 등 더 세부적인 컨트롤이 필요한 경우 커스텀 서버 설정이 적합하다.
    
  • Next.js의 자체 HTTPS 지원 기능 복잡한 설정 없이 빠르고 간단하게 HTTPS 환경을 설정하고자 한다면 Next.js의 --experimental-https 플래그를 사용하는 것이 가장 효율적이다.
    

---

사용 가이드

자신의 필요에 따라 다음 방법 중 적합한 것을 선택하여 필요한 부분만 참고하길 바란다.

1. 더 높은 유연성과 제어를 원한다면?

   → OpenSSL 또는 mkcert를 사용하여 커스텀 서버를 설정한다.

2. 빠르고 간단한 설정이 필요하다면?

   → Next.js의 --experimental-https 플래그를 사용한다.

본문을 이해하기 위한 간단한 사전 지식

1. SSL

SSL(Secure Sockets Layer)은 클라이언트와 서버 간의 데이터를 암호화하여 안전하게 보호하는 기술이다. 그러나 SSL은 오래된 기술로, 몇 가지 보안 취약점이 발견되면서 더 이상 권장되지 않는다.

---

2. TLS

TLS(Transport Layer Security)는 SSL의 취약점을 보완하여 개선된 업그레이드 버전이다. TLS는 효율적인 인증 및 암호화를 제공하며, 안전한 통신 채널을 유지하는 데 사용된다. 현재 대부분의 HTTPS 통신은 TLS를 기반으로 한다.

---

3. HTTPS

HTTPS(HTTP + SSL/TLS)는 SSL 또는 TLS를 사용하여 웹 브라우저와 서버 간의 데이터를 안전하게 전송하는 통신 프로토콜이다. 이를 통해 민감한 정보를 보호하며, HTTP에 비해 보안성이 훨씬 높다. HTTPS를 사용하는 웹사이트는 주소가 http:// 대신 https://로 시작한다.

---

4. Homebrew

Homebrew는 Mac에서 소프트웨어와 패키지를 설치하고 관리할 수 있는 패키지 관리자이다. 터미널에서 간단한 명령어로 다양한 프로그램을 설치, 업데이트, 삭제할 수 있다.

• 사용 예:

  brew install [패키지이름]

---

5. Chocolatey

Chocolatey는 Windows에서 소프트웨어와 패키지를 설치하고 관리할 수 있는 패키지 관리자이다. Windows 환경에서도 명령어로 프로그램 설치와 관리를 간편하게 할 수 있다.

• 사용 예:

  choco install [패키지이름]

---

HTTPS 개발 서버 설정하는 방법

Next.js로 HTTPS 개발 서버를 설정하는 방법에는 여러 방법이 있다. 그 중 대표적인 몇 가지 방법을 알아보자.

1. OpenSSL을 이용한 Custom Server 설정

OpenSSL은 SSL/TLS 프로토콜과 다양한 암호화 기능을 지원하는 오픈 소스 암호화 라이브러리 및 툴이다.

1.1 Mac 환경 OpenSSL 설치

1. OpenSSL 설치
   Mac에는 OpenSSL이 기본적으로 설치되어 있다. 만약 설치가 필요하다면, 아래 명령어를 사용해 설치할 수 있다.

   brew install openssl

2. 인증서 생성
   아래 명령어를 실행해 인증서를 생성한다.

   openssl req -x509 -nodes -newkey rsa:2048 -keyout localhost.key -out localhost.crt -days 365 -subj "/CN=localhost"

   • localhost.key: 개인 키 파일이다.
   • localhost.crt: 인증서 파일이다.
   • days 365: 인증서를 약 1년 동안 유효하게 설정한다.

3. 생성된 파일 확인
   명령어를 실행한 디렉토리에 localhost.key와 localhost.crt 파일이 생성된다. 이 파일들을 프로젝트 루트 디렉토리로 복사해야 한다.

---

1.2 Windows 환경 OpenSSL 설치

1. OpenSSL 설치
   Windows는 OpenSSL를 수동으로 설치해야 한다.
   slproweb.com에 접속하여 사양에 맞는 버전을 다운로드하여 설치한다.
   • Windows 사양 확인 방법
     • 윈도우 → 설정 → 시스템 → 장치 사양과 Windows 사양 확인
2. 환경 변수 추가
   • cmd 창에서 sysdm.cpl 입력 후 나타나는 시스템 속성 창의 고급 탭 → 환경 변수 클릭
   • 사용자 변수의 Path선택 후 편집 클릭
   • 새로 만들기 클릭 후 C:\Program Files\OpenSSL-Win64\bin 입력 후 확인
     • 해당 경로는 설치 과정에서 설정한 경로를 입력 해준 후 경로 끝에 \bin을 붙여야함.
   • cmd창 재시작
3. 이후 인증서 생성 및 생성된 파일 확인은 Mac 환경과 동일하다.

Windows OpenSSL 설치 과정 참고 문헌: window openssl 설치하기

---

1.3 인증서 파일 보호

인증서와 개인 키 파일이 원격 저장소(GitHub, GitLab 등)에 업로드되지 않도록 .gitignore 파일에 등록해야 한다.

• .gitignore에 다음 항목 추가

  # 인증서 및 개인 키 파일 제외
  localhost.crt
  localhost.key

---

1.4 커스텀 HTTPS 서버 설정

Node.js를 활용하여 커스텀 HTTPS 서버를 설정해야 한다. 이를 통해 Next.js 애플리케이션을 HTTPS로 실행할 수 있다.

1. server.js 파일 생성
   프로젝트 루트 디렉토리에 server.js 파일을 생성하고, 아래 코드를 추가한다.

    
    import fs from 'fs'
    import https from 'https'
    import next from 'next'
    
    const port = 3000
    const hostname = 'localhost'
    
    const dev = process.env.NODE_ENV !== 'production'
    const app = next({ dev })
    const handle = app.getRequestHandler()
    
    const httpsOptions = {
      key: fs.readFileSync('./localhost.key'), // 생성된 개인 키 파일
      cert: fs.readFileSync('./localhost.crt'), // 생성된 인증서 파일
    }
    
    app.prepare().then(() => {
      https
        .createServer(httpsOptions, (req, res) => {
          handle(req, res)
        })
        .listen(port, hostname, (err) => {
          if (err) throw err
          console.log(`> Ready on https://${hostname}:${port}`)
        })
    })

2. 포트 및 호스트명 설정
   port, hostname을 수정하여 포트와 호스트명을 원하는대로 설정할 수 있다.

3. server.js에서 import 문법 사용 시 발생할 수 있는 에러

   • 문제 server.js 파일에서 ES 모듈 방식의 import를 사용했지만, Node.js가 CommonJS 환경으로 실행되어 아래와 같은 오류가 발생할 수 있다.

     SyntaxError: Cannot use import statement outside a module

   • 원인 Node.js는 기본적으로 CommonJS 환경에서 실행된다. ES 모듈을 사용하려면 추가 설정이 필요하다.
     
   • 해결 방법

     1. ES 모듈 활성화

        package.json에 "type": "module"을 추가하여 ES 모듈 환경으로 전환한다.

        {
          "name": "your-project-name",
          "version": "1.0.0",
          "type": "module",
          "scripts": {
            "dev": "next dev",
            "dev:https": "node server.js"
          }
        }

---

1.5 package.json에 스크립트 추가

HTTPS 서버를 실행하기 위한 명령어를 package.json에 추가한다.

1. 스크립트 추가
   • package.json 파일을 열고 다음과 같이 스크립트를 추가한다.

     "scripts": {
       "dev:https": "node server.js" // HTTPS 서버 실행 스크립트
     }

2. HTTPS 개발 서버 실행
   • 아래 명령어를 사용하여 HTTPS 개발 서버를 실행한다.

     npm run dev:https

3. HTTPS 개발 서버 접속
   • 브라우저에서 다음 URL 형식으로 접속한다. 예: https://localhost:3000

     https://<설정한 호스트명>:<설정한 포트>

4. 기존 HTTP 개발 서버의 캐시 초기화
   • 이전에 npm run dev 명령으로 개발 서버를 실행한 적이 있다면, .next 디렉토리 캐시로 인해 충돌이 발생할 수 있다. 이를 방지하려면 프로젝트 루트 디렉토리에서 다음 명령어를 실행하여 .next 디렉토리를 삭제한다.

     rm -rf .next

---

2. mkcert를 이용한 Custom Server 설정

mkcert는 로컬 개발 환경에서 신뢰할 수 있는 SSL/TLS 인증서를 간편하게 생성하기 위한 도구이다. 복잡한 설정 없이, 개발 환경에서 HTTPS를 설정할 수 있다. 이 도구는 시스템 신뢰 저장소에 인증서를 설치하여 브라우저에서 신뢰할 수 있는 상태로 만들어준다.

• GitHub - FiloSottile/mkcert

---

2.1 Mac 환경 mkcert 설치

1. mkcert 설치

   brew install mkcert

---

2.2 Windows 환경 mkcert 설치

1. mkcert 설치

   choco install mkcert

---

2.3 mkcert 로컬 CA 설치

• 아래 명령어를 통하여 현재 사용하는 컴퓨터에 자체 인증 기관(CA, Certificate Authority)을 생성하고 시스템 신뢰 저장소에 추가한다. 브라우저가 mkcert의 인증서를 신뢰하도록 설정되며, 개발용 인증서를 생성할 준비가 완료된다.

  mkcert -install

---

2.4 인증서 생성

• localhost와 개발에서 사용할 도메인에 대한 인증서를 생성한다. 이 작업은 프로젝트 루트 디렉토리에서 진행한다.

  mkcert localhost

  • 생성되는 파일
    • localhost-key.pem: 개인 키 파일.
    • localhost.pem: 인증서 파일.

---

2.5 인증서 파일 보호

인증서와 개인 키 파일이 원격 저장소(GitHub, GitLab 등)에 업로드되지 않도록 .gitignore 파일에 등록해야 한다.

• .gitignore에 다음 항목 추가

  # 인증서 및 개인 키 파일 제외
  localhost.pem
  localhost-key.pem

---

2.6 커스텀 HTTPS 서버 설정

mkcert로 생성한 인증서를 이용하여 HTTPS 서버를 설정한다. OpenSSL을 이용한 서버 설정 과정(1.4 목차)과 대부분 동일하며, 아래 부분만 mkcert로 생성한 인증서 파일 이름에 맞게 변경하면 된다.

1. httpsOptions 변수에 인증서 파일 경로를 다음과 같이 설정한다.

   const httpsOptions = {
     key: fs.readFileSync('./localhost-key.pem'), // mkcert로 생성한 개인 키 파일
     cert: fs.readFileSync('./localhost.pem'),   // mkcert로 생성한 인증서 파일
   };

2. 나머지 설정(포트, 호스트네임, server.js 파일 구성 등)은 1.4 커스텀 HTTPS 서버 설정 항목을 참고하여 동일하게 적용한다.

---

2.7 package.json에 스크립트 추가

• 1.5 package.json에 스크립트 추가 항목을 참고하여 동일하게 적용한다.

---

3. Next.js의 --experimental-https 기능을 활용한 HTTPS 개발 서버 설정

Next.js는 버전 13.5.1부터 --experimental-https 플래그를 통해 개발 서버에서 HTTPS를 지원하는 기능을 제공한다. 이 기능을 활용하면 로컬 개발 환경에서 간단하게 HTTPS 서버를 실행할 수 있다.

• vercel.com - Next.js on localhost through HTTPS

3.1 요구 사항

• Next.js 버전이 13.5.1 이상이어야 한다.

---

3.2 사용 방법

1. HTTPS 개발 서버 실행
   • 아래 명령어를 사용하여 HTTPS 개발 서버를 실행할 수 있다.

     next dev --experimental-https

   • 실행 후 브라우저에서 https://localhost:3000으로 접속하면 HTTPS 서버가 동작한다.
2. 사용자 지정 인증서 설정
   • 기본적으로 Next.js는 localhost에 대한 자체 서명된 SSL 인증서를 생성한다.
   • 사용자 지정 인증서를 사용하려면 다음 플래그를 추가하여 실행한다.

     next dev --experimental-https-key <key-file-path> --experimental-https-cert <cert-file-path>

---

3.3 주요 기능

1. 자동 인증서 생성
   • -experimental-https 플래그는 mkcert와 같은 도구를 사용하여 localhost용 자체 서명된 SSL 인증서를 자동으로 생성한다.
   • 생성된 인증서는 프로젝트 루트 디렉토리의 certificates 폴더에 저장된다.
     • localhost-key.pem: 개인 키 파일.
     • localhost.pem: 인증서 파일.
2. 로컬 개발 환경 최적화
   • 이 플래그를 사용하면 HTTPS 설정이 자동화되며, 추가적인 인증서 설정 없이 로컬 개발 환경에서 HTTPS를 테스트할 수 있다.
3. 네트워크 URL 제한
   • 이 기능은 기본적으로 localhost에서만 작동하도록 설계되었다.
   • 네트워크 URL(예: 192.168.0.19:3000)을 사용할 경우, 브라우저에서 인증서를 신뢰하지 않을 수 있다.

• How can I use Next.js over HTTPS instead of HTTP? · vercel next.js · Discussion #10935

---

참고문헌

• SSL과 TLS 비교 - 통신 프로토콜 간의 차이점 - AWS
• Win32/Win64 OpenSSL Installer for Windows - Shining Light Productions
• window openssl 설치하기
• GitHub - FiloSottile/mkcert: A simple zero-config tool to make locally trusted development certificates with any names you'd like.
• How can I run Next.js on localhost through HTTPS?
• How can I use Next.js over HTTPS instead of HTTP? · vercel next.js · Discussion #10935