배포 (Deployment)

• 소개
• 서버 요구 사항
• 서버 설정
  • Nginx
  • FrankenPHP
  • 디렉터리 권한
• 최적화
  • 설정 캐싱
  • 이벤트 캐싱
  • 라우트 캐싱
  • 뷰 캐싱
• 서비스 다시 로드하기
• 디버그 모드
• 헬스 체크 라우트
• Laravel Cloud 또는 Forge로 배포하기

소개 (Introduction)

Laravel 애플리케이션을 프로덕션에 배포할 준비가 되었다면, 애플리케이션이 최대한 효율적으로 실행되도록 하기 위해 수행할 수 있는 몇 가지 중요한 작업이 있습니다. 이 문서에서는 Laravel 애플리케이션을 올바르게 배포하기 위한 좋은 시작점을 다룹니다.

서버 요구 사항 (Server Requirements)

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

• PHP >= 8.3
• Ctype PHP Extension
• cURL PHP Extension
• DOM PHP Extension
• Fileinfo PHP Extension
• Filter PHP Extension
• Hash PHP Extension
• Mbstring PHP Extension
• OpenSSL PHP Extension
• PCRE PHP Extension
• PDO PHP Extension
• Session PHP Extension
• Tokenizer PHP Extension
• XML PHP Extension

서버 설정 (Server Configuration)

Nginx

Nginx가 실행 중인 서버에 애플리케이션을 배포하는 경우, 다음 설정 파일을 웹 서버 설정의 출발점으로 사용할 수 있습니다. 대부분의 경우 이 파일은 서버 설정에 맞게 수정해야 합니다. 서버 관리에 도움이 필요하다면 Laravel Cloud와 같은 완전 관리형 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 ~ ^/index\.php(/|$) {
        fastcgi_pass unix:/var/run/php/php8.3-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;
    }
}

FrankenPHP

FrankenPHP도 Laravel 애플리케이션을 제공하는 데 사용할 수 있습니다. FrankenPHP는 Go로 작성된 현대적인 PHP 애플리케이션 서버입니다. FrankenPHP를 사용하여 Laravel PHP 애플리케이션을 제공하려면 php-server 명령어를 실행하면 됩니다.

frankenphp php-server -r public/

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

디렉터리 권한

Laravel은 bootstrap/cache 및 storage 디렉터리에 파일을 쓸 수 있어야 하므로, 웹 서버 프로세스 소유자에게 이 디렉터리에 쓸 권한이 있는지 확인해야 합니다.

최적화 (Optimization)

애플리케이션을 프로덕션에 배포할 때는 설정, 이벤트, 라우트, 뷰를 포함한 여러 파일을 캐싱해야 합니다. Laravel은 이러한 파일을 모두 캐싱하는 하나의 편리한 optimize Artisan 명령어를 제공합니다. 일반적으로 이 명령어는 애플리케이션 배포 과정의 일부로 실행해야 합니다.

php artisan optimize

optimize:clear 메서드는 optimize 명령어가 생성한 모든 캐시 파일과 기본 캐시 드라이버의 모든 키를 제거하는 데 사용할 수 있습니다.

php artisan optimize:clear

다음 문서에서는 optimize 명령어가 실행하는 각각의 세부 최적화 명령어를 살펴봅니다.

설정 캐싱

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

php artisan config:cache

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

배포 과정에서 config:cache 명령어를 실행한다면, env 함수는 설정 파일 안에서만 호출해야 합니다. 설정이 캐싱되면 .env 파일은 로드되지 않으며, .env 변수에 대한 모든 env 함수 호출은 null을 반환합니다.

이벤트 캐싱

배포 과정에서 애플리케이션의 자동 감지된 이벤트와 리스너 매핑을 캐싱해야 합니다. 배포 중 event:cache Artisan 명령어를 실행하면 됩니다.

php artisan event:cache

라우트 캐싱

많은 라우트를 가진 대규모 애플리케이션을 빌드하고 있다면, 배포 과정에서 route:cache Artisan 명령어를 실행해야 합니다.

php artisan route:cache

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

뷰 캐싱

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

php artisan view:cache

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

서비스 다시 로드하기 (Reloading Services)

Laravel Cloud에 배포하는 경우 모든 서비스의 중단 없는 다시 로드가 자동으로 처리되므로 reload 명령어를 사용할 필요가 없습니다.

애플리케이션의 새 버전을 배포한 후에는 queue worker, Laravel Reverb, Laravel Octane과 같이 오래 실행되는 서비스가 새 코드를 사용하도록 다시 로드하거나 다시 시작해야 합니다. Laravel은 이러한 서비스를 종료하는 하나의 reload Artisan 명령어를 제공합니다.

php artisan reload

Laravel Cloud를 사용하지 않는다면, 다시 로드할 수 있는 프로세스가 종료될 때 이를 감지하고 자동으로 다시 시작할 수 있는 프로세스 모니터를 직접 설정해야 합니다.

디버그 모드 (Debug Mode)

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

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

헬스 체크 라우트 (The Health Route)

Laravel에는 애플리케이션 상태를 모니터링하는 데 사용할 수 있는 내장 헬스 체크 라우트가 포함되어 있습니다. 프로덕션에서는 이 라우트를 사용하여 애플리케이션 상태를 uptime monitor, load balancer 또는 Kubernetes와 같은 오케스트레이션 시스템에 보고할 수 있습니다.

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

->withRouting(
    web: __DIR__.'/../routes/web.php',
    commands: __DIR__.'/../routes/console.php',
    health: '/up', // [tl! remove]
    health: '/status', // [tl! add]
)

이 라우트에 HTTP 요청이 들어오면 Laravel은 Illuminate\Foundation\Events\DiagnosingHealth 이벤트도 디스패치하므로, 애플리케이션에 맞는 추가 헬스 체크를 수행할 수 있습니다. 이 이벤트의 리스너 안에서 애플리케이션의 데이터베이스 또는 캐시 상태를 확인할 수 있습니다. 애플리케이션에 문제가 감지되면 리스너에서 예외를 던지면 됩니다.

Laravel Cloud 또는 Forge로 배포하기 (Deploying With Laravel Cloud or Forge)

Laravel Cloud

Laravel에 맞게 조정된 완전 관리형 자동 확장 배포 플랫폼이 필요하다면 Laravel Cloud를 확인해 보십시오. Laravel Cloud는 Laravel을 위한 강력한 배포 플랫폼으로, 관리형 컴퓨팅, 데이터베이스, 캐시, 객체 스토리지를 제공합니다.

Laravel 애플리케이션을 Cloud에서 실행하고, 확장 가능한 단순함을 경험해 보십시오. Laravel Cloud는 Laravel 제작자들이 프레임워크와 매끄럽게 작동하도록 세밀하게 조정했기 때문에, 지금까지 익숙한 방식 그대로 Laravel 애플리케이션을 계속 작성할 수 있습니다.

Laravel Forge

직접 서버를 관리하고 싶지만 강력한 Laravel 애플리케이션을 실행하는 데 필요한 여러 서비스를 설정하는 일이 익숙하지 않다면, Laravel Forge는 Laravel 애플리케이션을 위한 VPS 서버 관리 플랫폼입니다.

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