Laravel 설치¶

운영 서버(Production Server) 에서 Laravel을 실행 가능한 상태로 준비하기 위한 표준 설치/초기 구성 절차를 정의함. 개발 편의 설정이나 임시 실행 방식은 다루지 않음.

1. 설치 방식 선정 기준¶

운영 서버에서는 다음 조건을 반드시 만족해야 함.

nginx + php-fpm과 완전 호환
재부팅 후 자동 복구 가능
실행 경로 고정 (/var/www/[ProjectName]/current)
사용자 쉘 환경에 의존하지 않음
코드/의존성 변경은 개발 경로에서만 수행

2. `artisan serve`를 설치 기준에서 제외하는 이유¶

운영 서버에서 다음 방식은 허용하지 않음.

php artisan serve

이유¶

개발용 내장 서버이므로 운영 트래픽 기준 미충족
systemd/supervisor 기반 자동 복구 구조와 분리됨
운영 로그/권한/SELinux 정책과 일관성 유지 어려움

운영 서버 HTTP 경로는 Nginx → PHP-FPM → Laravel 로 고정함.

3. 필수 패키지 설치¶

sudo dnf install -y epel-release
sudo dnf install -y \
  nginx \
  php php-cli php-fpm php-common \
  php-mbstring php-xml php-json php-gd php-zip php-intl \
  php-mysqlnd php-opcache php-bcmath \
  composer git unzip policycoreutils-python-utils

설치 확인:

which php composer nginx
php -v
composer --version
nginx -v

정상 예시:

/usr/bin/php
/usr/bin/composer
/usr/sbin/nginx

4. 개발 경로와 운영 경로 분리¶

기본 구조¶

/home/[User]/[ProjectName]                → 개발 / 빌드 / 테스트
/var/www/[ProjectName]/current            → 운영 실행 경로
/var/www/[ProjectName]/releases/...       → 릴리즈 보관 (선택)

이유¶

운영 경로 오염 방지
롤백 가능성 확보
권한/SELinux 충돌 예방

4.1 개발 경로 준비 (`/home`)¶

sudo mkdir -p /home/[User]/[ProjectName]
sudo chown -R [User]:[Group] /home/[User]/[ProjectName]
sudo chmod -R 0755 /home/[User]/[ProjectName]

4.2 운영 경로 준비 (`/var/www`)¶

sudo mkdir -p /var/www/[ProjectName]
sudo chown -R [User]:nginx /var/www/[ProjectName]
sudo chmod -R 0755 /var/www/[ProjectName]

5. Laravel 프로젝트 준비 (개발 경로 기준)¶

아래 작업은 반드시 /home/[User]/[ProjectName] 에서 수행함.

cd /home/[User]/[ProjectName]
composer install --no-dev --optimize-autoloader
cp .env.example .env
php artisan key:generate

운영 기준 .env 핵심값:

APP_ENV=production
APP_DEBUG=false
APP_URL=https://example.com
LOG_CHANNEL=daily

6. 운영 실행 경로 반영¶

릴리즈 구조를 사용하는 경우 current 심링크를 기준으로 실행함.

ls -l /var/www/[ProjectName]/current

캐시 반영(운영 경로):

cd /var/www/[ProjectName]/current
php artisan config:cache
php artisan route:cache
php artisan view:cache

clear만 수행하고 cache를 생성하지 않은 채 운영하지 않음.

7. 권한 정책 (필수)¶

Laravel 쓰기 가능 경로는 최소화해야 함.

storage/
bootstrap/cache/

sudo chown -R [User]:nginx /var/www/[ProjectName]/current
sudo find /var/www/[ProjectName]/current -type d -exec chmod 0755 {} \;
sudo find /var/www/[ProjectName]/current -type f -exec chmod 0644 {} \;
sudo chmod -R ug+rwx /var/www/[ProjectName]/current/storage
sudo chmod -R ug+rwx /var/www/[ProjectName]/current/bootstrap/cache

프로젝트 전체 777 권한 부여 금지.

8. SELinux 컨텍스트 설정¶

SELinux는 Enforcing 유지 기준이며, writable 경로만 정책 부여함.

확인:

sudo semanage fcontext -l | grep "/var/www/[ProjectName]/current"

없으면 -a, 있으면 -m.

추가 예시:

sudo semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/[ProjectName]/current/storage(/.*)?"
sudo semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/[ProjectName]/current/bootstrap/cache(/.*)?"
sudo restorecon -Rv /var/www/[ProjectName]/current/storage
sudo restorecon -Rv /var/www/[ProjectName]/current/bootstrap/cache

수정 예시:

sudo semanage fcontext -m -t httpd_sys_rw_content_t "/var/www/[ProjectName]/current/storage(/.*)?"
sudo semanage fcontext -m -t httpd_sys_rw_content_t "/var/www/[ProjectName]/current/bootstrap/cache(/.*)?"
sudo restorecon -Rv /var/www/[ProjectName]/current/storage
sudo restorecon -Rv /var/www/[ProjectName]/current/bootstrap/cache

ex)

PROJECT="ProjectName"
PROJECT_ROOT="/var/www/${PROJECT}"
FOLDER="${PROJECT_ROOT}/current/storage"
PATTERN="(/.*)?"

sudo semanage fcontext -a -t httpd_sys_rw_content_t "${FOLDER}${PATTERN}" 2>/dev/null || sudo semanage fcontext -m -t httpd_sys_rw_content_t "${FOLDER}${PATTERN}"
sudo restorecon -Rv "${FOLDER}"

sudo semanage fcontext -l | grep "^${FOLDER}(\s|$)"

9. 설치 후 필수 검증¶

sudo nginx -t
sudo systemctl status nginx
sudo systemctl status php-fpm
php artisan about

검증 기준:

Nginx 설정 문법 정상
php-fpm active 상태
Laravel 앱 정보 정상 출력

10. 정리¶

Laravel 설치의 핵심은 패키지 나열이 아니라 운영 구조 일관성임
경로 분리 + 최소 권한 + SELinux + 캐시 반영 + 서비스 검증이 완료되어야 배포 가능함