> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Laravel Sail

> Laravel Sail을 사용해 Docker 기반의 로컬 개발 환경을 제로 컨피그로 구축하는 방법을 설명합니다.

## Sail이란

[Laravel Sail](https://github.com/laravel/sail)은 Laravel의 Docker 개발 환경을 조작하기 위한 경량 커맨드라인 인터페이스입니다.
PHP, MySQL, Redis를 사용한 Laravel 애플리케이션을 Docker의 사전 지식 없이도 구축할 수 있습니다.

Sail의 중심에 있는 것은 프로젝트 루트에 놓이는 `compose.yaml` 파일과 `sail` 스크립트입니다.
`sail` 스크립트는 `compose.yaml`로 정의된 Docker 컨테이너를 조작하기 위한 편리한 CLI 메서드를 제공합니다.

Laravel Sail은 macOS, Linux, 그리고 Windows([WSL2](https://docs.microsoft.com/en-us/windows/wsl/about) 경유)에서 동작합니다.

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

  ```shell theme={null}
  composer setup
  composer dev
  ```

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

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

***

## 설치

### 기존 프로젝트에의 설치

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

<Steps>
  <Step title="Sail 패키지를 추가">
    ```shell theme={null}
    composer require laravel/sail --dev
    ```
  </Step>

  <Step title="설정 파일을 발행">
    `sail:install` Artisan 명령을 실행합니다.
    이 명령은 `compose.yaml`을 프로젝트 루트에 발행하고, `.env`에 필요한 환경 변수를 추가 기재합니다.

    ```shell theme={null}
    php artisan sail:install
    ```

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

  <Step title="Sail을 기동">
    ```shell theme={null}
    ./vendor/bin/sail up
    ```

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

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

### 추가 서비스의 추가

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

```shell theme={null}
php artisan sail:add
```

### Devcontainer의 이용

[Devcontainer](https://code.visualstudio.com/docs/remote/containers) 내에서 개발하고 싶은 경우는 `--devcontainer` 옵션을 사용합니다.

```shell theme={null}
php artisan sail:install --devcontainer
```

***

## 설정

### 셸 에일리어스 설정

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

```shell theme={null}
alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'
```

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

```shell theme={null}
sail up
```

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

### 이미지의 재빌드

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

```shell theme={null}
docker compose down -v

sail build --no-cache

sail up
```

***

## 기동과 정지

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

```shell theme={null}
# 포어그라운드에서 기동
sail up

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

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

```shell theme={null}
sail stop
```

### 기동 플로우

```mermaid theme={null}
flowchart TD
    A["sail up을 실행"] --> B{"Docker 이미지가<br>존재하는가?"}
    B -- 아니오 --> C["이미지를 빌드/<br>다운로드"]
    C --> D["컨테이너를 기동"]
    B -- 예 --> D
    D --> E["laravel.test 컨테이너<br>(앱) 기동"]
    D --> F["mysql 컨테이너 기동"]
    D --> G["redis 컨테이너 기동"]
    D --> H["mailpit 컨테이너 기동"]
    E --> I["http://localhost에서 접속 가능"]
```

***

## 명령의 실행

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

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

### PHP 명령

```shell theme={null}
sail php --version

sail php script.php
```

### Composer 명령

```shell theme={null}
sail composer require laravel/sanctum
```

### Artisan 명령

```shell theme={null}
sail artisan migrate

sail artisan queue:work
```

### Node / NPM 명령

```shell theme={null}
sail node --version

sail npm run dev

# Yarn을 사용하는 경우
sail yarn
```

### 컨테이너 CLI (셸)

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

```shell theme={null}
sail shell

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

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

```shell theme={null}
sail tinker
```

***

## 서비스

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

### MySQL

기본으로 `compose.yaml`에 포함되어 있습니다.
데이터는 Docker Volume에서 영속화됩니다. 초회 기동 시에 앱용과 `testing`용의 2개의 데이터베이스가 자동 생성됩니다.

`.env`의 `DB_HOST`를 `mysql`로 설정하면 앱에서 접속할 수 있습니다.

```ini theme={null}
DB_HOST=mysql
DB_PORT=3306
```

로컬 머신에서 접속하려면 [TablePlus](https://tableplus.com) 등의 GUI 도구를 사용해 주세요. 기본 포트는 `3306`입니다.

### Redis

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

```ini theme={null}
REDIS_HOST=redis
REDIS_PORT=6379
```

### Valkey

Redis의 대체로서 [Valkey](https://valkey.io/)를 사용하는 경우는 `REDIS_HOST`를 `valkey`로 설정합니다.

### Mailpit

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

```ini theme={null}
MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_ENCRYPTION=null
```

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

### Meilisearch / Typesense

[Laravel Scout](/ko/scout)와 통합해 전문 검색을 시험할 수 있습니다.

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

### RustFS (S3 호환 스토리지)

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

```ini theme={null}
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
```

***

## 테스트의 실행

```shell theme={null}
sail test

sail test --group orders
```

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

### Laravel Dusk

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

```yaml theme={null}
selenium:
    image: 'selenium/standalone-chrome'
    extra_hosts:
      - 'host.docker.internal:host-gateway'
    volumes:
        - '/dev/shm:/dev/shm'
    networks:
        - sail
```

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

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

```shell theme={null}
sail dusk
```

***

## PHP / Node 버전

### PHP 버전의 변경

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

```yaml theme={null}
# 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
```

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

```shell theme={null}
sail build --no-cache
sail up
```

### 추가 PHP 확장 기능

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

```yaml theme={null}
build:
    args:
        WWWGROUP: '${WWWGROUP}'
        PHP_EXTENSIONS: 'gmp imagick'
```

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

```shell theme={null}
sail build --no-cache
sail up
```

### Node 버전의 변경

```yaml theme={null}
build:
    args:
        WWWGROUP: '${WWWGROUP}'
        NODE_VERSION: '20'
```

***

## 사이트의 공개 공유

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

```shell theme={null}
sail share
```

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

```php theme={null}
->withMiddleware(function (Middleware $middleware): void {
    $middleware->trustProxies(at: '*');
})
```

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

```shell theme={null}
sail share --subdomain=my-sail-site
```

***

## Xdebug

### 활성화

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

```ini theme={null}
SAIL_XDEBUG_MODE=develop,debug,coverage
```

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

```ini theme={null}
[xdebug]
xdebug.mode=${XDEBUG_MODE}
```

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

```shell theme={null}
sail build --no-cache
```

### CLI 디버그

```shell theme={null}
# Xdebug 없이 실행
sail artisan migrate

# Xdebug 있음으로 실행
sail debug migrate
```

### 브라우저 디버그

브라우저에서 디버그 세션을 시작하는 순서는 [Xdebug 공식 문서](https://xdebug.org/docs/step_debug#web-application)를 참조해 주세요.
PhpStorm을 사용하고 있는 경우는 [Zero-configuration debugging](https://www.jetbrains.com/help/phpstorm/zero-configuration-debugging.html)의 설정이 편리합니다.

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

***

## 커스터마이즈

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

```shell theme={null}
sail artisan sail:publish
```

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

```shell theme={null}
sail build --no-cache
```

***

## 프로덕션 환경과의 차이

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

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

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


## Related topics

- [Laravel Boost Custom Agent for GitHub Copilot CLI](/ko/packages/laravel-boost-copilot-cli.md)
- [Laravel Scout](/ko/scout.md)
- [Artisan 콘솔](/ko/artisan.md)
- [Redis](/ko/redis.md)
- [Laravel을 시작하기 전에 필요한 지식](/ko/true-tutorial.md)