다음을 통해 공유

웹 정적 파일 배포

  • 아티클

참고 항목

기본, 표준 및 엔터프라이즈 계획은 2025년 3월 중순부터 사용되지 않으며 3년의 은퇴 기간이 있습니다. Azure Container Apps로 전환하는 것이 좋습니다. 자세한 내용은 Azure Spring Apps 사용 중지 공지 사항을 참조하세요.

표준 소비 및 전용 계획은 2024년 9월 30일부터 사용되지 않으며 6개월 후에 완전히 종료됩니다. Azure Container Apps로 전환하는 것이 좋습니다. 자세한 내용은 Azure Spring Apps 표준 사용량 및 전용 계획을 Azure Container Apps로 마이그레이션을 참조 하세요.

이 문서는 기본/표준 ✅ 엔터프라이즈에 ❎ 적용됩니다.

이 문서에서는 Tanzu 웹 서버 빌드팩을 사용하여 정적 파일을 Azure Spring Apps 엔터프라이즈 플랜 인스턴스에 배포하는 방법을 보여 줍니다. 이 방법은 원하는 JavaScript 프레임워크를 사용하여 빌드된 HTML, CSS 또는 프런트 엔드 애플리케이션과 같은 정적 파일 보관에만 사용되는 애플리케이션이 있는 경우 유용합니다. 자동으로 구성된 웹 서버(HTTPD 및 NGINX)를 사용하면 이러한 애플리케이션을 직접 배포하여 이러한 자산을 제공할 수 있습니다.

필수 조건

정적 파일 배포

참고 항목

이 문서에서는 웹 정적 파일 배포와 관련된 배포 구성 및 문제 해결을 설명하는 데 중점을 둡니다. Azure Springs Apps 엔터프라이즈 플랜에 대한 일반 빌드 및 배포 시나리오를 이해하려면 Tanzu Build Service 사용 및 다국어 앱을 배포하는 방법의 주문형 빌드 서비스 섹션을 참조하세요.

다음과 같은 방법으로 NGINX 또는 HTTPD 웹 서버를 사용하여 Azure Spring Apps에 정적 파일을 배포할 수 있습니다.

  • 정적 파일을 직접 배포할 수 있습니다. Azure Spring Apps는 정적 파일을 제공하도록 지정된 웹 서버를 자동으로 구성합니다.
  • 선택한 JavaScript 프레임워크에서 프런트 엔드 애플리케이션을 만든 다음, 소스 코드에서 동적 프런트 엔드 애플리케이션을 배포할 수 있습니다. Azure Spring Apps는 정적 콘텐츠로 앱을 빌드하고 구성된 웹 서버를 사용하여 정적 파일을 제공합니다.

웹 서버를 사용자 지정하는 서버 구성 파일을 만들 수도 있습니다.

배포 예제

이 섹션의 Azure CLI 예제에서는 두 가지 컨테이너 레지스트리 시나리오에 대한 정적 파일 빌드 및 배포를 보여 줍니다.

  • Azure Spring Apps 관리 컨테이너 레지스트리
  • 사용자 관리 컨테이너 레지스트리

정적 파일 직접 빌드 및 배포

이 예제에서는 자동 생성된 기본 서버 구성 파일을 사용하여 정적 파일을 직접 배포합니다.

다음 명령은 정적 파일을 배포합니다.

az spring app deploy
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --name <app-name> \
    --source-path <path-to-source-code> \
    --build-env BP_WEB_SERVER=nginx

환경 변수 사용에 대한 자세한 내용은 자동 생성된 서버 구성 파일 구성 섹션을 참조하세요.

프런트 엔드 애플리케이션을 정적 콘텐츠로 빌드 및 배포

이 예제에서는 소스 코드에서 동적 프런트 엔드 애플리케이션을 배포합니다.

다음 명령은 애플리케이션을 배포합니다.

az spring app deploy \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --name <app-name> \
    --source-path <path-to-source-code> \
    --build-env BP_WEB_SERVER=nginx BP_NODE_RUN_SCRIPTS=build BP_WEB_SERVER_ROOT=build

사용자 지정된 구성 파일을 사용하여 정적 파일 빌드 및 배포

이 예제에서는 사용자 지정된 서버 구성 파일을 사용하여 정적 파일을 배포합니다.

다음 명령은 애플리케이션을 배포합니다.

az spring app deploy \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-instance-name> \
    --name <app-name> \
    --source-path <path-to-source-code>

자세한 내용은 이 문서의 사용자 지정된 서버 구성 파일 사용 섹션을 참조하세요.

샘플 코드

참고 항목

샘플 코드는 Paketo 오픈 소스 커뮤니티에서 관리합니다.

Paketo 빌드팩 샘플은 다음 사용 사례를 포함하여 여러 다양한 애플리케이션 형식에 대한 일반적인 사용 사례를 보여 줍니다.

  • BP_WEB_SERVER를 사용하여 HTTPD 또는 NGINX를 선택하는 기본 서버 구성 파일과 함께 정적 파일을 제공합니다.
  • 노드 패키지 관리자를 사용하여 웹 서버가 제공할 수 있는 정적 파일로 React 앱을 빌드합니다. 다음 단계를 사용합니다.
    1. 프로덕션에 바로 사용할 수 있는 정적 자산을 빌드하는 package.json 파일의 scripts 속성 아래에 스크립트를 정의합니다. React의 경우 build입니다.
    2. 빌드 스크립트 실행 후 정적 자산이 저장되는 위치를 찾습니다. React의 경우 정적 자산은 기본적으로 ./build에 저장됩니다.
    3. BP_NODE_RUN_SCRIPTS를 빌드 스크립트의 이름으로 설정합니다.
    4. BP_WEB_SERVER_ROOT를 빌드 출력 디렉터리로 설정합니다.
  • HTTPD 또는 NGINX를 사용하여 자체 서버 구성 파일로 정적 파일을 제공합니다.

자동 생성된 서버 구성 파일 구성

환경 변수를 사용하여 자동 생성된 서버 구성 파일을 수정할 수 있습니다. 다음 표는 지원되는 환경 변수를 보여 줍니다.

환경 변수 지원되는 값 설명
BP_WEB_SERVER nginx 또는 httpd Nginx의 경우 nginx로, 또는 Apache HTTP 서버의 경우 httpd로 웹 서버 형식을 지정합니다. 자동 생성된 서버 구성 파일을 사용할 때 필요합니다.
BP_WEB_SERVER_ROOT 절대 파일 경로 또는 /workspace에 상대적인 파일 경로입니다. 정적 파일의 루트 디렉터리를 설정합니다. 기본값은 public입니다.
BP_WEB_SERVER_ENABLE_PUSH_STATE true 또는 false 애플리케이션에 대한 푸시 상태 라우팅을 사용하도록 설정합니다. 요청된 경로에 관계없이 index.html은 항상 제공됩니다. 단일 페이지 웹 애플리케이션에 유용합니다.
BP_WEB_SERVER_FORCE_HTTPS true 또는 false HTTPS 프로토콜을 사용하도록 모든 요청을 리디렉션하여 서버 연결에 HTTPS를 적용합니다.

다음 환경 변수는 지원되지 않습니다.

  • BP_LIVE_RELOAD_ENABLED
  • BP_NGINX_VERSION
  • BP_HTTPD_VERSION

사용자 지정된 서버 구성 파일 사용

사용자 지정된 서버 구성 파일을 사용하여 웹 서버를 구성할 수 있습니다. 다음 표에서는 구성 파일 경로를 보여 줍니다.

웹 서버 기본 구성 파일 경로 서버 구성 파일 경로를 사용자 지정하는 방법
nginx 소스 코드의 루트 경로 아래에 있는 nginx.conf. 환경 변수 BP_NGINX_CONF_LOCATION을 사용하여 구성 파일 이름을 지정합니다. 소스 코드의 루트 경로 아래에 파일을 배치합니다.
httpd 소스 코드의 루트 경로 아래에 있는 httpd.conf 지원되지 않습니다.

구성 파일은 다음 표에 설명된 제한 사항을 준수해야 합니다.

구성 설명 Nginx 구성 HTTP 구성
수신 대기 포트 웹 서버는 포트 8080에서 수신 대기해야 합니다. 이 서비스는 TCP의 포트에서 준비 상태와 활성 여부를 확인합니다. 구성 파일에서 템플릿 변수 PORT를 사용해야 합니다. 웹 서버가 시작될 때 적절한 포트 번호가 삽입됩니다. listen {{PORT}} Listen "${PORT}"
로그 경로 콘솔에 대한 구성 로그 경로입니다. access_log /dev/stdout, error_log stderr ErrorLog /proc/self/fd/2
쓰기 권한이 있는 파일 경로 웹 서버에 /tmp 디렉터리에 대한 쓰기 권한이 부여됩니다. 전체 경로를 구성하려면 /tmp 디렉터리 아래에 쓰기 권한이 필요합니다. 예: client_body_temp_path /tmp/client_body_temp
클라이언트 요청의 최대 허용 본문 크기 웹 서버가 게이트웨이 뒤에 있습니다. 클라이언트 요청의 최대 허용 본문 크기는 게이트웨이에 500m로 설정되며, 웹 서버의 값은 500m 미만이어야 합니다. client_max_body_size는 500m 미만이어야 합니다. LimitRequestBody는 500m 미만이어야 합니다.

빌드팩 바인딩

Azure Spring Apps 엔터프라이즈 플랜에 정적 파일을 배포하면 Dynatrace 빌드팩 바인딩이 지원됩니다. htpasswd 빌드팩 바인딩은 지원되지 않습니다.

자세한 내용은 APM 통합 및 CA 인증서 구성 방법을 참조하세요.

일반적인 빌드 및 배포 오류

Azure Spring Apps 엔터프라이즈 인스턴스에 정적 파일을 배포하면 다음과 같은 일반적인 빌드 오류가 발생할 수 있습니다.

  • ERROR: No buildpack groups passed detection.
  • ERROR: Please check that you're running against the correct path.
  • ERROR: failed to detect: no buildpacks participating

이러한 오류의 근본 원인은 웹 서버 형식이 지정되지 않았기 때문입니다. 이러한 오류를 해결하려면 환경 변수 BP_WEB_SERVER를 nginx 또는 httpd로 설정합니다.

다음 표에서는 정적 파일을 Azure Spring Apps 엔터프라이즈에 배포할 때 발생하는 일반적인 배포 오류에 대해 설명합니다.

오류 메시지 근본 원인 솔루션
112404: Exit code 0: purposely stopped, please refer to https://aka.ms/exitcode 웹 서버를 시작하지 못했습니다. 서버 구성 파일의 유효성을 검사하여 구성 오류가 있는지 확인합니다. 그런 다음, 구성 파일이 사용자 지정된 서버 구성 파일 사용 섹션에 설명된 제한 사항을 준수하는지 확인합니다.
mkdir() "/var/client_body_temp" failed (13: Permission denied) 웹 서버에 지정된 경로에 대한 쓰기 권한이 없습니다. /tmp 디렉터리 아래에 경로를 구성합니다. 예: /tmp/client_body_temp.

다음 단계