라라벨12 AWS 라이트세일에 배포하기

2025-03-09 | 라라벨 12, Inertia.js, React 19, TailwindCSS, ShadCN 기반으로 블로그를 구축하는 방법

라라벨 12, Inertia.js, React 19, TailwindCSS, ShadCN 기반으로 블로그를 구축하는 방법입니다. Next.js와 유사하지만, 더 확장된 백엔드 기능을 활용할 수 있는 - 라라벨의 React Starter Kit과 Inertia.js를 활용해 프론트엔드와 백엔드를 통합된 환경을 경험할 수 있습니다. 최적화 및 배포 과정을 다루고 있습니다.

기본설정

기본적인 환경은 이렇습니다.

라라벨 12
Inertia.js + React 19
ShadCN / Tailwindcss
CloudPanel

새롭게 블로그를 만들면서, 라라벨 12 React Starter kit을 이용한 상태입니다. CloudPanel을 이용해 사이트를 생성하여, Laravel 12 설정을 그대로 이용하여 Vhost와 같은 부분에서 별다른 설정을 거치지 않고 바로 사용할 수 있는 환경입니다.

별도의 Nginx와 같은 설정을 필요로할 경우엔 라라벨 배포 페이지를 통해 세부사항을 확인하기 바랍니다. 참고:라라벨 배포 문서

github 저장소 연결

기본적으로 만들어지는 public 폴더를 지운 후 깃허브 저장소로부터, 로컬에서 개발한 소스를 클론해옵니다. 깃허브에서 AWS 라이트세일 인스턴스에 private 저장소를 클론해 올때는 먼저 github 인증 과정부터 거쳐야합니다.

SSH키 생성

라이트세일 인스턴스에서 아래 명령을 통해 SSH 키를 생성합니다.

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

기본적인 경로를 통해 생성된 키는 ~/.ssh/id_rsa.pub 라는 형식으로 생성됩니다. cat 명령으로 키 값을 확인합니다.

cat ~/.ssh/id_rsa.pub

이메일 주소를 포함하여 내용을 복사합니다.

Github 계정의 settings 페이지에서 SSH and GPG 페이지로 이동합니다. new SSH Key를 눌러 방금 복사한 내용을 붙여넣어 줍니다. 이제 별도의 인증 없이 깃허브 저장소로부터 프로젝트를 clone해올 수 있습니다.

프로젝트를 설치할 경로에서 아래 명령으로 깃허브 저장소를 복제합니다.

git clone git@github.com:username/repository.git .

node 설치 여부 확인

npm 패키지를 설치해야하기때문에 현재 운영체제에 node가 설치되어있는지 확인해야합니다. 제 경우엔 node 18 버전으로 설치되어있어서 좀 더 높은 LTS 버전으로 설치하기로 했습니다. nvm을 이용하는 것이 좋은데, nvm --version 명령으로 확인해보고, 설치 되어 있지 않다면 아래 명령으로 nvm을 설치합니다.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash

설치가 완료되고 나면 자동으로 .bashrc 파일이 변경됩니다. 재부팅 없이 즉시 적용해주기 위해 아래 명령을 입력합니다.

source ~/.bashrc

다시 nvm --version을 실행해보면, 설치된 것을 확인할 수 있습니다.

nvm --version #버전확인
nvm list-remote #설치가능한 node.js 버전확인
nvm install --lts #최신LTS 설치

특정 버전을 원하는것이 아니면 nvm install --lts로 설치하여 마무리합니다.

npm 패키지 설치

react를 비롯해 여러가지 npm 패키지를 설치하여 프론트엔드 부분을 별도로 의존하고 있기때문에, npm 패키지를 설치해줍니다.

npm install

패키지를 모두 설치하고나면 build 과정을 거쳐야합니다.

npm run build

라라벨의 react startet kit의 경우엔 별도로 frontend 웹사이트와 REST API로 통신하는게 아니라 Inertia.js라는 라이브러리를 통해 직접 라라벨 백엔드와 통신합니다. Next.js처럼 백엔드가 통합된 개념이지만, Next.js에 비해서 인증,데이터베이스,보안, 등 강력한 백엔드 기능이 기본적으로 포함되어 있습니다.

composer 패키지 설치

php에서도 여러가지 패키지를 설치하여 사용하기 때문에 아래 명령으로 패키지를 설치해줍니다.

composer install

App Key 생성

라라벨 프로젝트를 로컬에 설치할 경우엔 필요없는 과정이지만, 저장소에서 복사해올 경우엔 app key가 설정되지 않은 상태입니다. app key가 없다면 500 에러를 발생시킵니다. 아래 명령을 통해 app key를 생성해줍니다.

php artisan key:generate

env 설정

환경 설정 파일(.env)을 생성해야하는데, .env.sample 파일을 복사하여 사용하면 됩니다.

cp .env.sample .env

많은 내용들이 있지만, 주로 바꿔야하는 내용은 아래와 같습니다.

APP_NAME= #앱이름
APP_ENV=local
APP_KEY= #앱키로자동생성
APP_DEBUG=false #프로덕션에선 false로 디버그 기능을 비활성화
APP_URL=http://localhost
...
APP_LOCALE=ko
APP_FALLBACK_LOCALE=en
APP_FAKER_LOCALE=ko_KR
...
DB_CONNECTION=mysql #원하는 데이터베이스 설정
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=root
DB_PASSWORD=password

기본적인 내용은 위와 같고, 필요에 따라 다른 설정도 입력해줄 수 있습니다.

database와 연결해주기 위해 아래 명령을 실행해줍니다.

php artisan migrate

최적화

배포를 위해 최적화 과정이 필요합니다. 아래 링크에 있는 내용들을 실행해줍니다. 참고:라라벨 배포 최적화

php artisan optimize
php artisan optimaze:clear #위의 최적화를 전부 clear해야할 경우

기타

개인적으로는 php artisan config:cache 과정에서 Your configuration files are not serializable 에러가 발생했는데, 이 에러는 config 폴더 안에 있는 파일 중 closure 형식으로 선언된 부분이 있을 경우 문제가 됩니다.

예시를 보면 아래와 같습니다.

// 에러가 발생하는 경우
return [
'key'=> function(param) {
return param;
}];

// 정상적으로 작동하는 경우
return [
'key' => 'value'
];

위의 과정을 거쳐서 배포를 마무리할 수 있습니다. 기타 다른 설정들도 필요할 수 있는데, 현재 이 웹사이트를 만들면서 추가적으로 블로그로 기록을 남길 예정입니다.