Bedrock Framework - Local Installation Process

This guide is designed to help new developers set up their local development environment according to our agency’s standards. We leverage a structured workflow centered around LocalWP, the Bedrock Framework, and other tools to streamline development and maintain consistency across our WordPress projects.

This guide will walk you through the essential tools, configuration settings, and folder structure necessary for a smooth setup. By the end, you’ll have a fully configured local environment ready to clone repositories, manage dependencies, and start coding with ease.

Prerequisite(s):

  1. LocalWP: Download LocalWP to set up local development environments.
  2. Node Version Manager (NVM): Install NVM to handle multiple Node versions required across different projects.
  3. Node.js: Use nvm to install the appropriate Node.js version based on project requirements (this version will be specified in each project’s README or Buddy).
  4. Composer: Download Composer for PHP dependency management in WordPress projects.
  5. WP-CLI: Install WP-CLI to streamline WordPress management via the command line.
  6. IDE: Install an IDE, such as Visual Studio Code, for code editing.

Bedrock Framework: Local Installation Process

  1. Setting Up the Local Site
    1. Open LocalWP and add a new local site.
      1. You’ll want to name the project that you’re currently working on as close to the live domain as possible.
      2. To avoid any potential hiccups, my recommendation is to avoid usings spaces, underscores, or slashes when creating a site.
    2. Configure the following settings:
      1. PHP Version: 7.4
        1. Note some projects will require version 8.0 or above. Please update as needed per project.
      2. Web Server: Nginx
      3. Database: MySQL 8.0.16
    3. Enable SSL by selecting “Trust SSL” to facilitate HTTPS during local development.
      1. If working a Windows based system, you’ll be prompted by a confirmation pop up to ensure that you want to proceed.
      2. If you are working with MacOS, there are a few extra steps that are needed to enable the SSL.
        1. Once you’ve selected “Trust”, you will be prompted to enter in your computer’s password. This won’t entirely complete the process as you’ll need to update your keychain access for this site to be secure.
        2. Navigate to your Keychain access and search for the site that you’ve just created ( i.e example.local ). Once located, you’ll want to double click on the domain and a popup will appear.
        3. From here, you’ll want to expand the Trust section and change the “When using this certificate” from either “Use system defaults” or “Never Trust” to “Always Trust”.
        4. Once complete, you’ll want to close the pop-up which will then prompt you to either use your password or biometric login to finish the process.
    4. Once the domain has been trusted, you’ll want to restart the site. You may need to update some settings in the WordPress admin to ensure that the local site is leveraging HTTPS.
      1. If you click on another site and then click back into the site that you just created, you should see something like the screenshot below:

>>>>> gd2md-html alert: inline image link here (to images/image2.png). Store image on your image server and adjust path/filename/extension if necessary.
(Back to top)(Next alert)
>>>>>

alt_text \ \

  1. Repository & Folder Structure

    1. Create a Repositories Folder:
      1. Set up a main folder on your computer where all project repositories will reside. This can be named according to your preference (e.g., Projects or Repos). It does not need to be inside a clients folder or follow any specific structure as long as it’s easy for you to access.
    2. Clone the Repository:
      1. Clone the project repository into your designated folder (e.g., Projects/projectName).
      2. After cloning, move files from Projects/projectName to LocalSites/projectName to align with the LocalWP setup.
    3. Organize Web Directory:
      1. Inside LocalSites/projectName/app, move the public folder to LocalSites/projectName/web.
      2. Rename the public folder in web to wp for consistency with the Bedrock structure. \ \

  2. Nginx Configuration Adjustments

    1. Open the LocalSites/projectName in your code editor.

    2. Go to conf/nginx/site.conf.hbs and replace lines 50 to 55 with the following code snippet to handle remote image loading:

      ``` location ~* .(?:jpg|jpeg|gif|png|ico|xml|svg)$ { access_log off; log_not_found off; expires 5m; add_header Cache-Control "public"; try_files $uri @img_proxy; }

location @img_proxy { rewrite ^(.*)$ https://classicjourneys.829dev.com/$1 break; }



    10. **Adjust the Remote URL**:
        14. On line 59, replace the URL as needed (refer to 1Password for the correct URL if required).
    11. Update the path on line 10 - could potentially be line 9 - by changing the code as shown below:

        ```
 // Change the root  line from this
    root:   "{{root}}";
// To this
    root: "/Users/YourUser/Local Sites/projectName/web/"

    15. For Mac Operating Systems: \

\ \ \ \

    16. For Windows Operating Systems: \


        ```

// Change the root line from this root: "{{root}}"; // To this root: "C:\Users\your_username\your_local_sites_path\guideddiscoveries\web";



4. Environment File Configuration
    12. Duplicate .env.example in your project root and rename it to .env.
        17. If your project repository is missing a .env.example file, please use the following code and place it inside the repo:
            6. [https://bitbucket.org/829studios/workspace/snippets/5qgnLa/missing-envexample-file](https://bitbucket.org/829studios/workspace/snippets/5qgnLa/missing-envexample-file)
        18. Please ensure that the missing.env.example file is deployed alongside your next PR.
    13. Modify the .env file with the following values:

        ```
DB_NAME=local
DB_USER=root
DB_PASS=root
DB_HOST=localhost
APP_URL=https://projectname.local  # Replace with your LocalWP site domain

14. Restart LocalWP to apply the new configurations. \

\

  1. Setting Up Node & Composer Dependencies
    1. Check Node Version:
      1. Refer to the Buddy configuration, .nvmrc file, or repository notes for the specific Node version required.

      2. In the terminal, navigate to LocalSites/projectName and switch to the correct Node version using:

        ``` // If a NVMRC file is present, use this command:

nvm use

// If no NVMRC file is present, but you know what version of node is used, please use this command:

nvm use 16.13.0

//If you don't have a specific version of node installed, please use this command to install missing versions:

nvm install 16.13.0

// You can check what version of node you're using by running this command: node -v



    16. Install Dependencies:
        21. Run composer install to install PHP dependencies:

            ```
composer install

    22. Run npm install to set up project-specific Node packages.

        ```

npm install or npm i



6. Version Control and Branch Management
    17. Create a New Feature Branch:
        23. In the terminal, navigate to your project’s root directory and create a new feature branch for your task:

            ```
git checkout -b yourname/feature-or-task

    24. [Please follow the Git workflow as described in this guide](https://drive.google.com/file/d/1TtCvfR2_gP-FMXfSFsvYYwQCHD7Jumfa/view?usp=sharing). \

\ For the remainder of the steps, please follow along with this video tutorial as a majority of the remainder is handled via WP Migrate and working with the WordPress admin. \ \ 829 - Local Installation Process - Bedrock Framework - Windows