Local Environment Setup (VirtualBox + Docksal)

Please feel free to view a video of local environment setup as well follow the instructions below. Note that this is an outdated setup process; our team has moved to a setup that uses Laravel Valet and DBngin on MacOS (view more here).

First-time setup

Download VirtualBox for Mac
1. Download the VirtualBox package from the link
2. Follow the instructions to install Docksal through the command line
Install Homebrew if needed

Project setup

Clone the project from Bitbucket
1. Log into Bitbucket, navigate to desired project, click on clone in the top right corner
2. Copy the git clone command (ex: git clone git@bitbucket.org:relias/relias-wceiblog.git)
3. Copy in the Projects folder within the terminal
4. A new folder will be created automatically with the repo inside
  1. If on a mac, click cmd + shift + . to see hidden files
Add Wordpress Core files to the new project root folder. See all versions here
1. Do not overwrite wp-content or .htaccess files
2. Make sure you use WP Core version that is the same as the version that your project is using
Add uploads for project
1. Download a backup from WPEngine that includes all file uploads
  1. Navigate to http://www.wpengine.com , click on sign in. Log in with your credentials.
  2. Navigate to production version of desired site
  3. Click on “backup points” from the left side menu
  4. Click on “Create backup”
  5. Within the pop-up:
    1. enter backup description (typically “deployment backup”)
    2. remove email addresses listed and only enter your email address. This is where the notification is sent that a backup has been created.
    3. Click “Create production backup”
  6. Once the backup has been created, you will receive an email notification. You may then navigate to wpengine backup points, choose your recently created backup point, and click “prepare zip”.
  7. You may choose to do a full backup or partial backup. If you choose a partial backup, you will need the entire database and media uploads.
  8. Make sure you’re sending notifications only to your email address
  9. When the zip has been successfully created, you can then click on the download link to download the zipped version of the production environment.
2. When moving uploads to project uploads folder, only copy over each year’s folder from the backup. Ignore sucuri logs and .htaccess, these are not needed locally.
Run fin system start in the project root folder in terminal
1. Since docksal files are already configured in git, you won’t need to worry about those.
2. Please note, this may take a while if it’s your first time building
Run fin p start in the project root folder in the terminal to start your project.
Visit the project URL provided in the terminal
1. You should see a Wordpress startup screen, since the database has not been imported and a wp-config file has not been generated yet.
2. Navigate through screens but stop at the screen where you need to enter database connection details. You’ll need to make sure your database is set up prior to doing this. Please follow the sets in https://relias.atlassian.net/wiki/spaces/CEMVP/pages/2540831060/Relias.com+%7C+Local+Environment+Setup#Set-up-the-database section before proceeding.
3. After database has been set up, please fill in the screen with the following:
  1. Database name: local_wceiblog (or whatever your database name is)
  2. Username: root
  3. Password: root
  4. Database Host: db
  5. Table Prefix: wp_

Set up the database

Download/open Sequel Pro (if you’re on a mac)
Hook up your project’s configuration files to the new database connection:
In the docksal.env file, remove hashes and add single quotes around variable values for your database’s credentials
1. MYSQL_ROOT_PASSWORD=’root’
2. MYSQL_USER=’user’
3. MYSQL_PASSWORD=’root’
Change the port mapping variable to a unique port number:
1. MYSQL_PORT_MAPPING=’00000:3306’
Run ‘fin p restart’ to initialize changes.
Docksal has a MYSQL service built in that is exposed to a random port by default. Create a new connection using these credentials:
1. Name: your project’s name (use ‘local_projectname’)
2. Host: 192.168.64.100
3. Username: root
4. Password: root
5. Database: [leave blank]
6. Port: [choose a number unique for this project]
Verify the connection works, then save it as a favorite in Sequel Pro for quick use.
Add the wp-config-local.php file to your project root folder. Update the database variables similarly for this file:
1. define(‘DB_NAME’, ‘local_projectname’);
2. define(‘DB_USER’, ‘root’);
3. define(‘DB_PASSWORD’, ‘root’);
4. define(‘DB_HOST’, ‘db’);
5. Do the same for wp-config-sample.php
Run ‘fin p restart’ to initialize changes
Import the database file from the backup you downloaded from WPEngine
1. Once you have tested and made the connection, go to File > Add Database in Sequel Pro
2. Add a new db with the same name you set up in your wp-config-local.php file for DB_NAME
3. Import the mysql.sql file from your site backup’s wp-content folder
Now that the database is imported and connected, run through the Wordpress setup screens in your local environment browser tab.
1. If you see an error that says “error establishing database connection”, there is likely a problem with the wp-includes/wp-config.php file.
Within wp-config.php file, you can remove the section that says “Authentication unique keys and salts”. This is not needed for the local environment.
After you make changes to files, always do a fin p restart within the terminal. This updates your instance with whatever changes you’ve made in files.
Visit your project url and you should see a working project.
1. Sometimes images and css won’t load and you’re see errors within your console. In that case, run the following commands:
  1. Within terminal on the project, run the following commands that will allow read/write/execute access to all files within directory
    1. chmod -R 755 wp-includes
    2. chmod -R 755 wp-content
    3. navigate to the wp-content and run:
      1. chmod -R 755 uploads
  2. Some errors are expected because some 3rd party tools are not needed on a local environment. You can ignore these errors. If you have any questions about the errors please reach out to the team lead.

Search-replace the database

Before visiting the project URL, need to adjust the database so that existing plugins and URLs do not conflict with local setup
Use wp-cli to disable the following plugins (if they exist):
1. fin wp plugin deactivate redirection
2. fin wp plugin deactivate sucuri-scanner
3. fin wp plugin deactivate autoptimize
Search and replace all live URLs with local project URLs:
1. fin wp search-replace ‘https://www.livesite.com ’ ‘http://project.docksal’ --dry-run
  1. Be very mindful of entering the correct urls and your syntax
2. When satisfied with dry run results, re-run command without --dry-run argument
Run fin p restart, to refresh everything
Give the new project folder permissions needed for Docksal to access images. From the Projects folder, run this command in Terminal:
1. chmod -R 755 <folder name>

Your local environment should now be ready to use.

Notes:

Use fin vm restart to fix 403 Forbidden errors