Laravel과 MySQL Docker로 연결하기, .env 설정부터 artisan까지 완전 정리

내 개발 환경을 바꾼 Laravel + Docker 이야기

처음 Laravel을 접했을 때만 해도, 이게 뭐가 그렇게 대단하다는 거지? 라는 생각이 솔직히 들었어요. 하지만 진짜 매력은 Docker와 함께 쓸 때 시작되더라고요. 진짜 무슨 마법처럼, 세팅이 딱! 깔끔하고 편해지는 그 느낌이란...

그래서 이번 글은 딱딱한 매뉴얼이 아니라, 제가 Laravel을 Docker랑 엮으면서 겪었던 경험을 중심으로 편하게 풀어볼게요. 혹시라도 "나만 헷갈리나?" 싶은 분들께 위로도 드리고, 작은 팁도 같이 나누고 싶어서요 :)

 

---

 

Step 1: 처음 만나는 .env의 세계

 

Step 1: 처음 만나는 .env의 세계

Laravel 프로젝트를 막 만들고 나면, source 폴더 안에 .env 파일이라는 게 있어요. 이게 진짜 중요한데, 약간 비유하자면 이건 Laravel 앱의 주소록이나 핸드폰 설정 같은 거예요. 여기서 데이터베이스 접속 정보를 직접 수정해줘야 합니다.

예전에 저도 처음에 이걸 건드리지 않고 계속 "DB 연결 안 됨" 메시지만 보고 좌절했었어요. 알고 보니 DB_HOST에 이상하게 IP 주소를 넣고 있었던 거 있죠... 사실 그냥 mysql이라고 쓰면 되는데 말이죠.

DB_DATABASE=homestead
DB_USERNAME=homestead
DB_PASSWORD=secret
DB_HOST=mysql

 

이렇게만 맞춰주면 Laravel이 컨테이너 안의 MySQL과 문제 없이 소통합니다. 알고 나면 별거 아닌데, 처음엔 진짜 왜 안 되는지 하루종일 붙잡고 있었네요 ㅎㅎ

 

---

 

Step 2: 서비스들이 어떻게 서로 말하는지

 

Step 2: 서비스들이 어떻게 서로 말하는지

Laravel이 돌아가려면 기본적으로 세 친구가 필요해요:

• Nginx (문을 여는 친구)
• PHP (말을 이해하는 친구)
• MySQL (기억을 맡아주는 친구)

 

요청이 들어오면 Nginx가 받았다고 PHP에게 전달하고, PHP가 필요할 때 MySQL에게 뭔가 물어보는 구조예요. 근데 이게 잘 작동하려면 로컬의 source 폴더를 /var/www/html 경로에 잘 바인딩해줘야 해요. 예전에 이걸 빼먹고 왜 페이지가 안 뜨지? 하고 엄청 헤맸던 기억이 나네요.

 

---

 

Step 3: docker-compose로 쉽게 시작하기

Docker 명령어가 어렵다고 느껴지셨다면, docker-compose는 정말 구세주 같은 존재예요. 예를 들면 이런 식으로요:

docker-compose up server php mysql

 

예전엔 막 하나하나 컨테이너 실행시키면서 헷갈렸는데, 이거 하나면 필요한 서비스만 딱 실행돼요. 그리고 --detach 붙이면 백그라운드로 조용히 돌아가고, --build 넣으면 Dockerfile 수정된 것도 반영돼요.

근데 여기서 진짜 중요한 포인트! 볼륨 설정이 꼬이면 Nginx가 Laravel 코드를 못 봅니다. 즉, 설정 잘못하면 그냥 하얀 화면이에요... (경험담 ㅠㅠ)

 

---

 

Step 4: 설정이 꼬였을 때 대처법

 

Step 4: 설정이 꼬였을 때 대처법

어느 날 갑자기 Nginx가 말을 안 듣길래 멘붕이었는데, 원인은 너무 간단했어요. config 파일이 엉뚱한 위치에 마운트돼 있었던 거죠.

docker-compose down

docker-compose up --build server php mysql

 

이렇게 깔끔하게 다시 시작하면 대부분 해결돼요. 다시 localhost:8000 들어가 보면 Laravel의 친숙한 환영 메시지가 반겨줄 거예요. (그때 진짜 울 뻔했어요...)

 

---

 

Step 5: 반복 작업 줄이기

매번 server, php, mysql 입력하는 거 너무 귀찮더라고요. 그래서 알게 된 게 depends_on 설정!

services:
  server:
    depends_on:
      - php
      - mysql

 

이렇게 설정해두면 server 하나만 실행해도 나머지는 자동으로 따라옵니다. 너무 편해서 처음엔 살짝 감동했어요.

 

---

 

Step 6: Artisan과 NPM도 컨테이너로 깔끔하게

Laravel에서는 artisan 명령어나 npm 빌드 같은 거 자주 하잖아요? 근데 이걸 매번 로컬에 설치해서 쓰기 귀찮더라고요. 그래서 아예 컨테이너로 따로 빼는 게 낫겠다는 생각이 들었어요.

 

Artisan

PHP 이미지 하나 더 쓰고, 엔트리포인트만 php /var/www/html/artisan으로 설정하면 끝!

docker-compose run artisan migrate

 

이 명령어 하나로 migration도 깔끔하게 처리돼요. 로컬에 php 설치 안 해도 되니까 진짜 개꿀.

 

NPM

Node.js도 마찬가지로 이미지 하나 쓰고, 디렉토리 설정과 npm 엔트리포인트만 설정하면 끝!

docker-compose run npm install

 

이거 설정해두면 나중에 프론트 작업할 때 진짜 편해요.

 

---

 

Step 7: Dockerfile 바꿨으면 잊지 말고 rebuild

이건 저도 자주 까먹는 건데, Dockerfile 수정한 후에는 반드시 다시 빌드해야 해요.

docker-compose up --build

 

안 그러면 왜 바뀐 게 안 반영되지? 하고 며칠 동안 헛수고만 하게 됩니다... (누군가의 실화)

다행히 Docker는 변경 없는 부분은 캐시 덕분에 빠르게 처리해줘서 기다리는 시간이 짧아요. 하지만 다시 말하지만, build 잊지 마세요!

 

---

 

정리하면서...

이제 Docker 위에서 Laravel이 잘 돌아가고 있다면, 여러분은 꽤 멋진 환경을 가진 거예요. 컨테이너로 나눠진 서비스, 환경 변수 설정, artisan이나 npm 같은 유틸리티까지 다 갖춘 셈이죠.

사실 처음엔 저도 머리가 아팠어요. 뭐가 뭔지 하나도 모르겠고, 맨날 에러 메시지랑 씨름했죠. 근데 어느 순간부터, 이 구조가 엄청 강력하다는 걸 느꼈어요.

나도 이제는 남 부럽지 않은 개발 환경을 갖췄다! 라고 자신 있게 말할 수 있을 거예요 :)