본문 바로가기

Homestead

업데이트됨

번역일: 2026년 9월 26일

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

원문 수정
2026년 9월 26일
번역 갱신
2026년 9월 26일

Homestead

소개

Laravel은 로컬 PHP 개발 환경 전체를 가능한 한 즐겁게 만드는 것을 목표로 하는 프레임워크입니다. 그중에서도 Laravel Homestead는 여러분의 컴퓨터에 PHP, 웹 서버, 기타 서버 소프트웨어를 직접 설치하지 않고도 훌륭한 개발 환경을 손쉽게 구축할 수 있게 해주는 공식 Vagrant Box입니다.

Vagrant는 가상 머신을 쉽고 우아하게 관리하고 다룰 수 있게 해주는 도구입니다. Vagrant Box는 완전히 폐기 가능(disposable)합니다. 즉, 문제가 생기면 몇 분 안에 박스를 삭제하고 다시 생성할 수 있습니다! Homestead는 Windows, macOS, Linux 어떤 시스템에서도 실행할 수 있으며, Nginx 웹 서버, PHP, MySQL, PostgreSQL, Redis, Memcached, Node 등 Laravel 애플리케이션 개발에 필요한 모든 소프트웨어를 포함하고 있습니다.

NOTE

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
  • 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 포함)
  • Redis
  • Memcached
  • 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 유틸리티

Homestead

소개

WARNING

Laravel Homestead는 더 이상 활발히 관리되지 않는 레거시 패키지입니다. 현대적인 대안으로 Laravel Sail을 사용할 수 있습니다.

Laravel은 로컬 개발 환경을 포함하여 PHP 개발 경험 전반을 즐겁게 만들고자 합니다. Laravel Homestead는 공식적으로 미리 패키징된 Vagrant box로, 로컬 머신에 PHP나 웹 서버 등 별도의 서버 소프트웨어를 설치하지 않고도 훌륭한 개발 환경을 제공합니다.

Vagrant는 가상 머신을 간단하고 우아하게 관리하고 프로비저닝할 수 있는 방법을 제공합니다. Vagrant box는 완전히 폐기 가능(disposable)합니다. 문제가 생기면 몇 분 안에 box를 삭제하고 다시 만들 수 있습니다!

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
  • 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

선택적으로 설치 가능한 소프트웨어

  • 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 유틸리티

Homestead

설치 및 설정

시작하기 전에

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

두 소프트웨어 모두 대부분의 운영체제에서 사용하기 쉬운 그래픽 설치 프로그램을 제공합니다.

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

Homestead 설치하기

Homestead 저장소를 호스트 머신에 클론하여 설치할 수 있습니다. Homestead 가상 머신은 여러분이 작업하는 모든 Laravel 애플리케이션의 호스트 역할을 하게 되므로, 홈 디렉터리 안에 Homestead라는 폴더를 만들어 그 안에 클론하는 것을 권장합니다. 이 문서 전체에서는 이 디렉터리를 "Homestead 디렉터리"라고 부르겠습니다.

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

저장소를 클론한 후에는 release 브랜치로 체크아웃해야 합니다. 이 브랜치는 항상 Homestead의 최신 안정 버전을 담고 있습니다.

cd ~/Homesteadgit checkout release

다음으로 Homestead 디렉터리에서 bash init.sh 명령어를 실행해 Homestead.yaml 설정 파일을 생성하세요. 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 등) 기반의 Mac을 사용 중이라면 반드시 Parallels 프로바이더를 사용해야 합니다.

공유 폴더 설정하기

Homestead.yaml 파일의 folders 속성에는 Homestead 환경과 공유할 폴더 목록을 지정합니다. 이 폴더 안의 파일이 변경되면 로컬 머신과 Homestead 가상 머신 사이에서 자동으로 동기화됩니다. 필요한 만큼 여러 개의 공유 폴더를 설정할 수 있습니다.

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

WARNING

Windows 사용자는 ~/ 형태의 경로 표기법을 사용할 수 없습니다. 대신 C:\Users\user\Code\project1처럼 전체 경로를 입력해야 합니다.

여러 애플리케이션을 모두 담고 있는 하나의 큰 디렉터리를 통째로 매핑하기보다는, 애플리케이션마다 개별 폴더로 매핑하는 것이 좋습니다. 폴더를 매핑하면 가상 머신이 그 폴더 안의 모든 파일에 대한 디스크 IO를 추적해야 하는데, 폴더 안에 파일 개수가 많으면 성능이 저하될 수 있습니다.

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 플러그인 설치를 고려해 보세요. 이 플러그인은 Homestead 가상 머신 내 파일 및 디렉터리의 사용자/그룹 권한을 올바르게 유지해 줍니다.

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

Homestead 가상 머신을 프로비저닝한 이후에 sites 속성을 변경했다면, 터미널에서 vagrant reload --provision 명령어를 실행해 가상 머신의 Nginx 설정을 업데이트해야 합니다.

WARNING

Homestead 스크립트는 최대한 멱등성(같은 작업을 여러 번 실행해도 결과가 같도록)을 갖도록 설계되어 있습니다. 그럼에도 프로비저닝 과정에서 문제가 발생한다면 vagrant destroy && vagrant up 명령어로 머신을 완전히 삭제하고 다시 생성해 보세요.

호스트명 자동 인식

Homestead는 mDNS를 이용해 호스트명을 게시하여 자동으로 호스트를 인식할 수 있게 해줍니다. Homestead.yaml 파일에 hostname: homestead로 설정했다면, homestead.local 주소로 접속할 수 있습니다. macOS, iOS, 그리고 대부분의 Linux 데스크톱 배포판은 기본적으로 mDNS를 지원합니다. Windows를 사용 중이라면 Bonjour Print Services for Windows를 설치해야 합니다.

자동 호스트명 인식은 Homestead를 프로젝트별로 설치했을 때 가장 잘 동작합니다. 만약 하나의 Homestead 인스턴스에서 여러 사이트를 운영한다면, 각 웹 사이트의 "도메인"을 여러분의 로컬 머신 hosts 파일에 직접 추가해야 합니다. 이 hosts 파일은 해당 도메인으로의 요청을 Homestead 가상 머신으로 리다이렉트해 줍니다. macOS와 Linux에서는 /etc/hosts 파일이며, Windows에서는 C:\Windows\System32\drivers\etc\hosts 파일입니다. 추가할 내용은 다음과 같은 형태입니다.

192.168.56.56  homestead.test

여기에 입력하는 IP 주소는 반드시 Homestead.yaml 파일에 설정된 IP와 동일해야 합니다. 도메인을 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 옵션을 통해 설정합니다. 대부분의 기능은 불리언 값으로 활성화/비활성화할 수 있으며, 일부 기능은 추가적인 세부 설정 값을 받을 수 있습니다.

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가 설치됩니다. 애플리케이션에서는 mysql 드라이버 대신 mariadb 데이터베이스 드라이버를 사용해야 합니다. 둘 다 연결 자체는 가능하지만, 벡터 거리 쿼리(vector distance query)와 같이 MariaDB 전용 SQL 문법은 mariadb 드라이버를 사용해야만 정상적으로 생성됩니다.

MongoDB

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

Neo4j

Neo4j를 기본 설치하면 데이터베이스 사용자 이름은 homestead, 비밀번호는 secret으로 설정됩니다. Neo4j 브라우저에 접속하려면 웹 브라우저에서 http://homestead.test:7474로 이동하세요. 7687(Bolt), 7474(HTTP), 7473(HTTPS) 포트가 Neo4j 클라이언트의 요청을 처리할 준비가 되어 있습니다.

별칭(Alias) 설정하기

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

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

aliases 파일을 수정한 후에는 vagrant reload --provision 명령어로 Homestead 가상 머신을 다시 프로비저닝해야 합니다. 그래야 새로 추가한 별칭이 머신에 반영되어 사용할 수 있습니다.

Homestead

Homestead 업데이트하기

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

vagrant destroy

다음으로 Homestead 소스 코드를 업데이트합니다. 저장소를 직접 클론하여 사용하고 있다면, 원래 클론했던 위치에서 다음 명령어를 실행하면 됩니다.

git fetchgit pull origin release

위 명령어는 GitHub 저장소로부터 최신 Homestead 코드를 가져오고, 최신 태그를 fetch한 뒤 가장 최근에 태그된 릴리스로 체크아웃합니다. 최신 안정 버전은 Homestead의 GitHub 릴리스 페이지에서 확인할 수 있습니다.

프로젝트의 composer.json 파일을 통해 Homestead를 설치했다면, composer.json 파일에 "laravel/homestead": "^12"가 포함되어 있는지 확인한 뒤 의존성을 업데이트해야 합니다.

composer update

그다음 vagrant box update 명령어를 사용해 Vagrant box를 업데이트합니다.

vagrant box update

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

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

마지막으로, 최신 Vagrant 설치본을 적용하기 위해 Homestead 가상 머신을 다시 생성해야 합니다.

vagrant up

NOTE

업데이트 과정에서 Homestead.yaml, after.sh, aliases 파일을 덮어쓰면 기존에 직접 수정했던 내용이 사라집니다. 중요한 설정이 있다면 업데이트 전에 미리 백업해 두는 것이 좋습니다.

Homestead

일상적인 사용법

SSH로 접속하기

Homestead 디렉터리에서 vagrant ssh 명령어를 실행하면 가상 머신에 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" 파일을 자동으로 관리하고 있지 않다면, 새로 추가한 사이트를 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 사이트 타입을 사용하면 Statamic 애플리케이션도 쉽게 추가할 수 있습니다.

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 박스로 포트를 추가 포워딩할 수 있습니다. Homestead.yaml 파일을 수정한 후에는 vagrant reload --provision 명령어로 반드시 다시 프로비저닝해야 합니다.

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

아래는 호스트 머신에서 Vagrant 박스로 매핑하면 유용한 Homestead 서비스 포트 목록입니다.

  • 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 버전을 지정할 수 있습니다. 사용 가능한 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

Homestead 가상 머신 내부에서 다음 명령어를 실행하면 CLI에서 기본으로 사용할 PHP 버전을 변경할 수 있습니다.

php56php70php71php72php73php74php80php81php82php83

데이터베이스 연결하기

MySQL과 PostgreSQL 모두 기본적으로 homestead라는 데이터베이스가 미리 구성되어 있습니다. 호스트 머신의 데이터베이스 클라이언트에서 MySQL이나 PostgreSQL에 접속하려면 127.0.0.1의 33060번(MySQL) 또는 54320번(PostgreSQL) 포트로 연결하면 됩니다. 두 데이터베이스 모두 사용자명과 비밀번호는 homestead / secret입니다.

WARNING

이 비표준 포트들은 호스트 머신에서 데이터베이스에 접속할 때만 사용해야 합니다. Laravel 애플리케이션은 가상 머신 _내부_에서 실행되므로, database 설정 파일에서는 기본 포트인 3306(MySQL), 5432(PostgreSQL)를 그대로 사용해야 합니다.

데이터베이스 백업

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

backup: true

이렇게 설정하면 vagrant destroy 명령어를 실행할 때 Homestead가 데이터베이스를 .backup/mysql_backup, .backup/postgres_backup 디렉터리로 자동 내보냅니다. 이 디렉터리들은 Homestead를 설치한 폴더, 혹은 프로젝트별 설치 방식을 사용 중이라면 프로젝트 루트에서 찾을 수 있습니다.

크론 스케줄 설정하기

Laravel은 크론 작업을 스케줄링할 수 있는 편리한 방법을 제공합니다. 방법은 간단한데, schedule:run이라는 단 하나의 Artisan 명령어만 매분 실행되도록 등록해 두면 됩니다. 이 schedule:run 명령어가 routes/console.php 파일에 정의된 스케줄을 확인해서 실행할 작업을 판단합니다.

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

Mailpit을 설정한 뒤에는 http://localhost:8025에서 Mailpit 대시보드에 접속할 수 있습니다.

Minio 설정하기

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

minio: true

기본적으로 Minio는 9600번 포트에서 동작합니다. http://localhost:9600으로 접속하면 Minio 제어판을 사용할 수 있습니다. 기본 액세스 키는 homestead, 기본 시크릿 키는 secretkey입니다. Minio를 사용할 때는 항상 리전을 us-east-1로 지정해야 합니다.

Minio를 사용하려면 .env 파일에 다음 옵션들이 설정되어 있어야 합니다.

AWS_USE_PATH_STYLE_ENDPOINT=true AWS_ENDPOINT=http://localhost:9600 AWS_ACCESS_KEY_ID=homestead AWS_SECRET_ACCESS_KEY=secretkey AWS_DEFAULT_REGION=us-east-1

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 가상 머신에 접속한 다음, share homestead.test 명령어를 실행하세요. 이 명령어는 Homestead.yaml 설정 파일에 정의된 homestead.test 사이트를 외부에 공유합니다. homestead.test 자리에는 설정된 다른 사이트 이름을 넣어도 됩니다.

share homestead.test

명령어를 실행하면 Ngrok 화면이 나타나면서 활동 로그와 함께 공유된 사이트에 외부에서 접속할 수 있는 공개 URL이 표시됩니다. 특정 리전이나 서브도메인 등 Ngrok 실행 옵션을 커스터마이징하고 싶다면 share 명령어에 다음과 같이 옵션을 추가하면 됩니다.

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

HTTP가 아닌 HTTPS로 콘텐츠를 공유해야 한다면, share 대신 sshare 명령어를 사용하면 됩니다.

WARNING

Vagrant는 기본적으로 보안에 취약한 구조라는 점을 기억하세요. share 명령어를 실행하는 순간 가상 머신이 인터넷에 그대로 노출됩니다.

Homestead

Xdebug를 이용한 웹 요청 디버깅

Homestead는 Xdebug를 이용한 스텝 디버깅(step debugging)을 지원합니다. 예를 들어 브라우저에서 특정 페이지에 접속하면 PHP가 IDE와 연결되어, 실행 중인 코드를 실시간으로 들여다보거나 값을 수정하는 등의 작업이 가능해집니다.

Xdebug는 기본적으로 이미 실행 중이며 연결을 받아들일 준비가 되어 있습니다. CLI에서 Xdebug를 활성화해야 한다면 Homestead 가상 머신 안에서 sudo phpenmod xdebug 명령을 실행하세요. 그다음 사용 중인 IDE의 안내에 따라 디버깅 기능을 활성화하고, 브라우저 확장 프로그램이나 북마클릿을 이용해 Xdebug를 트리거하도록 브라우저를 설정하면 됩니다.

WARNING

Xdebug가 활성화되어 있으면 PHP 실행 속도가 눈에 띄게 느려집니다. Xdebug를 비활성화하려면 Homestead 가상 머신 안에서 sudo phpdismod xdebug를 실행한 뒤 FPM 서비스를 재시작하세요.

Xdebug 자동 시작 설정

웹 서버로 요청을 보내는 기능 테스트(functional test)를 디버깅할 때는, 디버깅을 트리거하기 위해 매번 테스트 코드에 커스텀 헤더나 쿠키를 추가하는 것보다 Xdebug가 자동으로 시작되도록 설정하는 편이 훨씬 편리합니다. 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를 제공하며, 개발·스테이징·운영 환경 어디에서나 최종 사용자에게 성능 부담을 주지 않으면서 사용할 수 있도록 설계되었습니다. 또한 Blackfire는 코드와 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 계정이 필요합니다. Blackfire는 CLI 도구와 브라우저 확장 프로그램 등 애플리케이션을 프로파일링할 수 있는 다양한 방법을 제공합니다. 자세한 내용은 Blackfire 공식 문서를 참고하세요.

Homestead

네트워크 인터페이스 설정

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 옵션을 추가하면 됩니다. 기본 dev 값은 eth0입니다.

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

NOTE

사내 네트워크 정책이나 사용 중인 Wi-Fi 어댑터 이름은 macOS, Windows, Linux 환경마다 다를 수 있습니다. bridge 값에 지정해야 하는 정확한 인터페이스 이름은 VBoxManage list bridgedifs 명령어(VirtualBox 기준)로 확인할 수 있습니다.

Homestead

Homestead 확장하기

Homestead 디렉터리 최상단에 있는 after.sh 스크립트를 사용하면 Homestead를 확장할 수 있습니다. 이 파일 안에 가상 머신을 여러분의 필요에 맞게 설정하고 커스터마이징하는 데 필요한 셸 명령어를 자유롭게 추가하면 됩니다.

Homestead를 커스터마이징하다 보면, Ubuntu가 패키지의 기존 설정 파일을 그대로 유지할지 아니면 새로운 설정 파일로 덮어쓸지 물어보는 경우가 있습니다. 이런 프롬프트가 뜨는 것을 방지하고 Homestead가 이미 작성해 둔 설정을 덮어쓰지 않으려면, 패키지를 설치할 때 다음과 같은 명령어를 사용하세요:

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

사용자별 커스터마이징

팀 단위로 Homestead를 함께 사용하다 보면, 각자의 개발 스타일에 맞게 Homestead를 조금씩 다르게 조정하고 싶을 수 있습니다. 이럴 때는 Homestead.yaml 파일이 위치한 Homestead 디렉터리 최상단에 user-customizations.sh 파일을 만들면 됩니다. 이 파일 안에는 원하는 커스터마이징 내용을 자유롭게 작성할 수 있습니다. 다만 user-customizations.sh 파일은 팀 전체가 공유하는 설정이 아니라 개인용 설정이므로, 버전 관리(Git 등)에는 포함시키지 않아야 합니다.

Homestead

Provider Specific Settings

VirtualBox

natdnshostresolver

Homestead는 기본적으로 natdnshostresolver 설정을 on으로 지정합니다. 이 설정 덕분에 Homestead는 호스트 운영체제의 DNS 설정을 그대로 사용할 수 있습니다. 만약 이 동작 방식을 변경하고 싶다면, Homestead.yaml 파일에 다음 설정을 추가하세요.

provider: virtualbox natdnshostresolver: 'off'

NOTE

사내 프록시나 사설 DNS 서버를 사용하는 개발 환경에서는 이 옵션을 off로 바꿔야 정상적으로 네트워크가 동작하는 경우가 있습니다. 접속이 원활하지 않다면 이 설정을 가장 먼저 점검해 보세요.

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

번역일: 2026년 9월 26일