Laravel Sail

번역일: 2026년 6월 25일

Laravel Sail

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

소개

Laravel Sail은 Laravel의 기본 Docker 개발 환경을 손쉽게 다룰 수 있는 경량 CLI 도구입니다. Docker 경험이 없어도 PHP, MySQL, Redis를 갖춘 Laravel 개발 환경을 빠르게 구축할 수 있습니다.

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

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

설치 및 설정

새 Laravel 애플리케이션을 생성하면 Sail이 자동으로 포함되므로 바로 사용할 수 있습니다.

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

이미 존재하는 Laravel 프로젝트에 Sail을 추가하려면 Composer로 패키지를 설치합니다. 이 단계는 로컬 환경에 Composer가 설치되어 있다는 것을 전제로 합니다.

composer require laravel/sail --dev

설치 후 sail:install Artisan 명령어를 실행합니다. 이 명령어는 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 이미지 재빌드

이미지 내 패키지나 소프트웨어를 최신 상태로 유지하려면 아래 절차로 이미지를 완전히 재빌드합니다.

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 up

Sail 시작 및 중지

compose.yaml 파일에는 Laravel 개발에 필요한 여러 Docker 컨테이너가 정의되어 있습니다. laravel.test 컨테이너가 애플리케이션을 실제로 서빙하는 주 컨테이너입니다.

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

compose.yaml에 정의된 모든 컨테이너를 시작하려면 up 명령어를 실행합니다.

sail up

백그라운드(detached 모드)로 실행하려면 -d 옵션을 사용합니다.

sail up -d

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

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

sail stop

명령어 실행

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

Laravel 공식 문서에서는 Sail을 명시하지 않고 Composer, Artisan, Node/NPM 명령어를 설명하는 경우가 많습니다. 이는 해당 도구가 로컬에 설치되어 있다는 전제입니다. Sail을 개발 환경으로 사용한다면 아래처럼 모든 명령어 앞에 sail을 붙여 실행하세요.

# 로컬에서 Artisan 명령어 실행php artisan queue:work# Sail(컨테이너) 안에서 Artisan 명령어 실행sail artisan queue:work

PHP 명령어 실행

php 명령어로 PHP를 직접 실행할 수 있습니다. 사용되는 PHP 버전은 애플리케이션에 설정된 버전을 따릅니다. 사용 가능한 PHP 버전은 PHP 버전 문서를 참고하세요.

sail php --versionsail php script.php

Composer 명령어 실행

Sail의 애플리케이션 컨테이너에는 Composer가 포함되어 있으므로 composer 명령어를 바로 사용할 수 있습니다.

sail composer require laravel/sanctum

Artisan 명령어 실행

artisan 명령어로 Laravel Artisan 명령어를 실행합니다.

sail artisan queue:work

Node / NPM 명령어 실행

node 및 npm 명령어로 Node.js와 NPM을 사용할 수 있습니다.

sail node --versionsail npm run dev

NPM 대신 Yarn을 사용할 수도 있습니다.

sail yarn

데이터베이스 사용

MySQL

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

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

컨테이너가 시작된 후 .env 파일의 DB_HOST를 mysql로 설정하면 애플리케이션에서 MySQL에 연결할 수 있습니다.

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

MongoDB

Sail 설치 시 MongoDB를 선택했다면, compose.yaml에 MongoDB Atlas Local 컨테이너 항목이 추가됩니다. 이 컨테이너는 Search Indexes 같은 Atlas 기능도 제공합니다. Docker 볼륨을 사용하므로 컨테이너 재시작 후에도 데이터가 유지됩니다.

컨테이너 시작 후 .env 파일의 MONGODB_URI를 mongodb://mongodb:27017로 설정하면 연결할 수 있습니다. 기본적으로 인증은 비활성화되어 있으며, 인증을 활성화하려면 mongodb 컨테이너 시작 전에 아래와 같이 설정합니다.

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

Laravel과 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 볼륨을 사용하므로 데이터가 영구적으로 유지됩니다. .env 파일의 REDIS_HOST를 valkey로 설정하면 애플리케이션에서 연결할 수 있습니다.

로컬에서 Valkey에 접근하려면 TablePlus 등의 GUI 클라이언트를 사용합니다. 기본 접속 포트는 localhost:6379입니다.

Meilisearch

Sail 설치 시 Meilisearch를 선택했다면, compose.yaml에 해당 항목이 추가됩니다. Meilisearch는 Laravel Scout와 통합되는 고성능 검색 엔진입니다. 컨테이너 시작 후 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

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

파일 스토리지

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

애플리케이션의 filesystems 설정 파일에는 이미 s3 디스크 설정이 포함되어 있습니다. 환경 변수만 변경하면 Amazon S3 대신 RustFS를 바로 사용할 수 있습니다. 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는 내부적으로 아래 Artisan 명령어와 동일합니다.

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

그 다음, compose.yaml의 laravel.test 서비스에 depends_on 항목으로 selenium을 추가합니다.

depends_on:
    - mysql
    - redis
    - selenium

이제 Sail을 시작하고 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

이메일 미리보기

Sail의 기본 compose.yaml에는 Mailpit 서비스가 포함되어 있습니다. Mailpit은 로컬 개발 중 애플리케이션에서 발송되는 이메일을 가로채고, 브라우저에서 이메일 내용을 바로 확인할 수 있는 웹 UI를 제공합니다. Sail에서 Mailpit의 기본 호스트는 mailpit이며 포트 1025를 통해 연결됩니다.

MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null

Sail 실행 중에는 브라우저에서 http://localhost:8025 로 Mailpit 웹 UI에 접근할 수 있습니다.

컨테이너 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

Node 버전

Sail은 기본적으로 Node 22를 설치합니다. 이미지 빌드 시 설치할 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이 발급되며, 이 URL로 외부에서 애플리케이션에 접근할 수 있습니다.

sail share

share 명령어로 사이트를 공유할 때는 bootstrap/app.php에서 trustProxies 미들웨어 메서드로 신뢰할 프록시를 설정해야 합니다. 설정하지 않으면 url이나 route 같은 URL 생성 헬퍼가 올바른 HTTP 호스트를 인식하지 못합니다.

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

공유할 서브도메인을 직접 지정하려면 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

Laravel Sail

소개

설치 및 설정

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

서비스 추가하기

Devcontainer 사용하기

Sail 이미지 재빌드

셸 별칭 설정

Sail 시작 및 중지

명령어 실행

PHP 명령어 실행

Composer 명령어 실행

Artisan 명령어 실행

Node / NPM 명령어 실행

데이터베이스 사용

MySQL

MongoDB

Redis

Valkey

Meilisearch

Typesense

파일 스토리지

테스트 실행

Laravel Dusk

Apple Silicon에서 Selenium 사용

이메일 미리보기

컨테이너 CLI

PHP 버전

Node 버전

사이트 공유

Xdebug로 디버깅

Linux에서 호스트 IP 설정