Please also be aware of the Project Git Process.

- DO NOT INSTALL ANY WEB SERVERS OR MYSQL INSTANCES ON YOUR MACHINE.
- IF ANY ARE RUNNING STOP THEM NOW. 
- THE DOCKER CONTAINER BINDS TO PORT 80 and 3306!!!

- ONLY RUN BLT, DRUSH, AND NPM IN THE CONTAINER
- ONLY RUN COMPOSER AND GIT OUTSIDE OF THE CONTAINER

Here's where to start when you get your Mac. (Right now, that is all we support...)

1. Change your terminal to run bash instead of sh:
   1. Launch the Terminal application
   2. Go to preferences (Menu > Terminal > Preferences — or just [Cmd] [Comma])
   3. Mid-screen, change “Shells open with” to “Command (complete path)” and enter the value /bin/bash.
   4. Note: The "typical" command to change the default shell (chsh) will not work.
2. Enable the Mac developer tools so you can actually use Git and other command line things.
   1. Open a terminal and run the following command:

      sudo xcodebuild -license
      

3. Install Homebrew. The most up to date instructions are on that page, but they currently are:
   1. Open a terminal and run the following command:

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

   2. Be certain to execute the two "follow up" commands the script presents. These are necessary in order to put brew on your file path. (You may need to open a new terminal window in order for it to become available.)
4. Install dnsmasq. This will allow http://*.devbox to resolve to your docker container.
   1. brew install dnsmasq
   2. sudo echo 'address=/devbox/127.0.0.1' >> /usr/local/etc/dnsmasq.conf For Macs with the Apple Silicon (M1 chip) sudo echo 'address=/devbox/127.0.0.1' >> /opt/homebrew/etc/dnsmasq.conf
   3. sudo mkdir -p /etc/resolver
   4. echo 'nameserver 127.0.0.1' | sudo tee /etc/resolver/devbox to setup DNS for the sites
   5. sudo brew services restart dnsmasq
   6. When prompted, you do not want to allow dnsmasq to accept incoming network connections. (This would allow your laptop to be used as a DNS server by other computers.)
5. Install Docker for Mac
   1. Go to https://docs.docker.com/desktop/mac/install/
   2. Select the right binary for your Mac's architecture.
   3. Follow the instructions to install. (You may need to create an account. As of 10/2021, you know, just do that)
   4. Once installed you most likely want to increase the memory and cores of the Linux virtual machine Docker for Mac creates.
      1. Find the docker icon in the system tray at the top right of your window
      2. Left-click and select "preferences". This will open the Docker preferences panel.
      3. Select "Resources" on the left side of the panel.
         • CPUs: The number of CPUs are defined as the number of cores/hyperthreads. So a 8 core i7 processor has about 12 "CPUs" available. The default 2 is probably too low, but do not go soo high that you cannot run anything. I
         • Memory: I would give the machine at least 6GB of RAM. Anything more than 8GB is probably unnecessary.
           • NOTE 1: You still need to make sure your computer has enough resources to run things. However, newer Macs on the team are coming with 16GB RAM, so 8 would not be too much.
           • NOTE 2: This is the configuration for ALL the docker containers. So I am accounting for any other containers running with CGDP.
         • SWAP: Leave it at 2 GB. I have not tried to increase it, but I also did not see a need.
         • Disk image size: Personally I have ramped up my Disk image size to 128GB just to be on the safe side. Some CGDP site backups are large. Additionally the VM also holds all the Docker images, which can start taking up space as well. Currently I am only using 68GB of 128GB, but that is more than what the default is.
           • NOTE: The CGDP with the default content will fit in the default image size with a few other docker images.
6. Install PHP
   1. Run brew install [email protected] (note had to use brew upgrade php to make it work.
   2. Follow any additional instructions on the screen. One of this set is adding PHP to your path. Make sure you do that.
   3. Edit /opt/homebrew/etc/php/8.1/php.ini or /usr/local/etc/php/8.1/php.ini and set memory_limit = -1
      • This removes any memory limits, which composer install usually hits.
      • /opt/homebrew seems to be the location for newer home brew installs.
7. Install Composer
   1. Run curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer --2
      • You should have write access to /usr/local/bin if you can do brew.
8. Authenticate Composer to NCIOCPL Github
   1. Create a classic token with "no-scope". (Don't check any checkboxes)
   2. Authenticate token with SSO for NCIOCPL
   3. Make sure that ~/.composer is owned by your user. (Mine was owned by root)
      • If not sudo chown -R <your_user> ~/.composer should fix it
   4. Run composer config --global github-oauth.github.com <TOKEN>
9. Install Visual Studio Code (the suggested IDE): https://code.visualstudio.com/download
   1. Install the necessary VS Code plugins for development as well:
      • PHP Debug (felixfbecker.php-pack)
      • PHP Intelephense (bmewburn.vscode-intelephense-client)
        • Search extensions for @builtin php and disable extension PHP Language Features (vscode.php-language-features)
        • Add the following to your settings.json:

          "intelephense.files.associations": [
            "*.module",
            "*.theme",
            "*.php",
            "*.phtml"
          ],
          "intelephense.environment.phpVersion": "8.0.0",
          "intelephense.maxMemory": 4000,
          "intelephense.files.exclude": [
            "**/.git/**",
            "**/.svn/**",
           "**/.hg/**",
           "**/CVS/**",
           "**/.DS_Store/**",
           "**/node_modules/**",
           "**/bower_components/**",
           "**/vendor/**/{Tests,tests}/**",
           "**/.history/**",
           "**/vendor/**/vendor/**",
           "**/nano/**",
           "**/rare-brain-spine-tumor/**",
           "**/pediatric-adult-rare-tumor/**",
           "**/automation-installed/**",
           "**/automation-refreshed/**",
           "**/ccg/**",
           "**/connect-prevention-study/**"
          ],
          

      • phpcs (ikappas.phpcs)
      • Prettier (esbenp.prettier-vscode)
      • Live Share (ms-vsliveshare.vsliveshare)
      • EditorConfig (editorconfig.editorconfig)
      • YAML (redhat.vscode-yaml)

1. Install NVM --TBD
2. Check and see if the following works at the command line: python --version. Python is used by node-gyp and newer MacOS does not include a default python. If it returns file not found then do:
   1. brew install pyenv
   2. pyenv install 3.9.6
      • This will probably be out of date by the time you see this
   3. pyenv global 3.9.6
      • The version should match the version you installed.
   4. Add the following to your login script (.e.g, ~/.profile)

      if command -v pyenv 1>/dev/null 2>&1; then
         eval "$(pyenv init -)"
      fi
      

   5. Reopen your terminal

1. Certain packages are scoped to the @nciocpl organization so we need to inform npm where those packages reside. Create .npmrc directly under your $HOME directory with the following contents:

   @nciocpl:registry=https://npm.pkg.github.com
   

2. You will also need to npm login
   1. Generate a Personal Access Token(PAT) for use as your password for logging in. Follow github's documentation for creating a personal access token. Create your PAT with the repo scope checked. (If you work on other projects you may need other permissions which you should add at this time, such as write:packages + read:packages if you will be publishing packages)
   2. Login using npm login --scope=@NCIOCPL --registry=https://npm.pkg.github.com/. Use your PAT as the password and enter the email associated with your github account to complete login.

NOTES:

1. You build with node inside the container only. Installing it is only to get a .npmrc
2. You only need a token that can read packages. However, npm login requires more than that. So either document the token creation for just read and how to edit the .npmrc directly, OR, document the token for login. This is the local machine's .npmrc, so if you work on other projects you will need the read-write one.

1. Clone this repo
2. Open a command prompt
   1. Outside the container run the following commands:
      1. composer cgov-init
         • This sets up some commit hooks and some other things for Docker
      2. Create a <repo_root>/docker/web/runtime/licenses/licenses.php file with:

         <?php
         
         $cgdp_license_keys =
           [
             'ckeditor_lts' => [
             'default' => '<SEE #digital_platform_dev channel comment>',
           ],
         ];
         
         

      3. composer install
         • If you have a slow internet connection (e.g. satellite) you may need to run this as:

           COMPOSER_PROCESS_TIMEOUT=600 composer install
           

      4. IF ON NIH VPN LOG OFF!
         • Some of the packages in our Dockerfile are blocked by the NIH network.
      5. docker compose -f ./docker/docker-compose.yml up -d
         • DO NOT HAVE ANYTHING RUNNING ON PORT 80 or 3306!!!!!
         • This starts your container
      6. docker compose -f ./docker/docker-compose.yml exec web bash
         • This enters your container.
   2. Inside the container run the following commands
      1. blt setup --no-interaction
         • This installs Drupal and builds the front end. Really we just need the couple of setup commands but have yet to find time to make them so that we don't need to do the setup first.
      2. blt cgov:reinstall --no-interaction
         • This installs Drupal (again) along with our default content and translation packages and a bunch of other things needed to make our site work. THIS is the command you will use on a frequent basis to install Drupal.
   3. Outside of container
      1. Open a web browser and view http://www.devbox to see your web site.

Important Links:

1. Our Git Process, i.e. how commits and PRs should be done
2. Debugging with XDebug - You should know how to debug BLT, Drush, and the website with XDebug
3. Technical Design Notes - which may have some incorrect info as time has passed, but is usually correct.
4. Drupal Content Model - Our content types, media, taxonomies, etc. This is mostly kept up to date by our Information Architects who own this model.