Laravel Sail

번역일: 2026년 6월 20일

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의 핵심은 프로젝트 루트에 위치한 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 이미지 재빌드하기

이미지에 포함된 패키지나 소프트웨어를 최신 상태로 유지하려면 이미지를 완전히 재빌드해야 할 때가 있습니다. build 명령어로 재빌드할 수 있습니다.

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 시작 및 종료

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

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

sail up

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

sail up -d

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

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

sail stop

명령어 실행하기

Laravel 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 명령어 실행

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

sail composer require laravel/sanctum

기존 프로젝트의 Composer 의존성 설치

팀 프로젝트에서 저장소를 클론한 경우, Sail을 포함한 Composer 의존성이 아직 설치되지 않은 상태일 수 있습니다. 이럴 때는 로컬에 PHP나 Composer가 없어도 아래 명령어로 의존성을 설치할 수 있습니다. 이 명령어는 PHP와 Composer가 포함된 소형 Docker 컨테이너를 이용합니다.

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

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

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 데이터베이스 관리 도구를 사용할 수 있습니다. 기본 접속 정보는 다음과 같습니다.

호스트: localhost
포트: 3306
사용자명: DB_USERNAME 환경 변수 값
비밀번호: DB_PASSWORD 환경 변수 값
root 사용자로도 접속 가능하며, 비밀번호는 DB_PASSWORD 값과 동일합니다.

MongoDB

Sail 설치 시 MongoDB를 선택했다면, docker-compose.yml 파일에 MongoDB Atlas Local 컨테이너 항목이 추가됩니다. 이 컨테이너는 검색 인덱스와 같은 Atlas 기능을 제공하며, Docker 볼륨을 사용해 데이터를 영속적으로 보존합니다.

컨테이너가 실행되면 .env 파일의 MONGODB_URI를 아래와 같이 설정하여 연결합니다.

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를 사용할 수 있습니다. 기본 접속 포트는 27017입니다.

Redis

docker-compose.yml 파일에는 Redis 컨테이너 항목도 포함되어 있습니다. Docker 볼륨을 사용하므로 컨테이너를 재시작해도 데이터가 유지됩니다. 컨테이너가 실행되면 .env 파일의 REDIS_HOST를 redis로 설정하여 연결합니다.

로컬 머신에서 Redis에 접속하려면 TablePlus 등의 도구를 사용할 수 있습니다. 기본 접속 포트는 6379입니다.

Valkey

Sail 설치 시 Valkey를 선택했다면, docker-compose.yml 파일에 Valkey 컨테이너 항목이 추가됩니다. Docker 볼륨을 사용하므로 데이터가 영속적으로 보존됩니다. .env 파일의 REDIS_HOST를 valkey로 설정하여 연결합니다.

로컬 머신에서 접속하려면 TablePlus 등의 도구를 사용할 수 있으며, 기본 포트는 6379입니다.

Meilisearch

Sail 설치 시 Meilisearch를 선택했다면, docker-compose.yml 파일에 해당 컨테이너 항목이 추가됩니다. Meilisearch는 Laravel Scout와 연동되는 강력한 검색 엔진입니다. 컨테이너가 실행되면 MEILISEARCH_HOST 환경 변수를 http://meilisearch:7700으로 설정하여 연결합니다.

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

Typesense

Sail 설치 시 Typesense를 선택했다면, docker-compose.yml 파일에 해당 컨테이너 항목이 추가됩니다. Typesense는 Laravel Scout와 기본 통합을 제공하는 오픈소스 고속 검색 엔진입니다. 아래 환경 변수를 설정하여 연결합니다.

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

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

파일 스토리지

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

config/filesystems.php에는 이미 s3 디스크 설정이 포함되어 있습니다. MinIO를 사용하려면 .env 파일의 환경 변수를 아래와 같이 수정하세요.

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 명령어로 기능 테스트 및 단위 테스트를 실행할 수 있으며, 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 테스트를 실행할 수 있습니다. 시작하려면 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 명령어로 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의 기본 docker-compose.yml 파일에는 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.4, 8.3, 8.2, 8.1, 8.0을 지원하며, 기본값은 PHP 8.4입니다. PHP 버전을 변경하려면 docker-compose.yml 파일의 laravel.test 컨테이너 build 항목을 수정하세요.

# 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 이름도 함께 수정하는 것이 좋습니다.

image: sail-8.2/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'

수정 후 컨테이너 이미지를 재빌드합니다.

sail build --no-cachesail up

동료에게 작업 중인 화면을 보여주거나 웹훅 연동을 테스트해야 할 때, share 명령어로 외부에서 접근 가능한 임시 URL을 생성할 수 있습니다.

sail share

명령어를 실행하면 laravel-sail.site 형태의 임시 URL이 발급됩니다.

share 명령어를 사용할 때는 애플리케이션이 프록시 뒤에서 동작하므로, bootstrap/app.php 파일에서 trustProxies 미들웨어 설정을 추가해야 합니다. 그렇지 않으면 url, route 같은 URL 생성 헬퍼가 올바른 HTTP 호스트를 인식하지 못합니다.

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

공유 사이트의 서브도메인을

Laravel Sail

소개

설치 및 설정

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

서비스 추가하기

Devcontainer 사용하기

Sail 이미지 재빌드하기

셸 별칭 설정하기

Sail 시작 및 종료

명령어 실행하기

PHP 명령어 실행

Composer 명령어 실행

기존 프로젝트의 Composer 의존성 설치

Artisan 명령어 실행

Node / NPM 명령어 실행

데이터베이스 사용하기

MySQL

MongoDB

Redis

Valkey

Meilisearch

Typesense

파일 스토리지

테스트 실행하기

Laravel Dusk

Apple Silicon에서 Selenium 사용하기

이메일 미리보기

컨테이너 CLI

PHP 버전

Node 버전

사이트 공유하기