1## Using Vagrant with phpBB
2
3phpBB includes support for Vagrant. This allows developers and contributors to run phpBB without the need to set up their own local web server with traditional WAMP/MAMP stacks. It also provides a consistent environment between developers for writing and debugging code changes more productively.
4
5phpBB uses the [Laravel/Homestead](https://laravel.com/docs/5.1/homestead) Vagrant box. It runs a Linux server with Ubuntu 14.04, PHP 5.6, Nginx, SQLite3, MySQL, and a whole lot more (complete specs below).
6
7## Get Started
8
9* Download and Install [Vagrant](https://www.vagrantup.com/downloads.html)
10* Download and Install [VirtualBox](https://www.virtualbox.org/wiki/Downloads)
11* Run `vagrant up` from the root of your cloned fork of the phpBB Git repository
12
13```sh
14$ vagrant up
15```
16
17* Access phpBB at `http://192.168.10.10/`
18* Username: **admin**
19* Password: **adminadmin**
20
21## Additional commands:
22* Access your Linux server from the command line:
23
24```sh
25$ vagrant ssh
26```
27
28* Pause your server:
29
30```sh
31$ vagrant suspend
32```
33
34* Shut down your server:
35
36```sh
37$ vagrant halt
38```
39
40* Delete and remove your server:
41
42```sh
43$ vagrant destroy
44```
45
46> Note: destroying the vagrant server will remove all traces of the VM from your computer, reclaiming any disk space used by it. However, it also means the next time you vagrant up, you will be creating a brand new VM with a fresh install of phpBB and a new database.
47
48## Customising the phpBB configuration
49
50By default, phpBB is pre-configured to install with a MySQL database. You can, however, switch to PostegreSQL or SQLite3 by editing the `phpbb-install-config.yml` file in the vagrant directory. The next time you run `vagrant up` (or `vagrant provision`) it will be installed under the new configuration.
51
52If you prefer to access phpBB from the more friendly URL `http://phpbb.app` then you must update your computer's hosts file. This file is typically located at `/etc/hosts` for Mac/Linux or `C:\Windows\System32\drivers\etc\hosts` for Windows. Open this file and add the following line to it, at the very bottom, and save.
53
54```
55192.168.10.10  phpbb.app
56```
57
58## How it all works
59
60When you vagrant up, the Laravel/Homestead box is transparently loaded as a Virtual Machine on your computer (this may take several minutes the very first time while it downloads the VM image to your computer). Your local phpBB repository clone is mirrored/shared with the VM, so you can work on the phpBB code on your computer, and see the changes immediately when you browse to phpBB at the URL provided by the VM.
61
62This is very similar to traditional methods of working with a local WAMP/MAMP stack, except the webserver is now being provided by a VM of a Linux server. The advantages here are the exact same Linux server environment is being used by everybody who uses Vagrant with phpBB, so there will be consist behaviour unlike when everybody is developing on different versions of PHP, server configurations, etc.
63
64The environment is also "sandboxed" from your system. This means you don't need to worry about adjusting your own computer's internal PHP settings, setting up databases, or doing damage to your system or to phpBB. Other than the phpBB codebase, which lives on your computer, all execution is taking place within the VM and you can at any time, halt or destroy the VM and start a brand new one.
65
66There are some caveats, however. You can only run one vagrant VM for the phpBB repository. And of course, the database will be destroyed when you vagrant destroy. If the database is important, you should SSH into your vagrant VM and export/import the DB as needed using SSH commands.
67
68For example, to export/import a MySQL database (using phpBB's `store` directory):
69
70SSH into the VM
71
72```sh
73$ vagrant ssh
74```
75
76Export MySQL:
77
78```sh
79$ mysqldump -uhomestead -psecret phpbb > /home/vagrant/phpbb/phpBB/store/phpbb.sql
80```
81
82Import MySQL:
83
84```sh
85$ mysql -uhomestead -psecret phpbb < /home/vagrant/phpbb/phpBB/store/phpbb.sql
86```
87
88---
89
90## About the Laravel/Homestead box
91
92### Included Software
93
94* Ubuntu 14.04
95* Git
96* PHP 5.6
97* HHVM
98* Nginx
99* MySQL
100* Sqlite3
101* Postgres
102* Composer
103* Node (With PM2, Bower, Grunt, and Gulp)
104* Redis
105* Memcached
106* Beanstalkd
107* Blackfire Profiler
108
109### MySQL Access
110
111- Hostname: 127.0.0.1
112- Username: homestead
113- Password: secret
114- Database: phpbb
115- Port: 3306
116
117### PostgreSQL Access
118
119- Hostname: 127.0.0.1
120- Username: homestead
121- Password: secret
122- Database: phpbb
123- Port: 5432
124