|
1 | | -To make future Drupal VM updates easier to integrate with an existing project, you might consider the more complex setup of installing Drupal VM as a `composer` dependency. Using a delegating `Vagrantfile` you are able to run `vagrant` commands anywhere in your project as well as separate your custom configuration files from Drupal VM's own files. |
| 1 | +If you're setting up a new project you can get up and running quickly using [drupal-composer/drupal-project](https://github.com/drupal-composer/drupal-project) as a project template. |
2 | 2 |
|
3 | | -### Add Drupal VM as a Composer dependency |
4 | | - |
5 | | -Add Drupal VM as a development dependency to your `composer.json`. |
6 | | - |
7 | | -``` |
8 | | -composer require --dev geerlingguy/drupal-vm |
9 | | -``` |
10 | | - |
11 | | -### Setup your configuration files |
12 | | - |
13 | | -Add and configure the `config.yml` anywhere you like, in this example we place it in a `config/` directory. |
14 | | - |
15 | | -_Note: This will be the directory where Drupal VM looks for other local configuration files as well. Such as `drupal_build_makefile` and `local.config.yml`._ |
16 | | - |
17 | | -``` |
18 | | -├── composer.json |
19 | | -├── config/ |
20 | | -│ ├── config.yml |
21 | | -│ ├── local.config.yml |
22 | | -│ └── Vagrantfile.local |
23 | | -├── docroot/ |
24 | | -│ ├── ... |
25 | | -│ └── index.php |
26 | | -└── vendor/ |
27 | | - ├── ... |
28 | | - └── geerlingguy/ |
29 | | - └── drupal-vm/ |
30 | | -``` |
31 | | - |
32 | | -Change the [build strategy to use your `composer.json`](composer.md#using-composer-when-drupal-vm-is-a-composer-dependency-itself) file by setting: |
33 | | - |
34 | | -```yaml |
35 | | -drupal_build_composer_project: false |
36 | | -drupal_build_composer: true |
37 | | -drupal_composer_path: false |
38 | | -drupal_composer_install_dir: "/var/www/drupalvm" |
39 | | -drupal_core_path: "{{ drupal_composer_install_dir }}/docroot" |
40 | | -``` |
41 | | -
|
42 | | -If you intened to use the devel module, it must be added as a requirement to your `composer.json` file. Alternatively, if you do not intend to use it remove it from `drupal_enabled_modules` in your `config.yml` file: |
43 | | - |
44 | | -```yaml |
45 | | -drupal_enabled_modules: [] |
46 | | -``` |
47 | | - |
48 | | -If you're using `pre_provision_scripts` or `post_provision_scripts` you also need to adjust their paths to take into account the new directory structure. The examples used in `default.config.yml` assume the files are located in the Drupal VM directory. You can use the `config_dir` variable which is the absolute path of the directory where your `config.yml` is located. |
49 | | - |
50 | | -```yaml |
51 | | -post_provision_scripts: |
52 | | - # The default provided in `default.config.yml`: |
53 | | - - "../../examples/scripts/configure-solr.sh" |
54 | | - # With Drupal VM as a Composer dependency: |
55 | | - - "{{ config_dir }}/../examples/scripts/configure-solr.sh" |
56 | | -``` |
57 | | -
|
58 | | -### Create a delegating `Vagrantfile` |
59 | | - |
60 | | -Create a delegating `Vagrantfile` that will catch all your `vagrant` commands and send them to Drupal VM's own `Vagrantfile`. Place this file in your project's root directory. |
61 | | - |
62 | | -```ruby |
63 | | -# The absolute path to the root directory of the project. Both Drupal VM and |
64 | | -# the config file need to be contained within this path. |
65 | | -ENV['DRUPALVM_PROJECT_ROOT'] = "#{__dir__}" |
66 | | -# The relative path from the project root to the config directory where you |
67 | | -# placed your config.yml file. |
68 | | -ENV['DRUPALVM_CONFIG_DIR'] = "config" |
69 | | -# The relative path from the project root to the directory where Drupal VM is located. |
70 | | -ENV['DRUPALVM_DIR'] = "vendor/geerlingguy/drupal-vm" |
71 | | -
|
72 | | -# Load the real Vagrantfile |
73 | | -load "#{__dir__}/#{ENV['DRUPALVM_DIR']}/Vagrantfile" |
74 | | -``` |
75 | | - |
76 | | -When you issue `vagrant` commands anywhere in your project tree this file will be detected and used as a delegator for Drupal VM's own Vagrantfile. |
77 | | - |
78 | | -Your project structure should now look like this: |
79 | | - |
80 | | -``` |
81 | | -├── Vagrantfile |
82 | | -├── composer.json |
83 | | -├── config/ |
84 | | -│ ├── config.yml |
85 | | -│ ├── local.config.yml |
86 | | -│ └── Vagrantfile.local |
87 | | -├── docroot/ |
88 | | -│ ├── ... |
89 | | -│ └── index.php |
90 | | -└── vendor/ |
91 | | - ├── ... |
92 | | - └── geerlingguy/ |
93 | | - └── drupal-vm/ |
| 3 | +```sh |
| 4 | +composer create-project drupal-composer/drupal-project:8.x-dev <some-dir> --stability dev --no-interaction |
94 | 5 | ``` |
95 | 6 |
|
96 | | -### Provision the VM |
97 | | - |
98 | | -Finally provision the VM using the delegating `Vagrantfile`. |
| 7 | +### Add Drupal VM as a Composer dependency |
99 | 8 |
|
100 | | -```sh |
101 | | -vagrant up |
102 | | -``` |
| 9 | +Require Drupal VM as a development dependency to your project. |
103 | 10 |
|
104 | | -_Important: you should never issue `vagrant` commands through Drupal VM's own `Vagrantfile` from now on. If you do, it will create a secondary VM in that directory._ |
| 11 | + composer require --dev geerlingguy/drupal-vm |
105 | 12 |
|
106 | | -## Drupal VM in a subdirectory without composer |
| 13 | +_This command will scaffold a `Vagrantfile` in the root of your project. Feel free to add it to your `.gitignore` as the file is now managed by Drupal VM and will be reset each time you run `composer update`._ |
107 | 14 |
|
108 | | -If you're not using `composer` in your project you can still download Drupal VM (or add it as a git submodule) to any subdirectory in your project. As an example let's name that directory `box/`. |
| 15 | +### Create a `config.yml` to configure the VM |
109 | 16 |
|
110 | | -``` |
111 | | -├── docroot/ |
112 | | -│ ├── ... |
113 | | -│ └── index.php |
114 | | -└── box/ |
115 | | - ├── ... |
116 | | - ├── default.config.yml |
117 | | - └── Vagrantfile |
118 | | -``` |
| 17 | +Create and configure a config.yml file, eg. in `vm/config.yml`. You'll need at least the following variables: |
119 | 18 |
|
120 | | -Configure your `config.yml` as mentioned in the [`composer` section](#setup-your-configuration-files) above. |
| 19 | + # Change the build strategy to use a composer.json file. |
| 20 | + drupal_build_composer: true |
| 21 | + drupal_build_composer_project: false |
121 | 22 |
|
122 | | -```yaml |
123 | | -post_provision_scripts: |
124 | | - # The default provided in `default.config.yml`: |
125 | | - - "../../examples/scripts/configure-solr.sh" |
126 | | - # With Drupal VM in a toplevel subdirectory |
127 | | - - "{{ config_dir }}/../examples/scripts/configure-solr.sh" |
128 | | -``` |
| 23 | + # Tell Drupal VM that the composer.json file already exists and doesn't need to be transfered. |
| 24 | + drupal_composer_path: false |
129 | 25 |
|
130 | | -Your directory structure should now look like this: |
| 26 | + # Set the location of the composer.json file and Drupal core. |
| 27 | + drupal_composer_install_dir: "/var/www/drupalvm" |
| 28 | + drupal_core_path: "{{ drupal_composer_install_dir }}/web" |
131 | 29 |
|
132 | | -``` |
133 | | -├── Vagrantfile |
134 | | -├── config/ |
135 | | -│ ├── config.yml |
136 | | -│ ├── local.config.yml |
137 | | -│ └── Vagrantfile.local |
138 | | -├── docroot/ |
139 | | -│ ├── ... |
140 | | -│ └── index.php |
141 | | -└── box/ |
142 | | - ├── ... |
143 | | - ├── default.config.yml |
144 | | - └── Vagrantfile |
145 | | -``` |
| 30 | +_Note that `drupal_core_path` needs to match your `composer.json` configuration. `drupal-project` uses `web/` whereas Lightning and BLT uses `docroot/`_ |
146 | 31 |
|
147 | | -Provision the VM using the delegating `Vagrantfile`. |
| 32 | +If you placed the `config.yml` file in a subdirectory, tell Drupal VM where by adding the location to your `composer.json`. If not, Drupal VM will look for all configuration files in the root of your project. |
148 | 33 |
|
149 | | -```sh |
150 | | -vagrant up |
151 | | -``` |
| 34 | + composer config extra.drupalvm.config_dir 'vm' |
0 commit comments