Local and WP Engine Connect

Manually setting up a local environment to develop a website can be a needlessly extensive process. Local is a free program that allows you to easily set up a WordPress® environment on your local computer, regardless of your skill level or experience.¹ Local is supported on Windows, Mac and Linux systems.

Once a site is created it can then be transferred to any account type or hosting provider, such as WP Engine. Local provides an experience that is user-friendly and speeds up the overall development workflow.

---

Local Features

The following features come standard with Local. We also recommend keeping your eye on the Local Release Notes page for new feature releases.

• Local development environment
• Push/pull any environment
• Demo site URL
• SSL
• Mac/Windows/Linux compatibility
• Sleek GUI (Graphical User Interface)

The best part about Local is that it’s totally free! Check out this article to learn more about how all the Local Pro features have been made free for everyone.

For feature requests and additional questions, please refer to the Local community forums.

---

Install Local

Before starting the setup process, we recommend signing up for the Local community forums. The WordPress community is always a great source of information, feedback and guidance.

1. Get the Local application for free, by clicking “Download” here
2. Choose your platform
3. Fill in your information
4. Download and Save the installation package to your computer
5. Open the installation package for Local on your computer
6. Follow the installation setup prompts
7. Launch Local on your computer

---

Connect Local to WP Engine

The WP Engine Connect feature will allow Local users to connect any Sites they have created on their WP Engine account and download associated environments. Additionally, if a website was initially setup on WP Engine, WP Engine Connect can help pull that site to Local!

Enable API Access

1. Open the API Access page of your WP Engine User Portal: https://my.wpengine.com/api_access
   • Or, in the User Portal at Users > API access
2. Locate the account name and toggle Account API Access to Enabled

Connect Local to WP Engine

1. Open the Local application on the computer
2. Click Connect in the menu on the left (cloud icon)
3. Click Connect to a platform

4. Next to WP Engine click Sign in
5. You will be prompted to log in to WP Engine using your User Portal credentials
6. After logging in, you’ll be redirected back to Local.

You’ll know you’ve logged in successfully because your WP Engine sites will now be listed within the “Connect” tab of Local!

---

Pull to Local From WP Engine

When setting up a site in Local, an initial pull will typically be made from WP Engine to copy content locally. After the initial pull, subsequent pulls can be made any time to overwrite your local content.

Initial Pull to Local

This process needs to take place the very first time you pull to Local from WP Engine.

1. Ensure you’ve already connected Local to your WP Engine account
2. Open Local on your computer
3. Go the Connect tab
4. Locate a Site in the list
5. Click Pull to Local

6. Name the Local site
7. Select an environment to pull
8. Click Connect & pull site

Initial Partial Pull

If you have a large site or otherwise do not wish to pull all of your website’s content locally, you can perform a partial pull. To do a partial pull from WP Engine to Local:

1. Ensure you’ve already connected Local to your WP Engine account
2. Open Local on your computer
3. Create a blank site in Local by clicking the plus icon in the lower left corner
4. Once the new site has been added to Local, click Pull in the lower right corner

5. Select the WP Engine account name, site name, and environment name to pull
6. After choosing Select Files the file system will load on the left, select only the content you want pulled into Local.
   • Use the dropdown at the top to quickly select Only Newer Files or Only Modified Files as-needed
7. The database can also be included as-needed
8. When you’re done selecting assets, click Pull

Subsequent Pulls to Local

After the initial pull to Local, additional pulls can be made using the following steps.

1. Open the Local app
2. Select the Local Sites tab
3. Select the site name
4. Click Start site at the top right (if this already reads Stop site, no change is needed here)
5. Click Pull in the lower right corner

6. After choosing Select Files the file system will load on the left, select only the content you want pulled into Local.
   • Use the dropdown at the top to quickly select Only Newer Files or Only Modified Files as-needed
7. The database can also be included as-needed
8. Click Pull

---

Push to WP Engine from Local

1. Open the Local app
2. Select Sites from the main menu
3. Click Start Site on the environment that you want to push
4. In the bottom right corner, click Push

4. Choose whether to push to an existing WP Engine site or a new site
5. Select the account to push to
6. Select the WP Engine site name
7. Select the environment type/name
   • We recommend pushing to Staging or Development before copying up to Production.
   • If Staging or Development do not yet exist on the selected site, click Enable next to the environment type to create it as part of the push
8. Click Choose Files to specify which files should be included in the push. Use the dropdown at the top to quickly select Only Newer Files or Only Modified Files as-needed
   • Content that is included will be overwritten on the destination environment.
9. Chose whether or not to include the database
   • Including the database will overwrite all database information on the destination environment
   • It is never advised to include a database when pushing to Production

A success message will display within Local when the push has completed:

Site Pushed! Your site has been pushed to WP Engine

---

Push or Pull Only Specific Files

In the development process, there may be times when you need to push or pull only specific files. Similar to how Git has a .gitignore file, Local has a set of ignore files for pushing and pulling. You can modify these files if you need to.

The .wpe-pull-ignore and .wpe-push-ignore files can be found in the site root for Local.

MacOS Users

• /Users/computer-username/Local Sites/SITE-NAME/app/public
• Example: /Users/larry.frog/Local Sites/jdiazii22/app/public

WindowsOS Users

• C:/Users/computer-username/Local Sites/SITE-NAME/app/public
• Example: C:\Users\larry\Local Sites\aceofspades\app\public

Notes:

• If the files are missing they will be recreated with default values after the first push/pull.
• The wp-config.php file is excluded from the push/pull. However, it can still be modified locally, i.e., enabling debug mode, max file size, etc. Any changes made to that file will need to be manually updated after the push/pull.
• The file will be blank, but in the background, we automatically filter out all of the exclusions noted here.

---

Backup Process

Like other files on your computer, backing up your Local sites is essential. Local site are stored in ~/Local Sites, and you may be able to recover sites from this directory. Follow the instructions below for a complete backup:

1. Click Start Site on your Local site to start it
2. Right-click or CTRL+click on your site
3. Select Export
   • This will include site files and database in a single .zip archive
4. Click Export Site
5. Depending on the size of the site, exports can take several minutes

Success! You now have a backup of your Local Site. Simply drag this .zip archive into Local to import content from the backup.

---

Migrate DevKit to Local

If you’ve been using DevKit by WP Engine, you will need to migrate your content into Local.

1. Open terminal on your local machine
2. Change directory into your site. Replace SITENAME with your own site name.
   • cd SITENAME
3. Initiate your DevKit environment:
   • wpe start
4. Once in the running site, run the following command. Replace SITENAME with your own site name in DevKit.
   • mkdir local-SITENAME; wpe wp db export local-SITENAME.sql && mv local-SITENAME.sql local-SITENAME/; rsync -avP wp-content/ local-SITENAME/wp-content --exclude mu-plugins; zip -r local-SITENAME.zip local-SITENAME/
5. Open the Local app on your computer
6. Drag and drop the zip file created in step 4 into Local from a finder window.
   • With the above command, your zip will be called local-SITENAME.zip and is stored in the root of your DevKit environment.
7. The import process will begin in the Local app
8. Start the site in Local to confirm the import was successful

For additional assistance, please use the community forum.

---

Manual Import

If the pull from WP Engine fails to import your environment(s), use the following steps to manually import each environment from a backup.

1. Create a backup of the environment
2. Download the full backup as a zip
3. Rename the zip file locally to match the name of your environment
   • EX: mystagingenv.zip
4. Open Local on your machine
5. Open the File menu
6. Select Import Site

7. Open the file from Step 3
8. Confirm the Environment name
9. Click Continue
10. Select Preferred
11. Click Import Site

Once the import completes, we recommend clicking View Site at the top right to confirm that it works.

---

Local Connect Issues

Most issues connecting to WP Engine via Local Connect can be solved by simply logging out and logging back in. This causes new API credentials and a new SSH key to be generated for the account.

To reconnect Local to WP Engine, open the Connect tab within Local to complete the process.

1. Open Local on your computer
2. Click the Connect icon in the sidebar
3. Click My Hosts in the top right
4. Log out of WP Engine
5. Click Connect to a platform
6. Click Sign in next to the WP Engine logo
7. Enter your WP Engine credentials in the browser window
8. The browser should refocus Local and a list of the available sites will be shown in the app

For general Local troubleshooting, see Troubleshoot: Local.

Local Logging

When troubleshooting an issue Support may request your Local log file. Version 5 of Local introduced a new file called local-lightning.log. Older versions of Local will use a log file called local-by-flywheel.log.

For full documentation on logging, read the Local knowledge base article.

Download Local Log

The easiest option to collect your logs is to simply download all log files as a zip. This can be done within the Local app itself.

1. Open the Local desktop application
2. Click Get Help (the icon is a question mark)
3. Click Download Local Log

If working with Support, please provide us with the entire zip file. Providing logs in this way helps provide more context for any issues you may be experiencing.

Reveal Local’s Log

Alternatively, if the full zip is not desired, logs can also be viewed from the Help menu. These logs do not give as much context for Support and are not suggested for extensive troubleshooting.

1. Open the Local app on your machine
2. Click the Help menu
3. Select Reveal Local’s Log
4. Attach this file when request to a ticket or chat

Log File Locations

If you’d prefer to locate the file on your own, you will need to check in the appropriate location for your operating system.

Mac: ~/Library/Logs/local-lightning.log

Windows: %AppData%RoamingLocallocal-lightning.log

Linux: ~/.config/Local/local-lightning.log

---

NEXT STEP: Learn how to connect to the WP Engine API