Laravel Sail - Knowledge of Laravel

Sail이란

Laravel Sail은 Laravel의 Docker 개발 환경을 조작하기 위한 경량 커맨드라인 인터페이스입니다. PHP, MySQL, Redis를 사용한 Laravel 애플리케이션을 Docker의 사전 지식 없이도 구축할 수 있습니다. Sail의 중심에 있는 것은 프로젝트 루트에 놓이는 compose.yaml 파일과 sail 스크립트입니다. sail 스크립트는 compose.yaml로 정의된 Docker 컨테이너를 조작하기 위한 편리한 CLI 메서드를 제공합니다. Laravel Sail은 macOS, Linux, 그리고 Windows(WSL2 경유)에서 동작합니다.

Laravel 13에서 Sail은 표준 개발 환경이 아니게 되었습니다. 스켈레톤의 composer.json에서 laravel/sail이 삭제되고, 대신 composer setup 명령이 준비되어 있습니다. 표준은 로컬의 PHP + SQLite로 동작시키는 구성입니다.

composer setup
composer dev

Docker 컨테이너가 필요한 경우는, 계속해서 Sail을 설치해 사용할 수 있습니다.

Sail은 로컬 개발 전용 도구입니다. 프로덕션 환경에의 이용은 상정되어 있지 않습니다. 프로덕션 환경에서는 적절한 Docker / 클라우드 구성을 별도로 준비해 주세요.

설치

기존 프로젝트에의 설치

Composer로 패키지를 설치합니다.

Sail 패키지를 추가

composer require laravel/sail --dev

설정 파일을 발행

sail:install Artisan 명령을 실행합니다. 이 명령은 compose.yaml을 프로젝트 루트에 발행하고, .env에 필요한 환경 변수를 추가 기재합니다.

php artisan sail:install

대화 형식으로 서비스를 선택할 수 있습니다. MySQL, Redis, Mailpit 등을 선택해 주세요.

Sail을 기동

./vendor/bin/sail up

초회 기동 시는 Docker 이미지의 다운로드에 시간이 걸립니다. 기동 후는 http://localhost에서 애플리케이션에 접속할 수 있습니다.

Docker Desktop for Linux를 사용하고 있는 경우는 docker context use default를 실행해 default 컨텍스트를 사용해 주세요. 컨테이너 내에서 파일 퍼미션 에러가 발생한 경우는 SUPERVISOR_PHP_USER 환경 변수를 root로 설정해 주세요.

추가 서비스의 추가

기존 Sail 설치에 서비스를 추가하려면 sail:add 명령을 사용합니다.

php artisan sail:add

Devcontainer의 이용

Devcontainer 내에서 개발하고 싶은 경우는 --devcontainer 옵션을 사용합니다.

php artisan sail:install --devcontainer

설정

셸 에일리어스 설정

기본적으로 ./vendor/bin/sail을 매번 입력해야 합니다. 셸 에일리어스를 설정하면 sail이라고만 입력하면 되게 됩니다.

alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'

~/.zshrc 또는 ~/.bashrc에 추가 기재해 셸을 재기동해 주세요.

sail up

에일리어스를 설정한 후에는, 이 문서의 모든 명령 예에서 ./vendor/bin/sail 대신에 sail이라고 입력할 수 있습니다.

이미지의 재빌드

패키지를 최신 상태로 유지하고 싶은 경우는 이미지를 재빌드합니다.

docker compose down -v

sail build --no-cache

sail up

기동과 정지

compose.yaml에 정의된 모든 Docker 컨테이너를 기동하려면 up 명령을 사용합니다.

# 포어그라운드에서 기동
sail up

# 백그라운드에서 기동
sail up -d

정지하려면 stop 명령을 사용하거나, 포어그라운드에서 기동 중이라면 Ctrl + C를 누릅니다.

sail stop

기동 플로우

명령의 실행

Sail을 사용하는 경우, 애플리케이션은 Docker 컨테이너 내에서 동작합니다. PHP 명령, Artisan 명령, Composer 명령, Node / NPM 명령은 모두 sail 경유로 실행합니다.

Laravel 공식 문서에서 자주 보이는 php artisan, composer, npm 명령은, Sail 환경에서는 선두에 sail을 붙여 실행해 주세요.

PHP 명령

sail php --version

sail php script.php

Composer 명령

sail composer require laravel/sanctum

Artisan 명령

sail artisan migrate

sail artisan queue:work

Node / NPM 명령

sail node --version

sail npm run dev

# Yarn을 사용하는 경우
sail yarn

컨테이너 CLI (셸)

컨테이너 내에서 직접 Bash 세션을 열 수도 있습니다.

sail shell

# root 사용자로서 접속
sail root-shell

Tinker 세션을 열려면 다음 명령을 사용합니다.

sail tinker

서비스

Sail이 제공하는 서비스의 개요입니다. 설치 시에 sail:install에서 선택할 수 있습니다.

MySQL

기본으로 compose.yaml에 포함되어 있습니다. 데이터는 Docker Volume에서 영속화됩니다. 초회 기동 시에 앱용과 testing용의 2개의 데이터베이스가 자동 생성됩니다. .env의 DB_HOST를 mysql로 설정하면 앱에서 접속할 수 있습니다.

DB_HOST=mysql
DB_PORT=3306

로컬 머신에서 접속하려면 TablePlus 등의 GUI 도구를 사용해 주세요. 기본 포트는 3306입니다.

Redis

.env의 REDIS_HOST를 redis로 설정하면 앱에서 Redis에 접속할 수 있습니다.

REDIS_HOST=redis
REDIS_PORT=6379

Valkey

Redis의 대체로서 Valkey를 사용하는 경우는 REDIS_HOST를 valkey로 설정합니다.

Mailpit

로컬 개발 중의 메일 발송을 포착해 Web UI로 프리뷰할 수 있습니다.

MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null

Sail 기동 중은 http://localhost:8025에서 Mailpit의 Web UI에 접속할 수 있습니다.

Meilisearch / Typesense

Laravel Scout와 통합해 전문 검색을 시험할 수 있습니다.

Meilisearch: MEILISEARCH_HOST=http://meilisearch:7700
Typesense: TYPESENSE_HOST=typesense, TYPESENSE_PORT=8108 등

RustFS (S3 호환 스토리지)

프로덕션에서 Amazon S3를 사용할 예정이 있는 경우, 로컬에서 S3 호환 스토리지를 에뮬레이트할 수 있습니다.

FILESYSTEM_DISK=s3
AWS_ACCESS_KEY_ID=sail
AWS_SECRET_ACCESS_KEY=password
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=local
AWS_ENDPOINT=http://rustfs:9000
AWS_USE_PATH_STYLE_ENDPOINT=true

테스트의 실행

sail test

sail test --group orders

sail test는 내부적으로 sail artisan test와 동등합니다. 기본으로 전용의 testing 데이터베이스가 준비되기 때문에, 개발 데이터에 영향을 주지 않습니다.

Laravel Dusk

Sail을 사용하면 Selenium을 로컬에 설치하지 않고 Dusk의 브라우저 테스트를 실행할 수 있습니다. compose.yaml의 Selenium 서비스의 코멘트를 벗겨 주세요.

selenium:
    image: 'selenium/standalone-chrome'
    extra_hosts:
      - 'host.docker.internal:host-gateway'
    volumes:
        - '/dev/shm:/dev/shm'
    networks:
        - sail

Apple Silicon (M1/M2/M3)의 경우는 selenium/standalone-chromium 이미지를 사용해 주세요.

그 후 Dusk 테스트를 실행합니다.

sail dusk

PHP / Node 버전

PHP 버전의 변경

compose.yaml의 laravel.test 컨테이너의 build.context를 변경합니다.

# PHP 8.5 (기본값)
context: ./vendor/laravel/sail/runtimes/8.5

# PHP 8.4
context: ./vendor/laravel/sail/runtimes/8.4

# PHP 8.3
context: ./vendor/laravel/sail/runtimes/8.3

변경 후는 이미지를 재빌드해 주세요.

sail build --no-cache
sail up

추가 PHP 확장 기능

Sail의 런타임 이미지에는 일반적인 PHP 확장 기능이 포함되어 있습니다. 애플리케이션이 추가 확장 기능을 필요로 하는 경우, compose.yaml의 laravel.test 서비스에 PHP_EXTENSIONS 빌드 인수를 스페이스 구분으로 추가해 이미지 빌드 시에 설치할 수 있습니다.

build:
    args:
        WWWGROUP: '${WWWGROUP}'
        PHP_EXTENSIONS: 'gmp imagick'

compose.yaml을 업데이트한 후에는 컨테이너 이미지를 재빌드해 주세요.

sail build --no-cache
sail up

Node 버전의 변경

build:
    args:
        WWWGROUP: '${WWWGROUP}'
        NODE_VERSION: '20'

사이트의 공개 공유

동료의 프리뷰나 Webhook 테스트를 위해, 일시적으로 사이트를 외부 공개할 수 있습니다.

sail share

랜덤한 laravel-sail.site URL이 발행됩니다. URL 생성 헬퍼를 올바르게 동작시키기 위해, bootstrap/app.php에서 신뢰하는 프록시를 설정해 주세요.

->withMiddleware(function (Middleware $middleware): void {
    $middleware->trustProxies(at: '*');
})

서브도메인을 지정할 수도 있습니다.

sail share --subdomain=my-sail-site

Xdebug

활성화

우선 sail:publish로 설정 파일을 발행한 후, .env에 이하를 추가합니다.

SAIL_XDEBUG_MODE=develop,debug,coverage

발행된 php.ini 파일에 다음 설정이 포함되어 있는지 확인합니다.

[xdebug]
xdebug.mode=${XDEBUG_MODE}

변경 후는 이미지를 재빌드합니다.

sail build --no-cache

CLI 디버그

# Xdebug 없이 실행
sail artisan migrate

# Xdebug 있음으로 실행
sail debug migrate

브라우저 디버그

브라우저에서 디버그 세션을 시작하는 순서는 Xdebug 공식 문서를 참조해 주세요. PhpStorm을 사용하고 있는 경우는 Zero-configuration debugging의 설정이 편리합니다.

Sail은 artisan serve를 사용해 앱을 제공합니다. XDEBUG_CONFIG와 XDEBUG_MODE를 받는 것은 Laravel 8.53.0 이후입니다. 그것보다 오래된 버전에서는 디버그 접속이 기능하지 않습니다.

커스터마이즈

Sail의 Dockerfile이나 설정 파일을 커스터마이즈하려면 sail:publish 명령으로 발행합니다.

sail artisan sail:publish

발행 후는 docker/ 디렉터리에 Dockerfile이 배치됩니다. 변경 후는 컨테이너를 재빌드해 주세요.

sail build --no-cache

프로덕션 환경과의 차이

Sail은 로컬 개발 전용의 환경입니다. 프로덕션 환경에서의 사용은 상정되어 있지 않습니다. 프로덕션 환경에의 Docker 배포에는 Laravel Cloud, Forge, Ploi 등의 서비스나, 독자적인 Docker Compose / Kubernetes 구성을 검토해 주세요.

Sail과 프로덕션 환경의 주요 차이를 이하에 정리합니다.

항목	Sail (로컬)	프로덕션 환경
목적	개발·디버그	서비스 제공
Xdebug	활성화 가능	비활성화 권장
Mailpit	메일을 포착해 프리뷰	실제의 메일 서버
데이터 영속화	Docker Volume	매니지드 DB 등
성능	최적화 없음	최적화 필수

​Sail이란

​설치

​기존 프로젝트에의 설치

​추가 서비스의 추가

​Devcontainer의 이용

​설정

​셸 에일리어스 설정

​이미지의 재빌드

​기동과 정지

​기동 플로우

​명령의 실행

​PHP 명령

​Composer 명령

​Artisan 명령

​Node / NPM 명령

​컨테이너 CLI (셸)

​서비스

​MySQL

​Redis

​Valkey

​Mailpit

​Meilisearch / Typesense

​RustFS (S3 호환 스토리지)

​테스트의 실행

​Laravel Dusk

​PHP / Node 버전

​PHP 버전의 변경

​추가 PHP 확장 기능

​Node 버전의 변경

​사이트의 공개 공유

​Xdebug

​활성화

​CLI 디버그

​브라우저 디버그

​커스터마이즈

​프로덕션 환경과의 차이

Sail이란

설치

기존 프로젝트에의 설치

추가 서비스의 추가

Devcontainer의 이용

설정

셸 에일리어스 설정

이미지의 재빌드

기동과 정지

기동 플로우

명령의 실행

PHP 명령

Composer 명령

Artisan 명령

Node / NPM 명령

컨테이너 CLI (셸)

서비스

MySQL

Redis

Valkey

Mailpit

Meilisearch / Typesense

RustFS (S3 호환 스토리지)

테스트의 실행

Laravel Dusk

PHP / Node 버전

PHP 버전의 변경

추가 PHP 확장 기능

Node 버전의 변경

사이트의 공개 공유

Xdebug

활성화

CLI 디버그

브라우저 디버그

커스터마이즈

프로덕션 환경과의 차이