docker로 php + NGiNX + MariaDB의 Laravel 개발 환경 구축 1편

도커^docker를 이용해서 php와 NGiNX, 그리고 데이터베이스는 MariaDB를 사용해서 라라벨^Laravel 개발 환경을 구축하는 방법을 정리해 보겠다.

아마 네 번으로 나눠서 포스팅을 할 것 같은데, 오늘의 포스트에는 php 컨테이너를 생성하는 것까지만 정리하겠다.

전체 디렉터리 구성

프로젝트
├── docker
│   ├── php   // php 컨테이너
│   │   ├── Dockerfile
│   │   └── php.ini
│   ├── nginx   // NGiNX 컨테이너
│   │   ├── Dockerfile
│   │   └── default.conf
│   └── mariadb   // MariaDB 컨테이너
│       ├── Dockerfile
│       └── my.conf
├── src   // Laravel 프로젝트의 코드가 들어가는 곳
└── docker-compose.yml   // 전체 컨테이너 관리

최종 디렉터리 구성은 이렇다.

최상위에 모든 컨테이너를 관리하는 docker-compose.yml 파일과 docker 디렉터리가 있고, docker 디렉터리 아래에 각 컨테이너의 Dockerfile과 구성 파일을 배치한다.

디렉터리를 생성하자

먼저 깃허브^GitHub에서 해당 프로젝트를 올릴 Repository를 생성한다.

1. Repository를 생성할 때 Add README를 껐을 경우

• mkdir 디렉터리명
  ubuntu를 실행시키고 이 명령어를 입력해서 원하는 이름의 디렉터리를 만든다.


• cd 디렉터리명
  그리고 이 명령어로 방금 만든 디렉터리로 들어간다.

2. Add README를 켰을 경우

• git clone 리포지토리URL
  ubuntu를 실행시키고 이 명령어를 입력한다.
  리포지토리 URL은 리포지토리에 'Code'라고 쓰여있는 녹색 버튼을 클릭해서 HTTPS나 SSH 중에서 선택한다.
  그러면 리포지토리의 name과 똑같은 이름으로 디렉터리가 생성될 것이다.


• cd 디렉터리명
  이 명령어로 방금 만든 디렉터리로 들어간다.

code .

이 명령어로 VSCode에서 디렉터리를 연다.

그리고 위에서 보여준 전체 디렉터리 구성을 보고 docker라는 디렉터리를 만들고, 그 안에 또 php 디렉터리를 만들자.

터미널에 명령어를 입력해서 만들어도 되고, VSCode를 이용해서 만들어도 된다.

docker-compose.yml 파일 생성

docker-compose.yml

version: "3.8" #Compose 파일의 버전

services:
  # php Service
  app: #서비스명
    build:
      context: . #빌드가 실행되는 위치 설정 (.은 현재 위치라는 뜻)
      dockerfile: ./docker/php/Dockerfile #빌드 할 Dockerfile의 경로 (docker-compose.yml에서 본 상대 경로)
    volumes:
      - ./src/:/var/www/html #호스트 측의 ./src/를 컨테이너 측의 /var/www/html에 마운트 한다는 뜻

최상위 디렉터리에 docker-compose.yml 파일을 만들고, 위의 코드를 넣었다.

코드에 대한 설명은 주석을 달아놓았다.

'호스트의 ./src/를 컨테이너의 /var/www/html에 마운트 한다'는 것이 무슨 뜻인지 이해가 안 된다면 아래의 영상을 참고하자.

php의 Dockerfile 생성

Dockerfile

FROM php:8.4.13-fpm

# COPY php.ini
COPY ./docker/php/php.ini /usr/local/etc/php/php.ini

# Composer Install
COPY --from=composer:2.8.12 /usr/bin/composer /usr/bin/composer

# Install Node.js
COPY --from=node:24.10.0 /usr/local/bin /usr/local/bin
COPY --from=node:24.10.0 /usr/local/lib /usr/local/lib

RUN apt-get update && apt-get install -y \
    git \
    zip \
    unzip \
    vim \
    libicu-dev \
    libzip-dev \
    libfreetype-dev \
    libjpeg62-turbo-dev \
    libpng-dev \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
	&& docker-php-ext-install -j$(nproc) gd \
    && docker-php-ext-install pdo_mysql bcmath intl zip pcntl \
    && pecl install redis xdebug \
    && docker-php-ext-enable redis xdebug \
    && rm -rf /var/lib/apt/lists/*

# npm 패키지 및 bun 설치 & 업그레이드
RUN npm install -g bun && bun upgrade

WORKDIR /var/www/html

php 디렉터리 안에 이렇게 Dockerfile을 생성한다.

• FROM php:8.4.13-fpm: 이미지를 빌드하기 위한 베이스 이미지를 설정한다.
• COPY ./docker/php/php.ini /usr/local/etc/php/php.ini: php.ini(php의 설정 파일)를 docker컨테이너 안에 카피한다.
• COPY --from=composer:2.8.12 /usr/bin/composer /usr/bin/composer: Laravel을 설치하기 위한 Composer를 인스톨한다.
• libicu-dev \: 이것이 빠지면 filament(관리자 패널)를 설치할 때 에러가 발생한다.
• intl: intl도 마찬가지, filament를 설치한다면 넣어주자.

설정 파일(php.ini) 생성

php.ini

[Date]
date.timezone = "Asia/Seoul"

[mbstring]
mbstring.language = "Korean"

[xdebug]
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.log=/tmp/xdebug.log
xdebug.log_level=0

그리고 같은 디렉터리 안에 php.ini 파일도 생성한다.

코드의 작성은 이것으로 끝이다.

혹시 깃허브에 commit을 한다면 이 단계에서 해도 괜찮다.

php 컨테이너를 생성하자

docker-compose up -d --build

ubuntu에서 이 명령어를 실행해서 이미지를 빌드하고 컨테이너를 기동 시킨다.

처음이거나 오랜만에 하는 거라면 시간이 꽤 걸린다. (5분 이상..?)

docker-compose ps

이 명령어를 사용하여 실행 중인 컨테이너를 확인해보자.

방금 생성한 컨테이너가 실행 중인 것이 보인다면 성공.

volumes:
  - ./src/:/var/www/html

docker-compose.yml 파일 안에 있던 이 코드로 인해서 이 시점부터 최상위 디렉터리 안에 src 디렉터리가 생성된 것을 확인할 수 있을 것이다.

docker-compose exec app bash #컨테이너 안으로 들어간다.
pwd #현재의 디렉터리 확인. '/var/www/html'이 나오면 정상.
php -v #설치된 php의 버전 확인
composer -v #Composer의 버전 확인
git --version #git의 버전 확인
php -m #인스톨이 끝난 확장 기능 목록 확인
cat /usr/local/etc/php/php.ini #php.ini가 카피되어 있는지 확인

ubuntu에서 이 명령어들을 하나씩 실행해서 모든 것이 잘 설치되었는지 확인해 보자.

exit

모두 확인했다면 exit를 입력해서 컨테이너 밖으로 나오자.

docker-compose exec app touch sample.php #컨테이너 내의 /var/www/html 안에 sample.php 파일 생성
docker-compose exec app pwd #현재 작업 디렉터리를 확인
docker-compose exec app ls #컨테이너의 /var/www/html 아래에 있는 파일 확인
ls src #프로젝트 디렉터리 아래의 /src 아래에 있는 파일 확인

이제부터는 컨테이너 밖에서 명령을 실행할 수 있는지 확인도 겸해 호스트와 컨테이너가 잘 연결되어 있는지 실험해 보기 위해 이 명령들을 실행해 보자.

마지막의 두 명령어로 똑같이 sample.php 파일이 있는 것을 확인했다면, 컨테이너 내의 /var/www/html에서 행한 것이 프로젝트의 /src에 반영되고 있다는 것을 알 수 있을 것이다.

마지막으로 /src에서 수정한 내용이 컨테이너 내의 /var/www/html에 반영되는지도 시험해 보자.

/src/sample.php 파일을 VSCode에서 열고 파일에 'hello'라고 쓰고 저장한다.

에러가 발생할 경우

Failed to save 'sample.php': ... (NoPermissions (FileSystemError): Error: EACCES: permission denied ...

VSCode에서 이런 에러가 뜨면서 저장이 되지 않는다면, ubuntu에서 아래의 명령어를 실행해서 파일의 현재 소유자와 그룹을 확인한다.

ls -l

아마 docker 디렉터리와 docker-compose.yml 파일의 소유자는 본인이지만,

src는 root로 되어있을 것이다.

whoami

이걸 입력해서 본인의 계정을 확인하고,

sudo chown -R 소유자:그룹 src/

위의 명령어를 실행한다. '소유자'와 '그룹'에는 본인의 계정을 넣는다.

그리고 다시 VSCode에서 /src/sample.php 파일을 저장하면 저장이 될 것이다.

sudo chmod -R 755 ./src

이것은 소유자와 그룹과 일반 사용자에게 어떤 권한을 줄 수 있는지 변경하는 명령어다.

src/ 에는 755가 디폴트로 설정되어 있다.

어디선가 777을 입력하라고 쓰여 있는 것도 봤는데 그건 잘못된 정보다.

일반 사용자에게 쓰기 권한을 부여하면 해당 파일이나 디렉터리에 대한 수정, 삭제가 가능하게 된다.

일반적으로 웹 서버 프로세스는 웹 사이트의 내용을 읽을 수 있도록 읽기 및 실행 권한만 주고,

쓰기 권한은 필요한 경우에만 특정 디렉터리나 파일에 부여하는 것이 안전하다.

이 영상은 위에서 설명한 내용과 관련된 영상이다.

마무리

docker-compose exec app cat sample.php

이 명령어로 /var/www/html 내의 sample.php 파일의 내용을 확인한다.

/src에서 수정한 내용이 /var/www/html에서 반영되고 있는 것을 확인할 수 있을 거다.

rm src/sample.php

확인이 끝났다면 파일을 삭제하자.

다음 포스트

docker로 Laravel 개발 환경 구축 2편 (NGiNX 컨테이너 생성)

Docker Laravel 개발 환경 구축 2편에서는 NGiNX 컨테이너를 생성합니다. docker-compose.yml에 NGiNX 서비스를 추가하고, default.conf를 설정하여 NGiNX와 php 컨테이너를 연동합니다.

이 글이 도움이 됐거나 유익했다면 스크롤을 조금만 더 내려서 댓글을 남겨주세요. (비로그인도 가능합니다!)
응원이나 피드백이 담긴 댓글은 제가 계속 블로그를 해나갈 수 있는 원동력이 됩니다. 😊

지인에게 보여주고 싶은 글이었다면 URL을 복사해서 메신저나 소셜 미디어에 공유해 주세요.