Getting Started with Development ¶

This guide shows you the minimal steps required run an emergence project locally, make changes to it, and see the result.

In this article ¶

Introduction
Prerequisites
Clone Project via Git
Launch Studio via Habitat
Start Runtime and Build Project
Load Fixture Data (optional)
Create User Account (optional)
Running Tests

Introduction ¶

Prerequisites ¶

Before you begin, you’ll need Docker and Habitat set up on your workstation:

Install Docker

On Mac and Windows workstations, Docker must be installed to use habitat. On Linux, Docker is optional.

- Download Docker for Mac - Download Docker for Windows - Install Docker on Ubuntu
Install Chef Habitat on your system

Chef Habitat is a tool for automating all the build and runtime workflows for applications, in a way that behaves consistently across time and environments. An application automated with Habitat can be run on any operating system, connected to other applications running locally or remotely, and deployed to either a container, virtual machine, or bare-metal system.

Installing Habitat only adds one binary to your system, hab, and initializes the /hab tree.
```
curl -s https://raw.githubusercontent.com/habitat-sh/habitat/master/components/hab/install.sh | sudo bash
hab --version # should report 0.85.0 or newer
```
Configure the hab client for your user

Setting up Habitat will interactively ask questions to initialize ~/.hab.

This command must be run once per user that will use hab:
```
hab setup
```

Clone Project via Git ¶

In this example, the slate-cbl project is cloned, but you might use any repository/branch containing an emergence project:

git clone --recursive -b develop git@github.com:SlateFoundation/slate-cbl.git

The --recursive option is used so that any submodule repositories are also cloned.

Launch Studio via Habitat ¶

Change into project’s cloned directory
```
cd ./slate-cbl
```
Launch Studio

On any system, launch a studio with:
```
HAB_DOCKER_OPTS="-p 7080:80 -p 3306:3306 --name emergence-studio" \
    hab studio enter -D
```
The HAB_DOCKER_OPTS environment variable here allows you to use any options supported by docker run, in this case forwarding ports for the web server and MySQL server from inside the container to your host machine.

Review the notes printed to your terminal at the end of the studio startup process for a list of additional commands provided by your project’s .studiorc

Start Runtime and Build Site ¶

Ensure that the Supervisor is finished starting up in the background

As documented in your terminal right before your studio prompt, the Habitat studio has launched a Supervisor for you and set up a shortcut command to follow its log. This log contains the output for the Supervisor and any background services we load into it. Your Supervisor should be done downloading and starting by the time you type anything, but you can check by running sup-log and ensure you see these last lines look like this:
```
# sup-log
...
hab-sup(MR): Starting gossip-listener on 0.0.0.0:9638
hab-sup(MR): Starting ctl-gateway on 127.0.0.1:9632
hab-sup(MR): Starting http-gateway on 0.0.0.0:9631
```
If you still see packages downloading and installing instead, wait until that finishes. Press Ctrl+C to stop following the log and return to your prompt.

You can further confirm that the Supervisor is ready and see the status of any loaded services at any time by running hab svc status:
```
# hab svc status
No services loaded.
```
Start environment services

Use the Emergence Studio command start-all to launch and bind all the required services for loading an Emergence site: the http server (nginx), the application runtime (php-fpm+app bootloader), and a local mysql server:
```
start-all
```
At this point, you should be able to open localhost:7080 and see the error message Page not found.
Build environment

To build the entire environment and load it, use the studio command update-site:
```
update-site
```
At this point, localhost:7080 should display the current build of the site

Load Fixture Data (optional) ¶

# clone fixture branch into git-ignored .data/ directory
git clone -b cbl/competencies https://github.com/SlateFoundation/slate-fixtures.git .data/fixtures

# load all .sql files from fixture
cat .data/fixtures/*.sql | load-sql -

Create User Account (optional) ¶

Enable user registration form (optional)

If your project has registration disabled by default, you might want to enable it so you can register:

# write class configuring enabling registration
mkdir -p php-config/Emergence/People
echo '<?php Emergence\People\RegistrationRequestHandler::$enableRegistration = true;' > php-config/Emergence/People/RegistrationRequestHandler.config.php

# rebuild environment
update-site

Promote registered user to developer (optional)

After visiting /register and creating a new user account, you can use the studio command promote-user to upgrade the user account you just registered to the highest access level:
```
promote-user <myuser>
```

After editing code in the working tree, run the studio command update-site to rebuild and update the environment. A watch-site command is also available to automatically rebuild and update the environment as changes are made to the working tree.

Running Tests ¶

Cypress is used to provide browser-level full-stack testing. The package.json file at the root of the repository specifies the dependencies for running the test suite and all the configuration/tests for Cypress are container in the cypress/ tree at the root of the repository.

To get started, from a terminal outside the studio in the root of the repository:

# install development tooling locally
npm install

# launch cypress app
npm run cypress:open