Laravel Sail

번역일: 2026년 6월 27일

Laravel Sail

소개
설치 및 설정
- 기존 애플리케이션에 Sail 설치하기
- 셸 별칭 설정하기
Sail 시작 및 종료
명령어 실행
데이터베이스 사용
- MySQL
- Redis
- Meilisearch
- Typesense
파일 스토리지
테스트 실행
- Laravel Dusk
이메일 미리보기
컨테이너 CLI
PHP 버전
Node 버전
사이트 공유
Xdebug로 디버깅하기
- Xdebug CLI 사용
- Xdebug 브라우저 사용
커스터마이징

소개

Laravel Sail은 Laravel의 기본 Docker 개발 환경을 손쉽게 다룰 수 있는 경량 커맨드라인 인터페이스입니다. Docker에 대한 사전 지식 없이도 PHP, MySQL, Redis를 갖춘 Laravel 개발 환경을 바로 구성할 수 있어 입문자에게 특히 유용합니다.

Sail의 핵심은 프로젝트 루트에 위치한 docker-compose.yml 파일과 sail 스크립트입니다. sail 스크립트는 docker-compose.yml에 정의된 Docker 컨테이너를 편리하게 조작할 수 있는 CLI 명령어들을 제공합니다.

Laravel Sail은 macOS, Linux, Windows(WSL2 경유)를 지원합니다.

설치 및 설정

새로 생성한 Laravel 애플리케이션에는 Sail이 자동으로 포함되어 있으므로 별도 설치 없이 바로 사용할 수 있습니다. 새 Laravel 애플리케이션을 만드는 방법은 각 운영체제별 설치 문서를 참고하세요. 설치 과정에서 애플리케이션에서 사용할 Sail 지원 서비스를 선택할 수 있습니다.

기존 애플리케이션에 Sail 설치하기

이미 운영 중인 Laravel 프로젝트에 Sail을 추가하려면 Composer로 설치하면 됩니다. 단, 로컬 개발 환경에 Composer가 설치되어 있어야 합니다.

composer require laravel/sail --dev

설치가 완료되면 sail:install Artisan 명령어를 실행하세요. 이 명령어는 docker-compose.yml 파일을 프로젝트 루트에 생성하고, Docker 서비스 연결에 필요한 환경 변수를 .env 파일에 추가합니다.

php artisan sail:install

이제 Sail을 시작할 수 있습니다.

./vendor/bin/sail up

WARNING

Linux에서 Docker Desktop을 사용하는 경우, 다음 명령어로 default Docker 컨텍스트를 사용하도록 설정해야 합니다: docker context use default

서비스 추가하기

기존 Sail 설치에 새로운 서비스를 추가하려면 sail:add Artisan 명령어를 실행하세요.

php artisan sail:add

Devcontainer 사용하기

Devcontainer 환경에서 개발하고 싶다면 sail:install 명령어에 --devcontainer 옵션을 추가하세요. 이 옵션을 사용하면 프로젝트 루트에 .devcontainer/devcontainer.json 파일이 생성됩니다.

php artisan sail:install --devcontainer

셸 별칭 설정하기

기본적으로 Sail 명령어는 vendor/bin/sail 스크립트를 통해 실행합니다.

./vendor/bin/sail up

매번 vendor/bin/sail을 입력하는 번거로움을 줄이기 위해 셸 별칭을 설정하는 것을 권장합니다.

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

이 별칭을 영구적으로 사용하려면 ~/.zshrc 또는 ~/.bashrc 파일에 추가한 뒤 셸을 재시작하세요.

별칭 설정 후에는 sail만 입력해도 명령어를 실행할 수 있습니다. 이 문서의 나머지 예시는 모두 이 별칭이 설정되어 있다고 가정합니다.

sail up

Sail 시작 및 종료

docker-compose.yml 파일에는 Laravel 개발에 필요한 여러 Docker 컨테이너가 정의되어 있습니다. 각 컨테이너는 services 항목에 등록되며, laravel.test 컨테이너가 애플리케이션을 실제로 서빙하는 핵심 컨테이너입니다.

Sail을 시작하기 전에, 로컬 컴퓨터에서 실행 중인 다른 웹 서버나 데이터베이스가 없는지 확인하세요. 포트 충돌이 발생할 수 있습니다.

모든 Docker 컨테이너를 시작하려면 up 명령어를 실행하세요.

sail up

백그라운드에서 실행하려면 -d 옵션(detached 모드)을 사용하세요.

sail up -d

컨테이너가 시작되면 브라우저에서 http://localhost 로 프로젝트에 접근할 수 있습니다.

컨테이너를 중지하려면 Control + C를 누르거나, 백그라운드에서 실행 중인 경우 stop 명령어를 사용하세요.

sail stop

명령어 실행

Laravel Sail을 사용하면 애플리케이션이 Docker 컨테이너 안에서 실행되며 로컬 환경과 격리됩니다. Sail은 PHP, Artisan, Composer, Node/NPM 등 다양한 명령어를 컨테이너 내부에서 실행할 수 있는 편리한 방법을 제공합니다.

Laravel 공식 문서에서는 Composer, Artisan, Node/NPM 명령어 예시에 sail을 붙이지 않는 경우가 많습니다. 이는 해당 도구들이 로컬에 직접 설치되어 있다고 가정하기 때문입니다. Sail 환경을 사용하고 있다면 반드시 sail 명령어를 앞에 붙여서 실행해야 합니다.

# 로컬에서 직접 Artisan 명령어 실행 시...php artisan queue:work# Laravel Sail에서 Artisan 명령어 실행 시...sail artisan queue:work

PHP 명령어 실행

PHP 명령어는 php 커맨드로 실행합니다. 사용되는 PHP 버전은 애플리케이션에 설정된 버전을 따릅니다. 지원하는 PHP 버전에 대한 자세한 내용은 PHP 버전 문서를 참고하세요.

sail php --versionsail php script.php

Composer 명령어 실행

Composer 명령어는 composer 커맨드로 실행합니다. Sail 애플리케이션 컨테이너에는 Composer 2.x가 기본으로 포함되어 있습니다.

sail composer require laravel/sanctum

기존 애플리케이션의 Composer 의존성 설치

팀 프로젝트에서 저장소를 클론한 경우, Sail을 포함한 Composer 의존성이 아직 설치되어 있지 않을 수 있습니다. 이 경우 다음 명령어로 의존성을 먼저 설치할 수 있습니다. PHP와 Composer가 포함된 소형 Docker 컨테이너를 일회성으로 실행하는 방식입니다.

docker run --rm \    -u "$(id -u):$(id -g)" \    -v "$(pwd):/var/www/html" \    -w /var/www/html \    laravelsail/php83-composer:latest \    composer install --ignore-platform-reqs

laravelsail/phpXX-composer 이미지를 사용할 때는 프로젝트에서 사용할 PHP 버전(80, 81, 82, 83)과 일치하는 이미지를 선택하세요.

Artisan 명령어 실행

Artisan 명령어는 artisan 커맨드로 실행합니다.

sail artisan queue:work

Node / NPM 명령어 실행

Node 명령어는 node, NPM 명령어는 npm 커맨드로 실행합니다.

sail node --versionsail npm run dev

NPM 대신 Yarn을 사용하고 싶다면 다음과 같이 실행할 수 있습니다.

sail yarn

데이터베이스 사용

MySQL

docker-compose.yml 파일에는 MySQL 컨테이너 항목이 포함되어 있습니다. 이 컨테이너는 Docker 볼륨을 사용하므로 컨테이너를 중지하거나 재시작해도 데이터가 유지됩니다.

MySQL 컨테이너가 처음 시작될 때 두 개의 데이터베이스가 자동으로 생성됩니다. 하나는 DB_DATABASE 환경 변수에 지정한 이름의 개발용 데이터베이스이고, 다른 하나는 testing이라는 이름의 테스트 전용 데이터베이스입니다. 테스트 데이터베이스를 분리함으로써 테스트 실행이 개발 데이터에 영향을 주지 않습니다.

컨테이너가 실행 중일 때 .env 파일의 DB_HOST를 mysql로 설정하면 애플리케이션에서 MySQL에 접속할 수 있습니다.

로컬 머신에서 직접 MySQL에 접속하려면 TablePlus와 같은 GUI 데이터베이스 클라이언트를 사용할 수 있습니다. 기본적으로 MySQL은 localhost의 3306 포트로 접근 가능하며, 접속 정보는 .env 파일의 DB_USERNAME과 DB_PASSWORD 값을 따릅니다. root 사용자로 접속할 때의 비밀번호도 DB_PASSWORD 값과 동일합니다.

Redis

docker-compose.yml 파일에는 Redis 컨테이너 항목도 포함되어 있습니다. MySQL과 마찬가지로 Docker 볼륨을 사용하므로 컨테이너 재시작 후에도 데이터가 유지됩니다. .env 파일의 REDIS_HOST를 redis로 설정하면 애플리케이션에서 Redis에 접속할 수 있습니다.

로컬 머신에서 Redis에 직접 접속하려면 TablePlus 등의 GUI 클라이언트를 사용하세요. 기본적으로 Redis는 localhost의 6379 포트로 접근 가능합니다.

Meilisearch

Sail 설치 시 Meilisearch 서비스를 선택했다면 docker-compose.yml에 해당 항목이 추가됩니다. Meilisearch는 Laravel Scout와 호환되는 강력한 검색 엔진입니다. MEILISEARCH_HOST 환경 변수를 http://meilisearch:7700으로 설정하면 애플리케이션에서 Meilisearch에 접속할 수 있습니다.

로컬 머신에서는 http://localhost:7700으로 Meilisearch 웹 관리 패널에 접근할 수 있습니다.

Typesense

Sail 설치 시 Typesense 서비스를 선택했다면 docker-compose.yml에 해당 항목이 추가됩니다. Typesense는 Laravel Scout와 네이티브로 통합된 초고속 오픈소스 검색 엔진입니다. 다음 환경 변수를 설정하면 애플리케이션에서 Typesense에 접속할 수 있습니다.

TYPESENSE_HOST=typesense
TYPESENSE_PORT=8108
TYPESENSE_PROTOCOL=http
TYPESENSE_API_KEY=xyz

로컬 머신에서는 http://localhost:8108을 통해 Typesense API에 접근할 수 있습니다.

파일 스토리지

프로덕션 환경에서 Amazon S3를 파일 스토리지로 사용할 계획이라면, Sail 설치 시 MinIO 서비스를 함께 설치하는 것을 권장합니다. MinIO는 S3 호환 API를 제공하므로, 프로덕션 S3 버킷을 건드리지 않고도 Laravel의 s3 파일 스토리지 드라이버를 로컬에서 그대로 사용할 수 있습니다. MinIO를 선택하면 docker-compose.yml에 MinIO 설정이 자동으로 추가됩니다.

Laravel의 filesystems 설정 파일에는 기본적으로 s3 디스크 설정이 포함되어 있습니다. 환경 변수만 변경하면 Amazon S3 대신 MinIO를 사용할 수 있습니다. MinIO 사용 시 환경 변수는 다음과 같이 설정합니다.

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://minio:9000
AWS_USE_PATH_STYLE_ENDPOINT=true

MinIO 사용 시 Laravel Flysystem이 올바른 URL을 생성할 수 있도록 AWS_URL 환경 변수도 아래와 같이 설정해야 합니다. URL 경로에 버킷 이름이 포함되어야 합니다.

AWS_URL=http://localhost:9000/local

MinIO 콘솔은 http://localhost:8900에서 접근할 수 있으며 버킷을 생성할 수 있습니다. 기본 로그인 정보는 사용자명 sail, 비밀번호 password입니다.

WARNING

MinIO 사용 시 temporaryUrl 메서드를 통한 임시 스토리지 URL 생성은 지원되지 않습니다.

테스트 실행

Laravel은 강력한 테스트 기능을 기본으로 제공합니다. Sail의 test 명령어로 피처 테스트 및 유닛 테스트를 실행할 수 있으며, PHPUnit에서 지원하는 모든 CLI 옵션을 함께 사용할 수 있습니다.

sail testsail test --group orders

Sail의 test 명령어는 test Artisan 명령어와 동일하게 동작합니다.

sail artisan test

기본적으로 Sail은 테스트 전용 testing 데이터베이스를 별도로 생성하여, 테스트가 개발 데이터베이스에 영향을 주지 않도록 합니다. 기본 Laravel 설치에서는 phpunit.xml 파일이 다음과 같이 이 데이터베이스를 사용하도록 구성되어 있습니다.

<env name="DB_DATABASE" value="testing"/>

Laravel Dusk

Laravel Dusk는 표현력 있고 사용하기 쉬운 브라우저 자동화 및 테스트 API를 제공합니다. Sail을 사용하면 Selenium 등의 도구를 로컬에 별도 설치하지 않고도 Dusk 테스트를 실행할 수 있습니다.

먼저 docker-compose.yml 파일에서 Selenium 서비스의 주석을 해제하세요.

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

다음으로 laravel.test 서비스의 depends_on 항목에 selenium을 추가하세요.

depends_on:
    - mysql
    - redis
    - selenium

이제 Sail을 시작하고 dusk 명령어로 테스트를 실행할 수 있습니다.

sail dusk

Apple Silicon에서의 Selenium

Apple Silicon(M1/M2/M3 등) 칩을 사용하는 Mac에서는 selenium 서비스에 seleniarm/standalone-chromium 이미지를 사용해야 합니다.

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

이메일 미리보기

Laravel Sail의 기본 docker-compose.yml 파일에는 Mailpit 서비스가 포함되어 있습니다. Mailpit은 로컬 개발 중 애플리케이션이 발송하는 이메일을 가로채어 브라우저에서 미리볼 수 있는 편리한 웹 인터페이스를 제공합니다. 실제로 이메일이 발송되지 않으므로 개발 중 이메일 테스트에 안전하게 활용할 수 있습니다.

Sail 환경에서 Mailpit의 기본 호스트는 mailpit이며 포트 1025를 사용합니다.

MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null

Sail이 실행 중일 때 http://localhost:8025 에서 Mailpit 웹 인터페이스에 접근할 수 있습니다.

컨테이너 CLI

애플리케이션 컨테이너 내부에서 직접 작업해야 할 때는 shell 명령어로 Bash 세션을 시작할 수 있습니다. 파일을 확인하거나 설치된 서비스를 점검하고, 임의의 셸 명령어를 실행하는 데 유용합니다.

sail shellsail root-shell

Laravel Tinker 세션을 시작하려면 tinker 명령어를 사용하세요.

sail tinker

PHP 버전

Sail은 현재 PHP 8.3, 8.2, 8.1, 8.0을 지원합니다. 기본 PHP 버전은 8.3입니다. PHP 버전을 변경하려면 docker-compose.yml 파일에서 laravel.test 컨테이너의 build 항목을 수정하세요.

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

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

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

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

사용하는 PHP 버전에 맞게 image 이름도 함께 수정하는 것이 좋습니다.

image: sail-8.1/app

docker-compose.yml 파일을 수정한 후에는 컨테이너 이미지를 다시 빌드해야 합니다.

sail build --no-cachesail up

Node 버전

Sail은 기본적으로 Node 20을 설치합니다. 이미지 빌드 시 설치할 Node 버전을 변경하려면 docker-compose.yml 파일에서 laravel.test 서비스의 build.args 항목을 수정하세요.

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

docker-compose.yml 파일을 수정한 후에는 컨테이너 이미지를 다시 빌드해야 합니다.

sail build --no-cachesail up

동료에게 작업 중인 화면을 보여주거나 웹훅 연동을 테스트할 때처럼, 개발 중인 사이트를 외부에 일시적으로 공개해야 할 경우가 있습니다. 이때 share 명령어를 사용하면 됩니다. 명령어를 실행하면 랜덤한 laravel-sail.site URL이 발급되어 외부에서 접근할 수 있게 됩니다.

sail share

share 명령어로 사이트를 공유할 때는 TrustProxies 미들웨어에서 신뢰할 프록시를 설정해야 합니다. 그렇지 않으면 url, route 같은 URL 생성 헬퍼가 올바른 HTTP 호스트를 판단하지 못할 수 있습니다.

/**
 * 이 애플리케이션에서 신뢰할 프록시 목록
 *
 * @var array|string|null
 */
protected $proxies = '*';

공유 사이트의 서브도메인을 직접 지정하고 싶다면 subdomain 옵션을 사용하세요.

sail share --subdomain=my-sail-site

NOTE

share 명령어는 BeyondCode에서 만든 오픈소스 터널링 서비스 Expose를 기반으로 동작합니다.

Xdebug로 디버깅하기

Laravel Sail의 Docker 설정에는 PHP 디버거로 널리 사용되는 Xdebug 지원이 포함되어 있습니다. Xdebug를 활성화하려면 Sail을 시작하기 전에 .env 파일에 다음 변수를 추가하여 Xdebug 모드를 설정해야 합니다.

SAIL_XDEBUG_MODE=develop,debug,coverage

Linux 호스트 IP 설정

내부적으로 XDEBUG_CONFIG 환경 변수는 client_host=host.docker.internal로 정의되어 Mac과 Windows(WSL2) 환경에서는 자동으로 올바르게 설정됩니다. 단, Linux 환경에서는 Docker Engine 17.06.0+와 Compose 1.16.0+ 버전이 필요합니다. 이보다 낮은 버전을 사용 중이라면 다음과 같이 수동으로 환경 변수를 설정해야 합니다.

먼저 다음 명령어로 호스트 IP 주소를 확인하세요. <container-name>은 애플리케이션을 서빙하는 컨테이너 이름으로, 보통 _laravel.test_1로 끝납니다.

docker inspect -f {{range.NetworkSettings.Networks}}{{.Gateway}}{{end}} <container-name>

확인한 IP 주소를 .env 파일에 다음과 같이 설정하세요.

SAIL_XDEBUG_CONFIG="client_host=<host-ip-address>"

Xdebug CLI 사용

Artisan 명령어 실행 시 디버깅 세션을 시작하려면 sail debug 명령어를 사용하세요.

# Xdebug 없이 Artisan 명령어 실행...sail artisan migrate# Xdebug와 함께 Artisan 명령어 실행...sail debug migrate

Xdebug 브라우저 사용

브라우저를 통해 애플리케이션을 조작하면서 디버깅하려면 Xdebug 공식 문서에서 안내하는 방법에 따라 브라우저에서 Xdebug 세션을 시작하세요.

PhpStorm을 사용 중이라면 JetBrains의 제로 설정 디버깅 문서를 참고하세요.

WARNING

Laravel Sail은 artisan serve를 통해 애플리케이션을 서빙합니다. XDEBUG_CONFIG 및 XDEBUG_MODE 변수는 Laravel 8.53.0부터 지원됩니다. Laravel 8.52.0 이하 버전에서는 이 변수들이 지원되지 않아 디버그 연결이 정상적으로 이루어지지 않습니다.

커스터마이징

Sail은 결국 Docker이므로 거의 모든 것을 자유롭게 커스터마이징할 수 있습니다. Sail의 Dockerfile을 직접 수정하고 싶다면 sail:publish 명령어로 파일을 내보낼 수 있습니다.

sail artisan sail:publish

이 명령어를 실행하면 Laravel Sail이 사용하는 Dockerfile과 기타 설정 파일들이 프로젝트 루트의 docker 디렉터리에 생성됩니다. Sail 설정을 커스터마이징한 후에는 docker-compose.yml 파일에서 애플리케이션 컨테이너의 이미지 이름을 변경하는 것이 좋습니다. 한 머신에서 여러 Laravel 프로젝트를 Sail로 개발하는 경우, 이미지 이름이 겹치지 않도록 고유한 이름을 지정하는 것이 특히 중요합니다. 변경 후에는 build 명령어로 컨테이너 이미지를 다시 빌드하세요.

sail build --no-cache

Laravel Sail

소개

설치 및 설정

기존 애플리케이션에 Sail 설치하기

서비스 추가하기

Devcontainer 사용하기

셸 별칭 설정하기

Sail 시작 및 종료

명령어 실행

PHP 명령어 실행

Composer 명령어 실행

기존 애플리케이션의 Composer 의존성 설치

Artisan 명령어 실행

Node / NPM 명령어 실행

데이터베이스 사용

MySQL

Redis

Meilisearch

Typesense

파일 스토리지

테스트 실행

Laravel Dusk

Apple Silicon에서의 Selenium

이메일 미리보기

컨테이너 CLI

PHP 버전

Node 버전

사이트 공유

Xdebug로 디버깅하기

Linux 호스트 IP 설정

Xdebug CLI 사용

Xdebug 브라우저 사용

커스터마이징