Laravel 배포

Deployment

배포

• https://laravel.com/docs/11.x/deployment

1 소개

Laravel 애플리케이션을 프로덕션에 배포할 준비가 되었을 때, 애플리케이션이 가능한 한 효율적으로 실행되도록 하기 위해 할 수 있는 중요한 작업들이 있습니다. 이 문서에서는 Laravel 애플리케이션이 올바르게 배포되었는지 확인하기 위한 몇 가지 훌륭한 시작점을 다룰 것입니다.

2 서버 요구사항

Laravel 프레임워크는 몇 가지 시스템 요구사항이 있습니다. 웹서버가 다음 최소 PHP 버전 및 확장을 갖추고 있는지 확인해야 합니다:

• PHP >= 8.2
• Ctype PHP 확장
• cURL PHP 확장
• DOM PHP 확장
• Fileinfo PHP 확장
• Filter PHP 확장
• Hash PHP 확장
• Mbstring PHP 확장
• OpenSSL PHP 확장
• PCRE PHP 확장
• PDO PHP 확장
• Session PHP 확장
• Tokenizer PHP 확장
• XML PHP 확장

3 서버 설정

3.1 Nginx

다음은 Nginx를 실행 중인 서버에 애플리케이션을 배포할 때 사용할 수 있는 기본 설정 파일입니다. 서버의 설정에 따라 이 파일을 커스터마이징해야 할 가능성이 높습니다. 서버 관리를 지원받고 싶다면 Laravel Forge와 같은 Laravel의 공식 서버 관리 및 배포 서비스를 사용하는 것을 고려해 보십시오.

아래의 설정 파일과 같이 웹서버가 모든 요청을 애플리케이션의 public/index.php 파일로 전달하도록 설정해야 합니다. index.php 파일을 프로젝트의 루트 디렉토리로 옮기려 해서는 안되며, 프로젝트 루트에서 애플리케이션을 제공하면 많은 민감한 설정 파일이 공개 인터넷에 노출될 수 있습니다:

server {
    listen 80;
    listen [::]:80;
    server_name example.com;
    root /srv/example.com/public;
 
    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";
 
    index index.php;
 
    charset utf-8;
 
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
 
    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }
 
    error_page 404 /index.php;
 
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_hide_header X-Powered-By;
    }
 
    location ~ /\.(?!well-known).* {
        deny all;
    }
}

3.2 FrankenPHP

FrankenPHP도 Laravel 애플리케이션을 서빙하는 데 사용할 수 있습니다. FrankenPHP는 Go로 작성된 현대적인 PHP 애플리케이션 서버입니다. FrankenPHP를 사용하여 Laravel PHP 애플리케이션을 서빙하려면 php-server 명령어를 다음과 같이 호출하기만 하면 됩니다:

frankenphp php-server -r public/

FrankenPHP가 지원하는 Laravel Octane 통합, HTTP/3, 최신 압축, 또는 Laravel 애플리케이션을 독립 실행형 바이너리로 패키징하는 기능과 같은 더 강력한 기능을 활용하려면 FrankenPHP의 Laravel 문서를 참조하십시오.

4 최적화

애플리케이션을 프로덕션 환경에 배포할 때는 설정, 이벤트, 라우트, 뷰와 같은 다양한 파일을 캐시해야 합니다. Laravel은 이러한 모든 파일을 캐시할 수 있는 단일하고 편리한 optimize Artisan 명령어를 제공합니다. 이 명령어는 애플리케이션 배포 과정의 일부로 호출하는 것이 일반적입니다:

php artisan optimize

optimize 명령어로 생성된 모든 캐시 파일을 제거하려면 optimize:clear 메소드를 사용할 수 있습니다:

php artisan optimize:clear

아래에서는 optimize 명령어가 실행하는 각 세부 최적화 명령어에 대해 논의할 것입니다.

4.1 캐싱 설정

애플리케이션을 프로덕션 환경에 배포할 때, 배포 프로세스 중에 config:cache Artisan 명령어를 실행해야 합니다:

php artisan config:cache

이 명령어는 Laravel의 모든 설정 파일을 하나의 캐시된 파일로 결합하여, 프레임워크가 설정 값을 로드할 때 파일 시스템에 접근하는 횟수를 크게 줄입니다.

Warning

배포 과정 중에 config:cache 명령어를 실행한다면, 설정 파일 내에서만 env 함수를 호출하고 있는지 확인해야 합니다. 설정이 캐시된 후에는 .env 파일이 로드되지 않으며, .env 변수에 대한 env 함수 호출은 모두 null을 반환하게 됩니다.

4.2 이벤트 캐싱

배포 과정에서 애플리케이션의 자동 발견된 이벤트-리스너 매핑을 캐싱해야 합니다. 이는 배포 중에 event:cache Artisan 명령을 실행하여 수행할 수 있습니다:

php artisan event:cache

4.3 라우트 캐싱

많은 라우트를 포함한 대규모 애플리케이션을 구축하는 경우, 배포 과정에서 route:cache Artisan 명령어를 실행하는지 확인해야 합니다:

php artisan route:cache

이 명령어는 모든 라우트 등록을 캐시된 파일 내의 단일 메소드 호출로 줄여, 수백 개의 라우트를 등록할 때의 성능을 향상시킵니다.

4.4 뷰 캐싱

애플리케이션을 프로덕션에 배포할 때, 배포 과정에서 view:cache Artisan 명령어를 실행하는지 확인해야 합니다:

php artisan view:cache

이 명령어는 모든 Blade 뷰를 미리 컴파일하여, 요청 시 뷰가 컴파일되지 않도록 하여 뷰를 반환하는 각 요청의 성능을 향상시킵니다.

5 디버그 모드

config/app.php 설정 파일의 디버그 옵션은 오류에 대한 정보가 사용자에게 얼마나 많이 표시되는지를 결정합니다. 기본적으로 이 옵션은 애플리케이션의 .env 파일에 저장된 APP_DEBUG 환경변수 값을 따르도록 설정되어 있습니다.

Warning

프로덕션 환경에서는 이 값을 항상 false로 설정해야 합니다. 만약 APP_DEBUG 변수가 프로덕션에서 true로 설정되어 있으면, 애플리케이션의 최종 사용자에게 민감한 설정 값이 노출될 위험이 있습니다.

6 Health 라우트

Laravel은 애플리케이션 상태 모니터링에 사용할 수 있는 빌트인 헬스체크 라우트를 포함하고 있습니다. 프로덕션 환경에서 이 라우트는 업타임 모니터, 로드 밸런서 또는 Kubernetes와 같은 오케스트레이션 시스템에 애플리케이션의 상태를 보고하는 데 사용될 수 있습니다.

기본적으로, 헬스체크 라우트는 /up에서 제공되며 애플리케이션이 예외(exception) 없이 부팅된 경우 200 HTTP 응답을 반환합니다. 그렇지 않으면 500 HTTP 응답을 반환합니다. 이 라우트의 URI는 애플리케이션의 bootstrap/app 파일에서 다음과 같이 설정할 수 있습니다:

->withRouting(
    web: __DIR__.'/../routes/web.php',
    commands: __DIR__.'/../routes/console.php',
    health: '/status',
)

이 라우트로 HTTP 요청이 들어오면 Laravel은 Illuminate\Foundation\Events\DiagnosingHealth 이벤트도 디스패치하여 애플리케이션과 관련된 추가 헬스체크를 수행할 수 있도록 합니다. 이 이벤트의 리스너 내에서 애플리케이션의 데이터베이스나 캐시 상태를 확인할 수 있습니다. 애플리케이션에 문제가 있다고 감지되면 리스너에서 예외를 던지기만 하면 됩니다.

7 Forge / Vapor를 사용한 쉬운 배포

Laravel Forge

서버 설정 관리를 직접 할 준비가 되어 있지 않거나 다양한 서비스를 구성하는 것이 불편하다면, Laravel Forge는 훌륭한 대안입니다.

Laravel Forge는 DigitalOcean, Linode, AWS 등 다양한 인프라 제공업체에서 서버를 생성할 수 있습니다. 또한, Forge는 Nginx, MySQL, Redis, Memcached, Beanstalk 등 강력한 Laravel 애플리케이션을 구축하는 데 필요한 모든 도구를 설치하고 관리합니다.

Note

Laravel Forge로 배포하는 전체 가이드가 필요하신가요? Laravel Bootcamp와 Laracasts에서 제공하는 Forge 비디오 시리즈를 확인해 보세요.

Laravel Vapor

완전한 서버리스, 자동확장 배포 플랫폼을 원한다면, Laravel Vapor를 확인해 보세요. Laravel Vapor는 AWS 기반의 Laravel을 위한 서버리스 배포 플랫폼입니다. Vapor에서 Laravel 인프라를 시작하고 서버리스의 확장가능한 단순성에 반해 보세요. Laravel Vapor는 Laravel의 창시자들이 프레임워크와 원활하게 작동하도록 파인튜닝했기 때문에 Laravel 애플리케이션을 평소처럼 계속 작성할 수 있습니다.