1_1_Setup development environment - OpenISDM/VMS GitHub Wiki

Overview

There are two ways that we recommend to built the development environment, Docker and Homestead. You can choose one of them to setup.

For Docker

[To be continue...]

For Homestead

Laravel provides Homestead to build a local development environment easily. You can get further information from the Laravel Documentation.

Docker

Introduction

The section introduces to setup a development environment by Docker (1.12 above). It uses Dockerfile and Docker Compose to build the environment. The Dockerfile provides quick building Docker images and the Docker Compose simplys to launch Docker containers.

Installation for Windows (Docker Toolbox)

Prerequirements

Windows OS must disable the Hyper-v.

Steps

  1. Please download Docker Toolbox 1.12 above from https://github.com/docker/toolbox/releases.

  2. Click to install the DockerToolbox-XXX.exe.

  3. Open the Docker Quickstart Terminal from desktop. (If you lauch at first time, it may take for a while.)

Installation for Mac (Docker for Mac)

(To Be Continued...)

Building Docker images and containers (For general)

Steps

  1. Clone the project from Github

  2. Go to the git repository on local directory: cd VMS_GIT_REPOSITORY_PATH. (The VMS_GIT_REPOSITORY_PATH is the git repository location)

  3. Create a new .env file from .env.example in the repository and set correct environment variables

  4. To build a new Docker image, Execute docker-compose build in the git repository. (If you already built the image, you can ignore this step)

  5. To launch a Docker container, execute docker-compose up -d in the git repository.

  6. To make sure the Docker container is running, execute docker-compose ps and docker ps. You will see the following result:

  Name                 Command               State                        Ports
----------------------------------------------------------------------------------------------------
vms_web_1   /bin/bash -c /usr/bin/supe ...   Up      3306/tcp, 443/tcp, 6379/tcp, 0.0.0.0:80->80/tcp

FAQ

How to migrate the database in Docker container?

For Windows:

List running containers:

$ docker ps
CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                                             NAMES
57610cb0b0c8        vms_web             "/bin/bash -c /usr/bi"   22 minutes ago      Up 22 minutes       443/tcp, 3306/tcp, 0.0.0.0:80->80/tcp, 6379/tcp   vms_web_1

Enter the container by CONTAINER ID:

$ docker exec -ti 57610cb0b0c8 bash
root@57610cb0b0c8:/var/www/html/app# composer install ; scripts/deploy.sh

For Mac or Linux:

Run the following command in the git repository directory:

$ docker-compose exec web composer install ; scripts/deploy.sh

Homestead

Introduction

This section will describe how to setup a development environment by Homestead. Homestead is an official Vagrant box that provides you a Laravel development environment quickly.

Install Virtualbox & Vagrant

We mentioned that Homestead is an Vagrant box previously. Since Vagrant helps you manage virtual machine, you must install Virtualbox or VMWare.

Here it demonstrate on Virtualbox.

Please download Virtualbox 5.X and Vagrant for you operating system.

Prerequirements

The development environment includes PHP 5.6 above or PHP 7, Git and Composer

Install Composer

On the terminal, use the following command is for installing Composer. Composer is a tool for managing PHP packages.

$ curl -sS https://getcomposer.org/installer | php
$ mv composer.phar /usr/local/bin/composer

Configure composer environment

Open the ~/.bash_profile to add the following content:

export PATH="~/.composer/vendor/bin:$PATH"

Reload the script

$ source ~/.bash_profile

Install Homestead Vagrant Box

After installing Virtualbox and Vagrant, you have to download the Homestead Vagrant box.

$ vagrant box add laravel/homestead

Install Homestead tool

In your home directory, you need to clone the Hoemstead repository.

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

Once you have cloned the repository into home directory, execute the script file in Homestead directory.

$ cd ~/Homestead
$ bash init.sh

$ composer global require laravel/homestead --dev
$ composer global install

Configure Homestead

Generate and set SSH key

First, you can generate SSH key pair. Once you have generated a SSH key, configure the public key path in Homestead.yml.

$ ssh-keygen -t rsa -C "you@homestead"

Clone source code

Clone the forked repository into your local.

$ cd ~
$ git clone [email protected]:USERNAME/VMS.git

Create a homestead.yaml

$ homestead make

It creates a Homestead.yaml file in the project. If you want to configure the Homestead, you have to edit the file.

Configure Nginx sites

Homestead also creates nginx sites by the sites property. The sites property allows you to easily map domain name to homestead virtual machine path.

sites:
    - map: vms.app
      to: /home/vagrant/VMS/public
      hhvm: true

Set hosts file

If your operating system is Windows, the hosts file is located at C:\Windows\System32\drivers\etc\hosts. Other operating systems, eg. Mac or Linux, the file is located at /etc/hosts. Add a new line in hosts file:

192.168.10.10  vms.app

After setting the hosts file, make sure the vms.app domain name and IP are correct. Open your browser to access http://vms.app

Launch Homestead

Once you have configured Homestead, you can launch homestead virtual machine in your project.

$ vagrant up

Setup environment variables

UNFINISH

There is an example environment variables file, .env.example in root of the repository. You can copy it into a new file name and edit it.

$ cp .env.example .env

Run database migrations

Once you have set the environment variables, you can migrate database in Homestead virtual machine.

$ sh scripts/deploy.sh