Laravel Docker 설치 완벽 가이드 | Composer부터 권한 오류 해결까지 한 번에

Docker로 Laravel 앱 만들기: 한 개발자의 솔직한 이야기

Laravel이 뭔지 처음 들었을 때 솔직히 좀 낯설었어요. PHP는 알고 있었지만, 그 위에 뭔가 프레임워크가 얹힌다니… 어렵게 느껴졌거든요. 그런데 막상 해보니까 오히려 더 편하더라고요. 거기에 Docker까지 얹으면? 음... 처음엔 머리 아팠지만 지금은 이 조합 없이 개발하기가 싫어요. 깔끔하고, 어디서든 똑같은 환경이니까요.

이번엔 제가 Laravel을 Docker로 세팅하면서 느꼈던 시행착오, 그리고 그걸 해결해나간 경험을 바탕으로 천천히 같이 가보려고 해요. 특히 Linux에서 권한 때문에 삽질했던 분들, 저도 그랬으니까 걱정 마세요!

 

---

 

Laravel 설치? Composer 하나면 끝나요

 

Laravel 설치? Composer 하나면 끝나요

처음 Laravel 시작할 땐 공식 문서를 찾아보세요. 진짜 친절하게 설명돼 있어요. 거기 보면 이런 명령어 하나로 프로젝트가 뚝딱 만들어진다고 하죠:

composer create-project laravel/laravel example-app

 

그런데 제 경우에는 Composer를 굳이 시스템에 설치하고 싶진 않았어요. 환경 꼬이면 골치 아프잖아요. 그래서 Docker로 돌리기로 했죠.

 

---

 

Composer, 그냥 Docker로 돌리자

제가 했던 방법은요, src라는 폴더 하나 만들고 거기서 이 명령어 돌리는 거였어요:

docker compose run --rm composer create-project laravel/laravel .

 

설명하자면:

• run: 일회용 컨테이너 실행
• --rm: 실행 끝나면 알아서 컨테이너 삭제
• composer: 컨테이너 이름
• 마지막 .: 지금 디렉토리에 설치하라는 의미예요

 

이렇게 하면 Composer 설치 필요도 없고, 뭐가 꼬일 일도 없어요. 진짜 속 편해요.

 

---

 

docker-compose.yml은 왜 필요하냐고요?

이게 있어야 Docker가 뭘 어떻게 돌릴지 알 수 있어요. 지금은 Composer만 쓸 거니까 간단하게 가면 돼요. 나중에 PHP, Nginx, DB까지 넣으려면 이 파일이 훨씬 중요해지지만, 지금은 그냥 Composer만 설정해도 충분해요.

 

---

 

Linux 쓰는 사람들... 권한 문제 조심하세요

진짜 이거 때문에 며칠을 날렸어요. bind mount로 파일이 로컬에 복사되는데, 권한 꼬이면 진짜 곤란하거든요. 그래서 제가 찾은 해결법은 이거예요:

 

1. PHP Dockerfile 이렇게 바꾸세요

FROM php:8.2.4-fpm-alpine

WORKDIR /var/www/html

COPY src .

RUN docker-php-ext-install pdo pdo_mysql

RUN addgroup -g 1000 laravel && adduser -G laravel -g laravel -s /bin/sh -D laravel

USER laravel

 

왜 이렇게 하냐면요: root로 파일을 생성하면 나중에 수정도 못 해요. 그냥 laravel이라는 유저를 만들어서 그걸로 다 작업하게 만드는 게 제일 속 편해요.

 

2. Composer Dockerfile도 비슷하게

FROM composer:2.5.7

RUN addgroup -g 1000 laravel && adduser -G laravel -g laravel -s /bin/sh -D laravel

USER laravel

WORKDIR /var/www/html

ENTRYPOINT [ "composer", "--ignore-platform-reqs" ]

 

이렇게 맞춰두면, PHP랑 Composer 둘 다 같은 유저로 작업하니까 파일 충돌 걱정이 사라져요.

 

---

 

.의 역할? 진짜 중요해요

 

.의 역할? 진짜 중요해요

명령어 끝에 점 하나 찍은 거 별 거 아닌 것 같지만, 이게 핵심이에요. 현재 디렉토리에 설치하겠다는 뜻이거든요. 그리고 이게 Docker 안에서 실행돼도 바깥 src 폴더랑 연결되어 있어서 그대로 반영돼요. 이거 알기 전엔 왜 설치가 안 되나 삽질했었죠...

 

---

 

그럼 Docker는 그 안에서 뭘 하는 걸까?

생각보다 단순해요:

1. Composer 이미지 받기
2. 컨테이너 잠깐 실행
3. Laravel 프로젝트 만들기
4. 컨테이너 삭제하기

 

매번 같은 방식으로 동작하니까, 어디서든 똑같이 만들 수 있어요. 진짜 깔끔해요.

 

---

 

설치가 끝났다면? 이제 제대로 실행해보자

Laravel 폴더가 생겼으면 반은 성공이에요. 이제 로컬에서 php artisan serve로 돌리거나, Docker로 Nginx 붙여서 제대로 서비스 환경까지 만들 수도 있어요. 그건 다음 도전으로 남겨두자고요.

 

---

 

혹시 오류났어요? 저도 그랬어요

 

혹시 오류났어요? 저도 그랬어요

파일 권한 꼬이면 진짜 머리 아파요. 그래서 이 두 가지만 꼭 지키세요:

• PHP와 Composer에서 같은 유저(larevel)를 쓰기
• UID/GID를 동일하게 맞추기

이 방법으로도 해결 안 되면, 저처럼 Udemy Q&A를 뒤져보세요. 거기에 저 포함해서 많은 사람들이 같은 문제 겪었더라고요.

 

---

 

마무리하면서: 처음이라서 더 소중한 경험

이 과정, 그냥 Laravel 설치하는 것 같지만 사실은 '개발자 다운 개발자'로 나아가는 길이었어요. Docker를 쓰는 건 단지 멋내기용이 아니라, 나중에 진짜 효율적인 개발과 협업을 가능하게 해주는 기반이 되거든요.

물론 처음엔 헷갈릴 수 있어요. 저도 무슨 말인지 몰라서 반나절 동안 터미널이랑 씨름했으니까요. 근데 그렇게 하나하나 해보면서 쌓인 게 결국 저만의 환경이 됐고, 지금은 어디서든 자신 있게 개발할 수 있게 됐어요.

여러분도 충분히 할 수 있어요. 오늘 하나 배웠다면, 내일은 더 멋진 걸 만들 수 있을 거예요. Laravel, Docker, 그리고 여러분의 프로젝트—지금부터 시작입니다!