Laravel Homestead

번역일: 2026년 7월 2일

Laravel Homestead

소개

Laravel은 로컬 개발 환경을 포함한 PHP 개발 경험 전반을 즐겁게 만들기 위해 노력합니다. Laravel Homestead는 공식적으로 제공되는 Vagrant 박스로, PHP, 웹 서버, 그 외 서버 소프트웨어를 직접 로컬 머신에 설치할 필요 없이 훌륭한 개발 환경을 바로 갖출 수 있게 해줍니다.

Vagrant는 가상 머신을 간단하고 우아하게 관리하고 프로비저닝할 수 있는 도구입니다. Vagrant 박스는 언제든지 완전히 폐기하고 재생성할 수 있으므로, 문제가 생기더라도 몇 분 안에 깨끗한 환경으로 복구할 수 있습니다.

Homestead는 Windows, macOS, Linux 어디서든 동작하며, Nginx, PHP, MySQL, PostgreSQL, Redis, Memcached, Node 등 훌륭한 Laravel 애플리케이션 개발에 필요한 모든 소프트웨어를 포함하고 있습니다.

WARNING

Windows를 사용하는 경우 하드웨어 가상화(VT-x)를 활성화해야 할 수 있습니다. 보통 BIOS에서 설정할 수 있습니다. UEFI 시스템에서 Hyper-V를 사용 중이라면 VT-x에 접근하기 위해 Hyper-V를 비활성화해야 할 수도 있습니다.

포함된 소프트웨어

  • Ubuntu 22.04
  • Git
  • PHP 8.3
  • PHP 8.2
  • PHP 8.1
  • PHP 8.0
  • Nginx
  • MySQL 8.0
  • lmm
  • Sqlite3
  • PostgreSQL 15
  • Composer
  • Docker
  • Node (NVM 포함, Yarn, Bower, Grunt, Gulp 포함)
  • Redis
  • Memcached
  • Beanstalkd
  • Mailpit
  • avahi
  • ngrok
  • Xdebug
  • XHProf / Tideways / XHGui
  • wp-cli

선택적 소프트웨어

  • Apache
  • Blackfire
  • Cassandra
  • Chronograf
  • CouchDB
  • Crystal & Lucky Framework
  • Elasticsearch
  • EventStoreDB
  • Flyway
  • Gearman
  • Go
  • Grafana
  • InfluxDB
  • Logstash
  • MariaDB
  • Meilisearch
  • MinIO
  • MongoDB
  • Neo4j
  • Oh My Zsh
  • Open Resty
  • PM2
  • Python
  • R
  • RabbitMQ
  • Rust
  • RVM (Ruby Version Manager)
  • Solr
  • TimescaleDB
  • Trader (PHP 확장)
  • Webdriver & Laravel Dusk 유틸리티

Laravel Homestead

소개

Laravel은 로컬 개발 환경을 포함한 PHP 개발 경험 전반을 쾌적하게 만들고자 합니다. Laravel Homestead는 공식 Vagrant 박스로, PHP, 웹 서버, 기타 서버 소프트웨어를 로컬 머신에 직접 설치하지 않고도 완전한 개발 환경을 제공합니다.

Vagrant는 가상 머신을 간편하게 관리하고 프로비저닝할 수 있는 도구입니다. Vagrant 박스는 언제든지 버리고 새로 만들 수 있습니다. 문제가 생기더라도 박스를 삭제하고 몇 분 안에 다시 생성할 수 있으니 부담 없이 사용할 수 있습니다.

Homestead는 Windows, macOS, Linux 어디서나 실행되며, Nginx, PHP, MySQL, PostgreSQL, Redis, Memcached, Node 등 Laravel 애플리케이션 개발에 필요한 소프트웨어를 모두 포함하고 있습니다.

WARNING

Windows를 사용하는 경우 BIOS에서 하드웨어 가상화(VT-x)를 활성화해야 할 수 있습니다. UEFI 시스템에서 Hyper-V를 사용 중이라면 VT-x에 접근하기 위해 Hyper-V를 비활성화해야 할 수도 있습니다.

포함된 소프트웨어

  • Ubuntu 22.04
  • Git
  • PHP 8.3
  • PHP 8.2
  • PHP 8.1
  • PHP 8.0
  • PHP 7.4
  • PHP 7.3
  • PHP 7.2
  • PHP 7.1
  • PHP 7.0
  • PHP 5.6
  • Nginx
  • MySQL 8.0
  • lmm
  • Sqlite3
  • PostgreSQL 15
  • Composer
  • Docker
  • Node (Yarn, Bower, Grunt, Gulp 포함)
  • Redis
  • Memcached
  • Beanstalkd
  • Mailpit
  • avahi
  • ngrok
  • Xdebug
  • XHProf / Tideways / XHGui
  • wp-cli

선택적 소프트웨어

아래 소프트웨어는 기본으로 설치되지 않으며, Homestead 설정 파일에서 필요한 항목을 선택해 설치할 수 있습니다.

  • Apache
  • Blackfire
  • Cassandra
  • Chronograf
  • CouchDB
  • Crystal & Lucky Framework
  • Elasticsearch
  • EventStoreDB
  • Flyway
  • Gearman
  • Go
  • Grafana
  • InfluxDB
  • Logstash
  • MariaDB
  • Meilisearch
  • MinIO
  • MongoDB
  • Neo4j
  • Oh My Zsh
  • Open Resty
  • PM2
  • Python
  • R
  • RabbitMQ
  • Rust
  • RVM (Ruby Version Manager)
  • Solr
  • TimescaleDB
  • Trader (PHP 익스텐션)
  • Webdriver & Laravel Dusk Utilities

Laravel Homestead

설치 및 설정

시작하기 전에

Homestead 환경을 실행하려면 먼저 Vagrant와 아래 가상화 프로바이더 중 하나를 설치해야 합니다.

두 소프트웨어 모두 주요 운영체제에서 사용할 수 있는 시각적 설치 프로그램을 제공합니다.

Parallels 프로바이더를 사용하려면 Parallels Vagrant 플러그인을 별도로 설치해야 합니다. 이 플러그인은 무료로 제공됩니다.

Homestead 설치

Homestead 저장소를 호스트 머신에 클론하여 설치합니다. 홈 디렉터리 안에 Homestead 폴더를 만들어 그 안에 클론하는 것을 권장합니다. 이 가상 머신이 모든 Laravel 프로젝트의 실행 환경이 되므로, 이 문서에서는 해당 디렉터리를 "Homestead 디렉터리"라고 부릅니다.

git clone https://github.com/laravel/homestead.git ~/Homestead

클론이 완료되면 release 브랜치로 전환합니다. 이 브랜치는 항상 Homestead의 최신 안정 버전을 유지합니다.

cd ~/Homesteadgit checkout release

다음으로, Homestead 디렉터리에서 bash init.sh 명령을 실행해 Homestead.yaml 설정 파일을 생성합니다. 이 파일이 Homestead의 모든 설정을 담는 핵심 파일이며, Homestead 디렉터리 안에 생성됩니다.

<h1 id="configuring-nginx-sites">macOS / Linux...</h1> bash init.sh <h1 id="hostname-resolution">Windows...</h1> init.bat

Homestead 설정

프로바이더 설정

Homestead.yaml 파일의 provider 키에서 사용할 Vagrant 프로바이더를 지정합니다. virtualbox 또는 parallels 중 하나를 선택합니다.

provider: virtualbox

WARNING

Apple Silicon(M1/M2/M3) Mac을 사용하는 경우 반드시 Parallels 프로바이더를 사용해야 합니다.

공유 폴더 설정

Homestead.yaml의 folders 항목에는 호스트 머신과 Homestead 가상 환경 간에 공유할 폴더를 지정합니다. 지정된 폴더 안의 파일이 변경되면 양쪽이 자동으로 동기화됩니다. 필요한 만큼 공유 폴더를 추가할 수 있습니다.

folders: - map: ~/code/project1 to: /home/vagrant/project1

WARNING

Windows 사용자는 ~/ 경로 형식을 사용하지 말고, C:\Users\사용자이름\Code\project1처럼 전체 경로를 입력해야 합니다.

여러 프로젝트를 하나의 큰 디렉터리로 묶어서 공유하기보다는, 프로젝트별로 각각 폴더 매핑을 설정하는 것이 좋습니다. 폴더를 마운트하면 가상 머신이 그 안의 모든 파일에 대한 디스크 I/O를 추적해야 합니다. 파일 수가 많아질수록 성능이 저하될 수 있습니다.

folders: - map: ~/code/project1 to: /home/vagrant/project1 - map: ~/code/project2 to: /home/vagrant/project2

WARNING

Homestead에서 .(현재 디렉터리)을 마운트하면 안 됩니다. 이 경우 Vagrant가 현재 폴더를 /vagrant에 매핑하지 못하게 되어 일부 기능이 동작하지 않거나 프로비저닝 중 예기치 않은 오류가 발생할 수 있습니다.

NFS를 사용하려면 폴더 매핑에 type 옵션을 추가합니다.

folders: - map: ~/code/project1 to: /home/vagrant/project1 type: "nfs"

WARNING

Windows에서 NFS를 사용할 때는 vagrant-winnfsd 플러그인 설치를 권장합니다. 이 플러그인은 가상 머신 내 파일과 디렉터리의 사용자/그룹 권한을 올바르게 유지해 줍니다.

Vagrant의 Synced Folders에서 지원하는 옵션은 options 키 아래에 추가할 수 있습니다.

folders: - map: ~/code/project1 to: /home/vagrant/project1 type: "rsync" options: rsync__args: ["--verbose", "--archive", "--delete", "-zz"] rsync__exclude: ["node_modules"]

Nginx 사이트 설정

Nginx에 익숙하지 않아도 괜찮습니다. Homestead.yaml의 sites 항목을 사용하면 도메인과 Homestead 내 폴더를 손쉽게 연결할 수 있습니다. 기본 사이트 설정 예시가 Homestead.yaml에 포함되어 있으며, 원하는 만큼 사이트를 추가할 수 있습니다. Homestead 하나로 여러 Laravel 애플리케이션을 동시에 운영할 수 있습니다.

sites: - map: homestead.test to: /home/vagrant/project1/public

가상 머신을 프로비저닝한 후 sites 항목을 변경했다면, 터미널에서 vagrant reload --provision 명령을 실행해 가상 머신의 Nginx 설정을 갱신해야 합니다.

WARNING

Homestead 스크립트는 가능한 한 멱등성(idempotent)을 보장하도록 설계되어 있습니다. 그러나 프로비저닝 중 문제가 발생하면 vagrant destroy && vagrant up 명령으로 머신을 완전히 재생성하는 것이 가장 확실한 해결책입니다.

호스트명 해석

Homestead는 mDNS를 이용해 호스트명을 자동으로 해석합니다. Homestead.yaml에 hostname: homestead를 설정하면 homestead.local로 접근할 수 있습니다. macOS, iOS, Linux 데스크탑은 기본적으로 mDNS를 지원합니다. Windows에서는 Bonjour Print Services for Windows를 설치해야 합니다.

자동 호스트명 해석은 프로젝트별 설치 방식에서 가장 잘 동작합니다. 하나의 Homestead 인스턴스에서 여러 사이트를 운영할 경우에는 각 도메인을 호스트 머신의 hosts 파일에 직접 추가해야 합니다. 이 파일에 등록된 도메인 요청이 Homestead 가상 머신으로 전달됩니다.

  • macOS / Linux: /etc/hosts
  • Windows: C:\Windows\System32\drivers\etc\hosts

추가할 내용은 다음과 같습니다.

192.168.56.56 homestead.test

IP 주소는 Homestead.yaml에 설정된 값과 일치해야 합니다. hosts 파일에 도메인을 추가하고 Vagrant 박스를 실행하면 브라우저에서 사이트에 접근할 수 있습니다.

http://homestead.test

서비스 설정

Homestead는 기본적으로 여러 서비스를 자동으로 시작합니다. 프로비저닝 시 어떤 서비스를 활성화하거나 비활성화할지 Homestead.yaml의 services 옵션으로 제어할 수 있습니다. 예를 들어, PostgreSQL을 활성화하고 MySQL을 비활성화하려면 다음과 같이 설정합니다.

services: - enabled: - "postgresql" - disabled: - "mysql"

지정된 서비스는 enabled 및 disabled 목록의 순서에 따라 시작되거나 중지됩니다.

Vagrant 박스 실행

Homestead.yaml 설정을 완료했으면 Homestead 디렉터리에서 vagrant up 명령을 실행합니다. Vagrant가 가상 머신을 부팅하고 공유 폴더와 Nginx 사이트를 자동으로 설정합니다.

가상 머신을 삭제하려면 vagrant destroy 명령을 사용합니다.

프로젝트별 설치

Homestead를 전역으로 설치하여 모든 프로젝트가 하나의 가상 머신을 공유하는 대신, 프로젝트마다 별도의 Homestead 인스턴스를 구성할 수도 있습니다. 이 방식은 프로젝트에 Vagrantfile을 포함해 팀원이 저장소를 클론한 후 바로 vagrant up을 실행할 수 있도록 하고 싶을 때 유용합니다.

Composer로 Homestead를 프로젝트에 설치합니다.

composer require laravel/homestead --dev

설치가 완료되면 Homestead의 make 명령을 실행해 프로젝트 루트에 Vagrantfile과 Homestead.yaml을 생성합니다. make 명령은 Homestead.yaml의 sites 및 folders 설정을 자동으로 구성해 줍니다.

<h1 id="mongodb">macOS / Linux...</h1> php vendor/bin/homestead make <h1 id="neo4j">Windows...</h1> vendor\\bin\\homestead make

이후 터미널에서 vagrant up을 실행하고 브라우저에서 http://homestead.test로 프로젝트에 접근합니다. 자동 호스트명 해석을 사용하지 않는 경우에는 homestead.test 또는 원하는 도메인을 /etc/hosts 파일에 직접 추가해야 한다는 점을 잊지 마세요.

선택적 기능 설치

Homestead.yaml의 features 옵션을 사용해 선택적 소프트웨어를 설치할 수 있습니다. 대부분의 기능은 true / false로 활성화·비활성화하며, 일부는 세부 설정 옵션을 지원합니다.

features: - blackfire: server_id: "server_id" server_token: "server_value" client_id: "client_id" client_token: "client_value" - cassandra: true - chronograf: true - couchdb: true - crystal: true - dragonflydb: true - elasticsearch: version: 7.9.0 - eventstore: true version: 21.2.0 - flyway: true - gearman: true - golang: true - grafana: true - influxdb: true - logstash: true - mariadb: true - meilisearch: true - minio: true - mongodb: true - neo4j: true - ohmyzsh: true - openresty: true - pm2: true - python: true - r-base: true - rabbitmq: true - rustc: true - rvm: true - solr: true - timescaledb: true - trader: true - webdriver: true

Elasticsearch

지원되는 Elasticsearch 버전을 major.minor.patch 형식의 정확한 버전 번호로 지정할 수 있습니다. 기본 설치 시 'homestead'라는 이름의 클러스터가 생성됩니다. Elasticsearch에는 운영체제 메모리의 절반 이상을 할당하지 않는 것이 원칙이므로, Homestead 가상 머신의 메모리는 Elasticsearch에 할당하려는 용량의 최소 두 배 이상으로 설정해야 합니다.

NOTE

설정을 커스터마이즈하는 방법은 Elasticsearch 공식 문서를 참고하세요.

MariaDB

MariaDB를 활성화하면 MySQL이 제거되고 MariaDB가 설치됩니다. MariaDB는 MySQL의 드롭인(drop-in) 대체제로 동작하므로, 애플리케이션의 데이터베이스 설정에서 드라이버는 그대로 mysql을 사용하면 됩니다.

MongoDB

기본 MongoDB 설치 시 데이터베이스 사용자 이름은 homestead, 비밀번호는 secret으로 설정됩니다.

Neo4j

기본 Neo4j 설치 시 데이터베이스 사용자 이름은 homestead, 비밀번호는 secret으로 설정됩니다. Neo4j 브라우저에 접근하려면 http://homestead.test:7474를 방문하세요. Neo4j 클라이언트에서 사용하는 포트는 다음과 같습니다.

  • 7687 — Bolt
  • 7474 — HTTP
  • 7473 — HTTPS

별칭(Aliases) 설정

Homestead 디렉터리 안의 aliases 파일을 수정해 가상 머신에 Bash 별칭을 추가할 수 있습니다.

alias c='clear'alias ..='cd ..'

aliases 파일을 수정한 후에는 vagrant reload --provision 명령으로 Homestead 가상 머신을 재프로비저닝해야 새 별칭이 적용됩니다.

Homestead 업데이트

Homestead를 업데이트하기 전에, 먼저 현재 실행 중인 가상 머신을 제거해야 합니다. Homestead 디렉터리에서 다음 명령을 실행하세요:

vagrant destroy

다음으로 Homestead 소스 코드를 업데이트합니다. 저장소를 클론한 경우, 원래 클론한 위치에서 아래 명령을 실행하세요:

git fetchgit pull origin release

이 명령들은 GitHub 저장소에서 최신 Homestead 코드와 태그를 가져온 뒤, 가장 최신의 안정 릴리즈로 체크아웃합니다. 최신 안정 버전은 Homestead의 GitHub 릴리즈 페이지에서 확인할 수 있습니다.

프로젝트의 composer.json 파일을 통해 Homestead를 설치한 경우, composer.json 파일에 "laravel/homestead": "^12"가 명시되어 있는지 확인한 후 의존성을 업데이트하세요:

composer update

그 다음, vagrant box update 명령으로 Vagrant 박스를 업데이트합니다:

vagrant box update

Vagrant 박스 업데이트가 완료되면, Homestead 디렉터리에서 bash init.sh 명령을 실행하여 추가 설정 파일들을 갱신합니다. 이 과정에서 기존의 Homestead.yaml, after.sh, aliases 파일을 덮어쓸지 여부를 묻는 메시지가 표시됩니다:

<h1 id="site-types">macOS / Linux...</h1> bash init.sh <h1 id="site-parameters">Windows...</h1> init.bat

마지막으로, 최신 Vagrant 설치 환경을 반영한 Homestead 가상 머신을 새로 생성합니다:

vagrant up

일상적인 사용법

SSH로 접속하기

Homestead 디렉터리에서 다음 명령어를 실행하면 가상 머신에 SSH로 접속할 수 있습니다.

vagrant ssh

사이트 추가하기

Homestead 환경이 프로비저닝되어 실행 중인 상태라면, 다른 Laravel 프로젝트를 위한 Nginx 사이트를 추가할 수 있습니다. 하나의 Homestead 환경에서 여러 Laravel 프로젝트를 동시에 실행하는 것이 가능합니다. 사이트를 추가하려면 Homestead.yaml 파일에 항목을 추가하세요.

sites: - map: homestead.test to: /home/vagrant/project1/public - map: another.test to: /home/vagrant/project2/public

WARNING

사이트를 추가하기 전에, 해당 프로젝트 디렉터리에 대한 폴더 매핑이 설정되어 있는지 확인하세요.

Vagrant가 hosts 파일을 자동으로 관리하지 않는 경우, 새 사이트를 직접 추가해야 합니다. macOS와 Linux에서는 /etc/hosts, Windows에서는 C:\Windows\System32\drivers\etc\hosts 파일을 수정하세요.

192.168.56.56  homestead.test
192.168.56.56  another.test

항목을 추가한 후 Homestead 디렉터리에서 다음 명령어를 실행하세요.

vagrant reload --provision

사이트 타입

Homestead는 Laravel 외의 다양한 프레임워크 기반 프로젝트를 손쉽게 실행할 수 있도록 여러 사이트 타입을 지원합니다. 예를 들어, Statamic 애플리케이션을 추가하려면 type 옵션을 아래와 같이 지정합니다.

sites: - map: statamic.test to: /home/vagrant/my-symfony-project/web type: "statamic"

사용 가능한 사이트 타입 목록: apache, apache-proxy, apigility, expressive, laravel (기본값), proxy (nginx용), silverstripe, statamic, symfony2, symfony4, zf

사이트 파라미터

params 디렉티브를 사용하면 특정 사이트에 Nginx fastcgi_param 값을 추가로 설정할 수 있습니다.

sites: - map: homestead.test to: /home/vagrant/project1/public params: - key: FOO value: BAR

환경 변수 설정

전역 환경 변수는 Homestead.yaml 파일에 아래와 같이 정의합니다.

variables: - key: APP_ENV value: local - key: FOO value: bar

Homestead.yaml을 수정한 후에는 반드시 vagrant reload --provision 명령어로 머신을 다시 프로비저닝해야 합니다. 이 과정에서 설치된 모든 PHP 버전의 PHP-FPM 설정과 vagrant 사용자 환경 변수가 함께 업데이트됩니다.

포트 설정

기본적으로 다음 포트들이 Homestead 환경으로 포워딩됩니다.

  • HTTP: 8000 → 80으로 포워딩
  • HTTPS: 44300 → 443으로 포워딩

추가 포트 포워딩

Homestead.yaml에 ports 항목을 추가하면 Vagrant 박스로 포워딩할 포트를 더 지정할 수 있습니다. 파일을 수정한 후에는 vagrant reload --provision을 실행하세요.

ports: - send: 50000 to: 5000 - send: 7777 to: 777 protocol: udp

호스트 머신에서 Vagrant 박스의 각 서비스에 접근할 때 사용하는 포트 목록은 다음과 같습니다.

  • SSH: 2222 → 22
  • ngrok UI: 4040 → 4040
  • MySQL: 33060 → 3306
  • PostgreSQL: 54320 → 5432
  • MongoDB: 27017 → 27017
  • Mailpit: 8025 → 8025
  • Minio: 9600 → 9600

PHP 버전 관리

Homestead는 하나의 가상 머신에서 여러 PHP 버전을 동시에 실행할 수 있습니다. Homestead.yaml에서 각 사이트별로 사용할 PHP 버전을 지정할 수 있습니다. 사용 가능한 버전은 "5.6", "7.0", "7.1", "7.2", "7.3", "7.4", "8.0", "8.1", "8.2", "8.3"(기본값)입니다.

sites: - map: homestead.test to: /home/vagrant/project1/public php: "7.1"

Homestead 가상 머신 내부에서는 CLI를 통해 원하는 PHP 버전을 직접 지정하여 실행할 수 있습니다.

php5.6 artisan listphp7.0 artisan listphp7.1 artisan listphp7.2 artisan listphp7.3 artisan listphp7.4 artisan listphp8.0 artisan listphp8.1 artisan listphp8.2 artisan listphp8.3 artisan list

CLI의 기본 PHP 버전을 변경하려면 가상 머신 내에서 다음 명령어 중 하나를 실행하세요.

php56php70php71php72php73php74php80php81php82php83

데이터베이스 연결

Homestead는 MySQL과 PostgreSQL 데이터베이스를 별도 설정 없이 바로 사용할 수 있도록 homestead 데이터베이스를 기본 제공합니다. 호스트 머신의 데이터베이스 클라이언트(예: TablePlus, DBeaver)에서 접속할 때는 127.0.0.1에 MySQL은 포트 33060, PostgreSQL은 포트 54320을 사용하세요. 두 데이터베이스의 사용자명과 비밀번호는 모두 homestead / secret입니다.

WARNING

이 비표준 포트(33060, 54320)는 호스트 머신에서 외부 클라이언트로 접속할 때만 사용합니다. Laravel 애플리케이션 자체는 가상 머신 내부에서 실행되므로, config/database.php에는 기본 포트인 3306(MySQL)과 5432(PostgreSQL)를 그대로 사용하세요.

데이터베이스 백업

Homestead는 가상 머신이 삭제(vagrant destroy)될 때 데이터베이스를 자동으로 백업하는 기능을 제공합니다. 이 기능을 사용하려면 Vagrant 2.1.0 이상이 필요합니다. 구버전을 사용 중이라면 vagrant-triggers 플러그인을 별도로 설치해야 합니다. 자동 백업을 활성화하려면 Homestead.yaml에 다음 줄을 추가하세요.

backup: true

설정이 완료되면 vagrant destroy 실행 시 데이터베이스가 .backup/mysql_backup 및 .backup/postgres_backup 디렉터리로 내보내집니다. 이 디렉터리는 Homestead를 설치한 폴더 또는 프로젝트별 설치 방식을 사용하는 경우 프로젝트 루트에서 찾을 수 있습니다.

크론 스케줄 설정

Laravel은 매 분마다 schedule:run Artisan 명령어 하나만 실행하면 크론 작업을 편리하게 스케줄링할 수 있습니다. schedule:run 명령어는 App\Console\Kernel 클래스에 정의된 스케줄을 확인하여 실행할 작업을 결정합니다.

Homestead 사이트에서 schedule:run을 자동 실행하려면, 사이트 정의 시 schedule 옵션을 true로 설정하세요.

sites: - map: homestead.test to: /home/vagrant/project1/public schedule: true

해당 사이트의 크론 작업은 Homestead 가상 머신의 /etc/cron.d 디렉터리에 등록됩니다.

Mailpit 설정

Mailpit은 애플리케이션에서 발송하는 이메일을 실제로 전송하지 않고 중간에서 가로채어 내용을 확인할 수 있는 도구입니다. 개발 중 이메일 발송 테스트에 매우 유용합니다. 사용하려면 .env 파일의 메일 설정을 아래와 같이 변경하세요.

MAIL_MAILER=smtp MAIL_HOST=localhost MAIL_PORT=1025 MAIL_USERNAME=null MAIL_PASSWORD=null MAIL_ENCRYPTION=null

설정 후 http://localhost:8025에서 Mailpit 대시보드에 접근할 수 있습니다.

Minio 설정

Minio는 Amazon S3 호환 API를 제공하는 오픈 소스 오브젝트 스토리지 서버입니다. Minio를 설치하려면 Homestead.yaml의 features 섹션에 다음 옵션을 추가하세요.

minio: true

Minio는 기본적으로 포트 9600에서 실행됩니다. http://localhost:9600에서 Minio 관리 패널에 접근할 수 있습니다. 기본 액세스 키는 homestead, 시크릿 키는 secretkey이며, 리전은 항상 us-east-1을 사용해야 합니다.

Minio를 사용하려면 config/filesystems.php의 S3 디스크 설정을 수정해야 합니다. use_path_style_endpoint 옵션을 추가하고 url 키를 endpoint로 변경하세요.

's3' => [
    'driver' => 's3',
    'key' => env('AWS_ACCESS_KEY_ID'),
    'secret' => env('AWS_SECRET_ACCESS_KEY'),
    'region' => env('AWS_DEFAULT_REGION'),
    'bucket' => env('AWS_BUCKET'),
    'endpoint' => env('AWS_URL'),
    'use_path_style_endpoint' => true,
]

그리고 .env 파일에 다음 값들을 설정하세요.

AWS_ACCESS_KEY_ID=homestead AWS_SECRET_ACCESS_KEY=secretkey AWS_DEFAULT_REGION=us-east-1 AWS_URL=http://localhost:9600

Minio 기반 "S3" 버킷을 프로비저닝하려면 Homestead.yaml에 buckets 디렉티브를 추가한 후 vagrant reload --provision을 실행하세요.

buckets: - name: your-bucket policy: public - name: your-private-bucket policy: none

policy에 사용할 수 있는 값은 none, download, upload, public입니다.

Laravel Dusk

Homestead에서 Laravel Dusk 테스트를 실행하려면 Homestead 설정에서 webdriver 기능을 활성화해야 합니다.

features: - webdriver: true

webdriver를 활성화한 후에는 vagrant reload --provision을 실행하세요.

환경 공유하기

작업 중인 화면을 팀원이나 클라이언트와 공유해야 할 때가 있습니다. Vagrant는 vagrant share 명령어로 이를 지원하지만, Homestead.yaml에 여러 사이트가 설정되어 있는 경우에는 정상적으로 동작하지 않습니다.

이 문제를 해결하기 위해 Homestead는 자체 share 명령어를 제공합니다. 먼저 vagrant ssh로 Homestead 가상 머신에 SSH 접속한 후, 공유할 사이트 이름을 인수로 전달하여 명령어를 실행하세요.

share homestead.test

명령어를 실행하면 Ngrok 화면이 나타나며, 활동 로그와 외부에서 접근 가능한 공개 URL을 확인할 수 있습니다. 리전, 서브도메인 등 Ngrok 옵션을 추가로 지정할 수도 있습니다.

share homestead.test -region=eu -subdomain=laravel

HTTP 대신 HTTPS로 공유해야 한다면 share 대신 sshare 명령어를 사용하세요.

WARNING

Vagrant 환경은 기본적으로 보안이 취약합니다. share 명령어를 실행하면 가상 머신이 인터넷에 노출되므로 주의하세요.

Laravel Homestead

디버깅과 프로파일링

Xdebug로 웹 요청 디버깅하기

Homestead는 Xdebug를 이용한 단계별 디버깅(step debugging)을 기본으로 지원합니다. 브라우저에서 페이지에 접근하면 PHP가 IDE에 자동으로 연결되어, 실행 중인 코드를 검사하고 변수 값을 확인할 수 있습니다.

기본적으로 Xdebug는 이미 실행 중이며 연결을 대기하는 상태입니다. CLI에서 Xdebug를 활성화해야 한다면, Homestead 가상 머신 내에서 sudo phpenmod xdebug 명령어를 실행하세요. 그런 다음 IDE의 디버깅 설정을 활성화하고, 브라우저에 Xdebug 확장 프로그램이나 북마클릿(bookmarklet)을 설정하면 됩니다.

WARNING

Xdebug를 활성화하면 PHP 실행 속도가 눈에 띄게 느려집니다. 디버깅이 필요하지 않을 때는 가상 머신 안에서 sudo phpdismod xdebug를 실행하고 FPM 서비스를 재시작하여 Xdebug를 비활성화하세요.

Xdebug 자동 시작 설정

웹 서버로 요청을 보내는 기능 테스트(functional test)를 디버깅할 때, 테스트 코드를 수정해 커스텀 헤더나 쿠키를 추가하는 방식보다는 Xdebug가 자동으로 시작되도록 설정하는 편이 더 편리합니다. 자동 시작을 활성화하려면 Homestead 가상 머신 내의 /etc/php/7.x/fpm/conf.d/20-xdebug.ini 파일을 열고 아래 설정을 추가하세요.

; Homestead.yaml에서 다른 서브넷 IP를 사용하는 경우 아래 주소가 다를 수 있습니다... xdebug.client_host = 192.168.10.1 xdebug.mode = debug xdebug.start_with_request = yes

CLI 애플리케이션 디버깅하기

PHP CLI 애플리케이션을 디버깅할 때는 Homestead 가상 머신에서 제공하는 xphp 셸 별칭(alias)을 사용하세요.

xphp /path/to/script

Blackfire로 애플리케이션 프로파일링하기

Blackfire는 웹 요청과 CLI 애플리케이션을 프로파일링할 수 있는 서비스입니다. 콜 그래프(call-graph)와 타임라인 형태로 프로파일 데이터를 시각화하는 인터랙티브 UI를 제공하며, 개발·스테이징·프로덕션 환경 모두에서 사용할 수 있습니다. 엔드 유저에게는 별도의 성능 부담 없이 작동하며, 코드 품질·성능·보안 점검과 php.ini 설정 검사 기능도 함께 제공합니다.

Blackfire Player는 오픈소스 웹 크롤링·테스트·스크래핑 도구로, Blackfire와 연동하여 프로파일링 시나리오를 스크립트로 작성할 수 있습니다.

Blackfire를 활성화하려면 Homestead 설정 파일의 features 항목에 아래와 같이 추가하세요.

features: - blackfire: server_id: "server_id" server_token: "server_value" client_id: "client_id" client_token: "client_value"

Blackfire 서버 자격증명과 클라이언트 자격증명을 사용하려면 Blackfire 계정이 필요합니다. CLI 도구와 브라우저 확장 프로그램 등 다양한 프로파일링 방식을 지원하며, 자세한 내용은 Blackfire 공식 문서를 참고하세요.

네트워크 인터페이스

Homestead.yaml 파일의 networks 속성을 사용하면 Homestead 가상 머신의 네트워크 인터페이스를 설정할 수 있습니다. 필요에 따라 여러 인터페이스를 자유롭게 구성할 수 있습니다:

networks: - type: "private_network" ip: "192.168.10.20"

브리지(bridged) 인터페이스를 사용하려면 bridge 항목을 추가하고 네트워크 타입을 public_network로 변경하세요:

networks: - type: "public_network" ip: "192.168.10.20" bridge: "en1: Wi-Fi (AirPort)"

DHCP를 사용하려면 ip 옵션을 제거하면 됩니다:

networks: - type: "public_network" bridge: "en1: Wi-Fi (AirPort)"

네트워크가 사용할 디바이스를 직접 지정하고 싶다면 dev 옵션을 추가하세요. 기본값은 eth0입니다:

networks: - type: "public_network" ip: "192.168.10.20" bridge: "en1: Wi-Fi (AirPort)" dev: "enp2s0"

Homestead 확장

Homestead 디렉터리 루트에 있는 after.sh 스크립트를 사용하면 Homestead를 자유롭게 확장할 수 있습니다. 이 파일 안에 가상 머신을 추가로 설정하거나 커스터마이징하는 데 필요한 셸 명령어를 작성하면 됩니다.

패키지를 설치할 때 Ubuntu가 기존 설정 파일을 유지할지 새 설정 파일로 덮어쓸지 묻는 경우가 있습니다. Homestead가 미리 작성해 둔 설정을 실수로 덮어쓰지 않으려면 패키지 설치 시 아래와 같이 옵션을 지정하세요:

sudo apt-get -y \    -o Dpkg::Options::="--force-confdef" \    -o Dpkg::Options::="--force-confold" \    install package-name

사용자 커스터마이징

팀과 함께 Homestead를 사용할 때, 개인 개발 스타일에 맞게 환경을 조정하고 싶을 수 있습니다. 이럴 때는 Homestead 디렉터리 루트(Homestead.yaml 파일이 있는 위치)에 user-customizations.sh 파일을 만들고, 원하는 커스터마이징 내용을 자유롭게 작성하면 됩니다.

NOTE

user-customizations.sh 파일은 개인 설정 파일이므로 버전 관리(Git 등)에 포함하지 않는 것이 좋습니다. .gitignore에 추가해 두세요.

프로바이더별 설정

VirtualBox

natdnshostresolver

Homestead는 기본적으로 natdnshostresolver 설정을 on으로 구성합니다. 이를 통해 Homestead가 호스트 운영체제의 DNS 설정을 그대로 사용할 수 있습니다. 이 동작을 비활성화하려면 Homestead.yaml 파일에 다음 옵션을 추가하세요:

provider: virtualbox natdnshostresolver: 'off'

이 문서는 Laravel 공식 문서(MIT)를 한국 개발자를 위해 번역·재구성한 것입니다.

번역일: 2026년 7월 2일