Laravel Sail

업데이트됨

번역일: 2026년 7월 28일

이 페이지는 원문이 업데이트되어 번역이 갱신되었습니다.

원문 수정: 2026년 7월 28일
번역 갱신: 2026년 7월 28일

Laravel Sail

소개
설치 및 설정
- Sail 이미지 재빌드
- 셸 별칭 설정
Sail 시작 및 중지
명령어 실행
데이터베이스 사용
- MySQL
- MongoDB
- Redis
- Valkey
- Meilisearch
- Typesense
파일 스토리지
테스트 실행
- Laravel Dusk
이메일 미리보기
컨테이너 CLI
PHP 버전
- 추가 PHP 익스텐션
Node 버전
사이트 공유
Xdebug로 디버깅
- Xdebug CLI 사용
- Xdebug 브라우저 사용
커스터마이징

소개

Laravel Sail은 Laravel의 기본 Docker 개발 환경을 손쉽게 다룰 수 있도록 만들어진 경량 커맨드라인 인터페이스입니다. Docker 경험이 전혀 없어도 PHP, MySQL, Redis를 갖춘 Laravel 개발 환경을 빠르게 구축할 수 있다는 점이 가장 큰 장점입니다.

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

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

설치 및 설정

Composer로 Sail을 설치합니다:

composer require laravel/sail --dev

설치 후 sail:install Artisan 명령어를 실행하면, Sail의 compose.yaml 파일이 프로젝트 루트에 생성되고 Docker 서비스 연결에 필요한 환경 변수들이 .env 파일에 자동으로 추가됩니다:

php artisan sail:install

마지막으로 Sail을 시작합니다:

./vendor/bin/sail up

WARNING

Linux에서 Docker Desktop을 사용하는 경우, docker context use default 명령어로 default Docker 컨텍스트를 사용하도록 설정하세요. 또한 컨테이너 내부에서 파일 권한 오류가 발생하면 SUPERVISOR_PHP_USER 환경 변수를 root로 설정해야 할 수 있습니다.

서비스 추가

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

php artisan sail:add

Devcontainer 사용

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

php artisan sail:install --devcontainer

Sail 이미지 재빌드

이미지에 포함된 패키지나 소프트웨어를 최신 상태로 유지하고 싶을 때는 Sail 이미지를 완전히 재빌드할 수 있습니다:

docker compose down -vsail build --no-cachesail up

셸 별칭 설정

기본적으로 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만 입력해서 실행할 수 있습니다. 이 문서의 나머지 예시는 이 별칭이 설정되어 있다고 가정합니다:

sail up

Sail 시작 및 중지

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

Sail을 시작하기 전에 로컬 컴퓨터에서 실행 중인 웹 서버나 데이터베이스가 없는지 확인하세요. 컨테이너를 시작하려면 다음 명령어를 실행합니다:

sail up

백그라운드에서 실행하고 싶다면 "detached" 모드를 사용하세요:

sail up -d

컨테이너가 시작되면 브라우저에서 http://localhost 로 애플리케이션에 접근할 수 있습니다.

컨테이너를 중지하려면 Control + C를 누르거나, 백그라운드 실행 중인 경우 다음 명령어를 사용합니다:

sail stop

명령어 실행

Laravel Sail을 사용하면 애플리케이션은 Docker 컨테이너 내부에서 실행되며, 로컬 컴퓨터와 격리된 환경에서 동작합니다. 그러나 Sail은 PHP, Artisan, Composer, Node/NPM 명령어를 컨테이너 내부에서 편리하게 실행할 수 있는 방법을 제공합니다.

Laravel 공식 문서에서는 Sail을 명시하지 않고 Composer, Artisan, Node/NPM 명령어를 설명하는 경우가 많습니다. 이는 해당 도구들이 로컬 컴퓨터에 설치되어 있다고 가정한 것입니다. 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가 기본으로 포함되어 있습니다:

sail composer require laravel/sanctum

Artisan 명령어 실행

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

sail artisan queue:work

Node / NPM 명령어 실행

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

sail node --versionsail npm run dev

NPM 대신 Yarn을 사용하고 싶다면 다음과 같이 실행합니다:

sail yarn

데이터베이스 사용

MySQL

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

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

컨테이너 실행 후 애플리케이션에서 MySQL에 연결하려면 .env 파일의 DB_HOST 값을 mysql로 설정하세요.

로컬 컴퓨터에서 MySQL에 직접 접속하려면 TablePlus와 같은 GUI 데이터베이스 도구를 사용할 수 있습니다. 기본적으로 localhost의 3306 포트로 접속 가능하며, 인증 정보는 DB_USERNAME과 DB_PASSWORD 환경 변수를 사용합니다. root 계정의 비밀번호도 DB_PASSWORD 값과 동일합니다.

MongoDB

Sail 설치 시 MongoDB 서비스를 선택했다면, compose.yaml에 MongoDB Atlas Local 컨테이너 항목이 추가됩니다. 이 컨테이너는 검색 인덱스 등 Atlas 기능을 포함한 MongoDB 문서 데이터베이스를 제공합니다. 데이터는 Docker 볼륨을 통해 컨테이너 재시작 후에도 유지됩니다.

컨테이너 실행 후 애플리케이션에서 MongoDB에 연결하려면 .env 파일의 MONGODB_URI를 mongodb://mongodb:27017로 설정하세요. 기본적으로 인증은 비활성화되어 있으며, 인증을 활성화하려면 mongodb 컨테이너 시작 전에 다음 환경 변수를 설정하세요:

MONGODB_USERNAME=user
MONGODB_PASSWORD=laravel
MONGODB_URI=mongodb://${MONGODB_USERNAME}:${MONGODB_PASSWORD}@mongodb:27017

애플리케이션에서 MongoDB를 원활하게 사용하려면 MongoDB 공식 패키지를 설치하는 것을 권장합니다.

로컬에서 MongoDB에 직접 접속할 때는 Compass와 같은 GUI 도구를 사용하세요. 기본적으로 localhost의 27017 포트로 접속 가능합니다.

Redis

compose.yaml 파일에는 Redis 컨테이너 항목도 포함되어 있습니다. Docker 볼륨을 사용하므로 컨테이너를 재시작해도 데이터가 유지됩니다. 컨테이너 실행 후 .env 파일의 REDIS_HOST를 redis로 설정하면 애플리케이션에서 Redis에 연결할 수 있습니다.

로컬에서 Redis에 직접 접속할 때는 TablePlus 등의 GUI 도구를 사용하세요. 기본적으로 localhost의 6379 포트로 접속 가능합니다.

Valkey

Sail 설치 시 Valkey 서비스를 선택했다면 compose.yaml에 Valkey 컨테이너 항목이 추가됩니다. Docker 볼륨을 사용하므로 컨테이너를 재시작해도 데이터가 유지됩니다. 애플리케이션에서 Valkey에 연결하려면 .env 파일의 REDIS_HOST를 valkey로 설정하세요.

로컬에서 Valkey에 직접 접속할 때는 TablePlus 등의 GUI 도구를 사용하세요. 기본적으로 localhost의 6379 포트로 접속 가능합니다.

Meilisearch

Sail 설치 시 Meilisearch 서비스를 선택했다면 compose.yaml에 해당 항목이 추가됩니다. Meilisearch는 Laravel Scout와 통합되는 강력한 검색 엔진입니다. 컨테이너 실행 후 .env 파일의 MEILISEARCH_HOST를 http://meilisearch:7700으로 설정하세요.

로컬 브라우저에서 http://localhost:7700으로 접속하면 Meilisearch 웹 관리 패널을 사용할 수 있습니다.

Typesense

Sail 설치 시 Typesense 서비스를 선택했다면 compose.yaml에 해당 항목이 추가됩니다. Typesense는 Laravel Scout와 네이티브로 통합되는 오픈소스 고속 검색 엔진입니다. 컨테이너 실행 후 다음 환경 변수를 설정하세요:

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

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

파일 스토리지

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

애플리케이션의 filesystems 설정 파일에는 이미 s3 디스크 설정이 포함되어 있습니다. 관련 환경 변수만 변경하면 Amazon S3뿐만 아니라 RustFS 같은 S3 호환 스토리지도 동일한 드라이버로 사용할 수 있습니다. RustFS 사용 시 환경 변수는 다음과 같이 설정합니다:

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

테스트 실행

Laravel은 강력한 테스트 지원을 기본 제공합니다. Sail의 test 명령어로 기능 테스트 및 단위 테스트를 실행할 수 있으며, Pest / PHPUnit이 지원하는 모든 CLI 옵션을 그대로 전달할 수 있습니다:

sail testsail test --group orders

sail test 명령어는 sail artisan test와 동일하게 동작합니다:

sail artisan test

Sail은 기본적으로 전용 testing 데이터베이스를 생성해 테스트가 개발 데이터베이스에 영향을 주지 않도록 합니다. 기본 Laravel 설치 시 phpunit.xml도 이 데이터베이스를 사용하도록 자동으로 설정됩니다:

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

Laravel Dusk

Laravel Dusk는 직관적이고 사용하기 쉬운 브라우저 자동화 및 테스트 API를 제공합니다. 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

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

depends_on:
    - mysql
    - redis
    - selenium

이제 Sail을 시작한 후 dusk 명령어로 Dusk 테스트를 실행할 수 있습니다:

sail dusk

Apple Silicon에서 Selenium 사용

Apple Silicon(M 시리즈 칩) 환경에서는 selenium 서비스 이미지를 selenium/standalone-chromium으로 교체해야 합니다:

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

이메일 미리보기

Laravel Sail의 기본 compose.yaml에는 Mailpit 서비스가 포함되어 있습니다. Mailpit은 로컬 개발 중 애플리케이션이 발송하는 이메일을 가로채서 브라우저에서 미리볼 수 있게 해주는 도구입니다. Sail 사용 시 Mailpit의 기본 호스트는 mailpit이며 1025 포트를 사용합니다:

MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null

Sail이 실행 중일 때 브라우저에서 http://localhost:8025 로 접속하면 Mailpit 웹 인터페이스를 사용할 수 있습니다.

컨테이너 CLI

컨테이너 내부에서 직접 Bash 세션을 시작하고 싶을 때는 shell 명령어를 사용합니다. 파일 구조 확인, 설치된 서비스 점검, 또는 임의의 셸 명령어를 직접 실행할 때 유용합니다:

sail shellsail root-shell

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

sail tinker

PHP 버전

Sail은 현재 PHP 8.5, 8.4, 8.3, 8.2, 8.1, 8.0을 지원합니다. 기본 PHP 버전은 8.5입니다. PHP 버전을 변경하려면 compose.yaml 파일의 laravel.test 컨테이너 build 정의를 수정하세요:

# 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

# 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 이름도 함께 변경하는 것을 권장합니다. 이 항목도 compose.yaml에 있습니다:

image: sail-8.2/app

compose.yaml 수정 후에는 컨테이너 이미지를 재빌드해야 합니다:

sail build --no-cachesail up

추가 PHP 익스텐션

Sail의 런타임 이미지에는 일반적으로 많이 사용되는 PHP 익스텐션이 기본으로 포함되어 있습니다. 추가 익스텐션이 필요한 경우, compose.yaml의 laravel.test 서비스에 PHP_EXTENSIONS 빌드 인수를 공백으로 구분하여 추가하세요:

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

compose.yaml 수정 후에는 컨테이너 이미지를 재빌드해야 합니다.

Node 버전

Sail은 기본적으로 Node 24를 설치합니다. Node 버전을 변경하려면 compose.yaml의 laravel.test 서비스 build.args를 수정하세요:

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

compose.yaml 수정 후에는 컨테이너 이미지를 재빌드해야 합니다:

sail build --no-cachesail up

동료에게 작업 중인 사이트를 미리 보여주거나 웹훅 연동을 테스트할 때처럼 로컬 사이트를 외부에 공개해야 할 경우 share 명령어를 사용하세요. 실행하면 무작위로 생성된 laravel-sail.site URL이 발급되어 외부에서 애플리케이션에 접근할 수 있습니다:

sail share

share 명령어를 사용할 때는 bootstrap/app.php에서 trustProxies 미들웨어 메서드를 설정해 신뢰할 수 있는 프록시를 지정해야 합니다. 그렇지 않으면 url, route 등의 URL 생성 헬퍼가 올바른 HTTP 호스트를 판단하지 못합니다:

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

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

sail share --subdomain=my-sail-site

NOTE

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

Xdebug로 디버깅

Laravel Sail의 Docker 설정에는 PHP 디버거인 Xdebug가 포함되어 있습니다. Xdebug를 활성화하려면 먼저 Sail 설정을 퍼블리시한 후, .env 파일에 다음 변수를 추가하세요:

SAIL_XDEBUG_MODE=develop,debug,coverage

그다음, 퍼블리시된 php.ini 파일에 아래 설정이 있는지 확인하세요. 이 설정이 있어야 지정한 모드로 Xdebug가 활성화됩니다:

[xdebug]
xdebug.mode=${XDEBUG_MODE}

php.ini 파일을 수정한 후에는 반드시 Docker 이미지를 재빌드해야 변경 사항이 반영됩니다:

sail build --no-cache

Linux 호스트 IP 설정

내부적으로 XDEBUG_CONFIG 환경 변수는 client_host=host.docker.internal로 설정되어 있어 macOS와 Windows(WSL2)에서는 별도 설정 없이 Xdebug가 정상 동작합니다. Linux에서 Docker 20.10 이상을 사용하는 경우에도 host.docker.internal이 지원되므로 추가 설정이 필요하지 않습니다.

Docker 20.10 미만 버전을 Linux에서 사용하는 경우 host.docker.internal이 지원되지 않으므로 수동으로 호스트 IP를 지정해야 합니다. compose.yaml에서 커스텀 네트워크를 정의해 컨테이너에 고정 IP를 할당하세요:

networks:
  custom_network:
    ipam:
      config:
        - subnet: 172.20.0.0/16

services:
  laravel.test:
    networks:
      custom_network:
        ipv4_address: 172.20.0.2

고정 IP 설정 후 .env 파일에 SAIL_XDEBUG_CONFIG 변수를 추가하세요:

SAIL_XDEBUG_CONFIG="client_host=172.20.0.2"

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 이상에서만 지원됩니다. 8.52.0 이하 버전에서는 이 변수들이 인식되지 않아 디버그 연결이 동작하지 않습니다.

커스터마이징

Sail은 결국 Docker이므로 거의 모든 것을 자유롭게 커스터마이징할 수 있습니다. Sail의 Dockerfile을 프로젝트에 퍼블리시하려면 다음 명령어를 실행하세요:

sail artisan sail:publish

이 명령어를 실행하면 Laravel Sail이 사용하는 Dockerfile 및 기타 설정 파일들이 프로젝트 루트의 docker 디렉터리에 생성됩니다. Sail 설정을 커스터마이징한 후에는 compose.yaml에서 애플리케이션 컨테이너의 이미지 이름을 변경하는 것을 권장합니다. 특히 하나의 머신에서 여러 Laravel 애플리케이션을 Sail로 개발하는 경우, 각 애플리케이션 이미지에 고유한 이름을 부여해야 충돌을 방지할 수 있습니다. 변경 후에는 build 명령어로 이미지를 재빌드하세요:

sail build --no-cache

Laravel Sail

소개

설치 및 설정

서비스 추가

Devcontainer 사용

Sail 이미지 재빌드

셸 별칭 설정

Sail 시작 및 중지

명령어 실행

PHP 명령어 실행

Composer 명령어 실행

Artisan 명령어 실행

Node / NPM 명령어 실행

데이터베이스 사용

MySQL

MongoDB

Redis

Valkey

Meilisearch

Typesense

파일 스토리지

테스트 실행

Laravel Dusk

Apple Silicon에서 Selenium 사용

이메일 미리보기

컨테이너 CLI

PHP 버전

추가 PHP 익스텐션

Node 버전

사이트 공유

Xdebug로 디버깅

Linux 호스트 IP 설정

Xdebug CLI 사용

Xdebug 브라우저 사용

커스터마이징