README

Hab(itat) is a virtual development environment bootstrapper for setting up and configuring a guest Vagrant instance. The Vagrant instance includes all development dependencies to run Deskpro and develop against it. Hab is designed for Linux and MacOS host machines.

Installation

Please install both Vagrant and VirtualBox before using Hab.

Hab is packaged as a .phar and is used to bootstrap the virtual development infrastructure from within the Deskpro project.

Download the latest version hab.phar and place it within the root of your Deskpro project directory.

"Quick" Start Guide (Linux & MacOS)

Install Vagrant and VirtualBox on your computer
Clone the Deskpro repository
Go to the Deskpro project root and download Hab to this location
Initialise and update Git submodules by running git submodule init && git submodule update
Run php ./hab.phar init to initialise Vagrant and provisioning scripts
Run vagrant up
Run vagrant ssh to access the virtual machine
Download and install Composer globally on the virtual machine
Run cd /var/www/deskpro/app/BUILD
Run composer install -o
Run cd /var/www/deskpro/www/assets/BUILD/web
Run npm install (this could take a while)
Run bower install --config.interactive=false --allow-root
Run npm run gulp
Run cd /var/www/deskpro/www/assets/BUILD/pub
Run npm install (this could take a while)
Run ASSET_SERVER_HOSTNAME=deskpro.local npm run dev to start the asset server
In another terminal on the host machine (your computer)
Run vagrant ssh to access the virtual machine as another session
Run bin/install --install-source dev to install Deskpro, when prompted:
- enter the project URL "http://deskpro.local/"
- enter "127.0.0.1" as the database hostname and "root" as both the database username and password. The database name is "deskpro"
Check that the asset_paths are pointed to deskpro.local:9666 in config/config.paths.php
Add the following line to the bottom of config/advanced/config.settings.php:

$SETTINGS['DESKPRO_APP_ASSETS_URL'] = 'http://deskpro.local/assets/BUILD/pub/build/';

You should now be able to access Deskpro via http://deskpro.local/

Usage

To initialise the Vagrantfile, settings and provisioning scripts, run the init command:

$ php hab.phar init

This will install the necessary files ready to start your virtual machine using the standard Vagrant commands:

$ vagrant up && vagrant ssh

You can pass along several options to adjust the virtual machine instance settings that are subsequently stored in the hab.json file.

php hab.phar init \
    --project-dir /path/to/project/dir \
    --hostname deskpro.local \
    --ip 192.168.2.34 \
    --memory 2048 \
    --cpus 4 \
    --force

The options are as follows:

project-dir - The location of your Deskpro project directory, default is current directory
hostname - Hostname of the VM, default is deskpro.local
ip - Private IP address of the guest VM, default is 10.40.1.23
memory - How much memory (in megabytes) is allocated to the VM, default is 4096
cpus - How many CPUs the VM has, default is 2
force - Force an overwrite of the hab bootstrap files, default is false

After Hab has been initialised you should exclude the following files from version control (usually by adding to a .gitignore file):

/.vagrant
/.hab
/hab.phar
/hab.json
/Vagrantfile

Once the VM is booted, you can then SSH into it and run the usual installation and setup scripts as described in the Deskpro setup instructions.

Note: When running the dev assets server, do the following to override the default hostname:

$ ASSET_SERVER_HOSTNAME=deskpro.local npm run dev

Assets server env. variables are as follows:

ASSET_SERVER_HOSTNAME - Override the asset server hostname (default is localhost)
ASSET_SERVER_PORT - Override the asset server port (default is 9666)

Note: To run the Deskpro test suite you will need to configure the application to use --login-path option for things like mysqldump, etc. as this will suppress the "password in command prompt is insecure" warnings. This is done by adding the --login-path=local option to the test configuration database parameters (after copying the .dist config):

# app/BUILD/tests/config/config.all.php

// ...

$CONFIG['database'] = [
    'host'     => '127.0.0.1',
    'user'     => 'root',
    'password' => 'root',
    'dbname'   => $dbName.$dbPostfix,
    'login-path' => 'local', // Append this parameter
];

// ...

Default Service Connectivity

MySQL DSN: mysql://root:root@deskpro.local:3306/deskpro
Elasticsearch URL: http://deskpro.local:9200/ (requires service start)

Updating

The hab.phar package may be self updated using the following command:

$ php hab.phar self-update

After updating, you'd usually want to force initialise the modified bootstrap files:

$ php hab.phar init --force

Testing

You may run the Hab functional test suite using the following:

$ composer install
$ vendor/bin/phpunit -c .

ashleydawson / deskpro-hab

Maintainers

Details