Link Search Menu Expand Document
NHM DEV DOCS
Tutorials
This site uses Just the Docs, a documentation theme for Jekyll.

Setting up a local development environment

Authored by: Daniel Markbreiter
Table of Contents

Setting up a local development environment

Because of the relatively complex local build for NHMLAC, setting up its local development environment is a lengthy process (6-8 hours).

This installation guide is written for Intel based machines running macOS. While most of the required software is compatible with other platforms and hardware, they often require different or additional steps.

Preinstallation requirements

  1. Check to see if macOS is up todate

    It is best practice to use the latest version of macOS. To check if there are updates click on the Apple icon in the menu bar About this Mac > Software Update > Update Now.

  2. Install xcode-select

    You can check to see if xcode-select is installed by running xcode-select --version.

    xcode-select --install

GitHub configuration

Create and add a new SSH key

If you already have an available SSH key, skip to step 6. A detailed overview of how to add SSH keys to a GitHub can be found in GitHub’s SSH key documentation.

Pantheon does not support the ed25519 algorithim — use the rsa one isntead.

  1. Open Terminal

  2. Create a new SSH key with your GitHub email

    ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

  3. When prompted with “Enter a file in which to save the key,” press Enter. This accepts the defauly file location.

  4. At the prompt (below), type a secure passphrase.

    > Enter passphrase (empty for no passphrase): [Type a passphrase]
> Enter same passphrase again: [Type passphrase again]

  5. Copy the SSH key to your clipboard with the following command

    pbcopy < ~/.ssh/id_rsa.pub

  6. Go to the nhmla Account (thumbnail) > Settings > SSH and GPG Keys

  7. Select New SSH key or Add SSH key

  8. Paste it into the GitHub SSH and GPG Key field

  9. Click Add SSH key

Generate GitHub PAT

GitHub requires the use of token-based authentification for all authentificated Git operations. Instead of using a your GitHub password to perform an operation such as a git push, a personal access token (PAT), is now required when prompted for a password. A detail description on how to create a PAT can be found on GitHub “Creating a personal access token” page.

  1. Click on your profile photo and then click Settings
  2. In the left sidebar click Developer settings
  3. In the left sidebar, click Personal access tokens
  4. Click Generate new token
  5. Give your token a descriptive name
  6. Select al scopes and permissions (click all the checkboxes)
  7. Click Generate token

Clone git project

  1. Open terminal

  2. Navigate to the location where you want the cloned directory.

    cd <directory/path/>

  3. Clone project to your current working directory

    git clone https://github.com/naturalhistorymuseumofla/nhmla.git

Install build tools

  1. Install homebrew

    Follow these steps for a detailed explanation of how to install Homebrew or enter the following into terminal:

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  2. Install node.js

    There a multiple ways to install node.js. The three most popular ways are outlined in this article. While the easiest way is by using brew (using the command below), using nvm (node version manager) to install node is suggested for better version control.

    brew install node

    To ensure that node was installed properly run the

  3. Install gulp cli

    The gulp command line utility allows for gulp.js to be used in Terminal. Gulp is a node based task runner that automates development tasks (such as compiling sass or minifying code).

    For a comprehensive guide on how to install gulp-cli, consult gulp’s official documentation.

  4. Install composer 1.x

    Composer is both a package and dependency manager for php. It is similar to node’s npm or python’s conda. For more information on how to install composer, consult the official composer documentation.

    1. Download Composer from the official website using the following command: 
         php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
    2. Ensure that the installer file is not corrupt by verifying ints signature (SHA-384) 
      php -r "if (hash_file('sha384', 'composer-setup.php') === 'e0012edf3e80b6978849f5eff0d4b4e4c79ff1609dd1e613307e16318854d24ae64f26d17af3ef0bf7cfb710ca74755a') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
    3. Install version 1.9.1 of Composer locally

      Do not install composer 2.x!

         php composer-setup.php --version=1.9.1
    4. Remove the installer when done: 
      php -r "unlink('composer-setup.php');"

    5. Move the composer.phar into a directory on PATH so it can be called from any location

      sudo mv composer.phar /usr/local/bin/composer

    6. Test if Composer installed correctly

      composer

      The results should be as below:

         ______
  / ____/___  ____ ___  ____  ____  ________  _____
 / /   / __ \/ __ `__ \/ __ \/ __ \/ ___/ _ \/ ___/
/ /___/ /_/ / / / / / / /_/ / /_/ (__  )  __/ /
\____/\____/_/ /_/ /_/ .___/\____/____/\___/_/
                    /_/
Composer version 1.9.1 2019-11-01 17:20:17

  5. Navigate to the root of the nhmla directory

  6. Run composer install. If asked for a token, you can install with the following command:

    config --global --auth github-q.github.com <token>

  7. Install all node dependencies and packages

    npm install

  8. Run gulp

  9. Download the v3.0.23 Lando dmg via the lando releases GitHub page

    Never allow Docker to update itself

    Currently Lando relies on a specific version of Docker, which it manages.

  10. Install Terminus

    Terminus is the CLI for the Pantheon platform. A detailed explanation on how to install Terminus can be found in the Pantheon Terminus Manual.

Setting up Pantheon

  1. Request an invite to Pantheon
  2. Create an account on Pantheon
  3. Go to Pantheon Dashboard > Account > Machine Tokens > Create token
  4. Name your token

  5. Save your Pantheon machine token

    Save your Pantheon machine token somewhere safe!

  6. Enter the terminus command in the popup

Starting the nhmla locally

  1. Receive /sites files

    Another developer will need to send files not included in the git clone. These files are the files besides the default directory in /sites/ and all files in sites/default/ except for the /files directory. This is done as to safeguard the codebase from being downloaded and the site started by developers outside of nhm.

  2. Run lando start and enter ‘y’ when prompted

  3. Run lando composer install

  4. Run npm install

  5. Run gulp

  6. Check to see if additional files are needed

    Files such as development.services.yml and other files might need to be downloaded. These files should be inside the web/sites/ directory next to “default”.

  7. Run lando pull

    As of the writing of this document, lando pull does not properly pull from Pantheon.

    Instead, git pull and manually downloading a database instance from Pantheon can be used as a workaround.

    This will start a pull process on GitHub and retrieve an updated database instance from Pantheon.

    1. The Pantheon Token has to be setup which requires your GitHub credential
    2. Pull everything from dev
    3. If you are stuck at 0% on the progress bar terminate the process with ctrl+c. Try lando rebuild before running lando pull

  8. Manually download a database instance from Pantheon (if lando pull fails)

    1. Download the database directly from Pantheon as a .zip file
    2. Drop the zip file inside the nhmla directory
    3. run lando db-import <name of file>

  9. Run lando drush cim

    This initiates a confirguration import, which is required after a database import.

  10. Run lando drush cr

  11. The project should run

  12. If the website will not start:

    1. Run lando rebuild
    2. Run lando composer install(lando composer self-update --1 if a rollback is required)
    3. Run npm install
    4. Run gulp
    5. Run lando drush cim
    6. Run lando drush cr

Troubleshooting

Composer

  1. Have another developer send a zipped site folder in the web directory in their working nhmla project directory
  2. Download and unzip the copied site folder and use it to replace the web/sites directory.
  3. Delete Docker
    1. Start Activity Monitor by going to Applications > Utilities
    2. Quit any proccesses with “Docker” in their name
    3. Quit Activity Monitor
    4. Locate the Docker app in your Applications folder
    5. Drag the Docker app to Trash and empty it
  4. Once Docker is removed, all associated files installed with Docker will need to be removed as well
    1. In finder, choose Go and select Go to Folder
    2. Paste ~/Library into search bar
    3. Click on the Application Scripts dir and look for “com.docker.helper”
    4. Delete it
    5. Navigate to the Containers dir and locate “com.docker.docker” and “com.docker.helper”
    6. Delete them
    7. Check the Applications Support dir for any files or subdirectories with “Docker” in their name and delete them
  5. Uninstall Lando by running the “uninstall.command.dmg”
  6. Rerun the composer installer and go back to step 7 of Installing build tools
Table of Contents