Use Pantheon Localdev to Develop Sites Locally

Localdev makes it easy to develop your sites locally with the Pantheon workflow.

Contributors: Edward Angert.

Tweet

Pantheon offers a number of ways to connect to your site. In addition to Git and SFTP modes, Pantheon Localdev gives you a graphical interface to your Pantheon sites, complete with a containerized local environment that makes it easy to develop and preview your site locally while still maintaining the Pantheon Workflow.

Localdev lets you use an integrated development environment (IDE) to edit files and code, and push changes to Pantheon right from your desktop. Use it if you want to avoid the command line, or to develop sites with a fully functional local preview, even when you don't have an internet connection.

Localdev is in active development, with new features and updates coming soon.

Install and Connect Localdev

Create a machine token before you continue.

If you have an older version of Localdev already installed on your machine, remove it to avoid potential compatibility issues. Newer versions of Localdev include support for automatic updates.

  1. Download and install the latest Localdev .dmg
  2. Localdev checks the Docker installation. Once it's done, click Continue installation
  3. Enter the machine token you created for Localdev.
    • Click View your Pantheon machine tokens to open a browser to the Machine Tokens tab of your account.
  4. Click Submit Token and wait for it to connect
  5. Click Begin sync to synchronize Localdev with your account

Once Localdev is installed, a list of your sites is displayed in a column on the left.

Download and Test Beta Versions

Download Edge versions to get the latest features, bug fixes, instructions, and help test Localdev.

  1. From within your Localdev installation, select Settings on left menu.

  2. In the Current Version section, click on switch to edge:

    Switch to edge version

 Note

Help improve Localdev by sharing bug reports and feedback on the Localdev Slack channel or GitHub issue queue.

Connect and Clone your Site Locally

Select a site and click Pull for local development to clone the site locally and boot the local environment.

Localdev clones the site code

Since this is the first time you are cloning the entire site code, this will take several minutes. Unless you reset Localdev to its defaults, you will only need to do this once per site.

Each site is cloned to its own directory within ~/Localdev/.

If there are any errors, Localdev will revert all changes and return you to the "Clone your development site" screen. Try the process again, then consult the Troubleshooting section below for how to contact Support.

Start the Container

In the upper right hand corner, click the grey Stopped button and click Start to start the local server.

In the Stopped button's dropdown, click Start

Once the container has been started, you can preview the site using the Open Browser button in the Local Site section, and track changed files using the Pull and Push tabs.

Localdev shows that the container is running

Use a Local IDE to Develop your Pantheon Site

There are a number of IDEs that have built-in Git tools or plugins available for working with Git from within the IDE:

See your editor's documentation for specific steps on how to commit and push changes from inside the editor.

Push and Pull Changes to Pantheon

If you have a Git client that you're already comfortable with, you can use it to track, commit, push, and pull as you normally would. Navigate or point your Git client to track your local code directory, for example: /Users/yourUser/Localdev/examplesite.

To have Localdev deal with Git for you, use the Pull and Push tabs.

In Pull tab, check the Pull code option to copy the site's code from the Pantheon Dev environment to your local environment. The Last Pull line below each option's area shows the last time the code was synched.

After you make changes to your site:

  1. Navigate to the Push tab
  2. Select the information you want pushed to the Pantheon Development environment
  3. Enter a Git commit message that describes the changes made in this particular push
  4. Click Push

Advanced Steps

For users looking to be more hands on and willing to use the terminal, try Terminus and Lando. The Local Development doc can help you get started.

FAQ, Troubleshooting, and Support

What does Localdev do about existing Lando config files?

Localdev will use the existing .lando file only when the site is initially cloned. After the initial site clone, there is currently no lando rebuild equivalent that will force Localdev to reconsider the landofile.

Note that if there are services specified in .lando, Localdev will return an error.

Contact Support / File an Issue

While Localdev is in beta, support request best practices are especially important for our team to help you resolve the issue, or to report any potential issues in Localdev itself.

  1. Navigate to the Settings tab and confirm that Usage and Crash Data is set to Allow reports. This allows the application to automatically submit crash data to Pantheon Support.

    • Application reports are collected and stored locally in ~/.pantheonlocaldev.
  2. Reproduce the error and note the steps taken.

    • If the error is inconsistent, make note of this as well. Multiple reports of an inconsistent error help our team troubleshoot.
  3. Report the error:

Log out and Reset to Defaults

The steps in this section should only be used as a last resort. This resets Localdev and will remove the machine token and all local copies of your connected sites.

  1. Click Settings
  2. Reset to defaults
  3. Proceed with reset

Limitations

Localdev does not connect to Multidev environments or allow direct database access.

Changelog

0.9.3

UPDATE IMMEDIATELY!!!

  • If you have an existing locally pulled down site that is not functioning click on that site in the sidebar, go to the Advanced tab and initialize a Force Rebuild.

Critical fixes

  • Fixed CRITICAL breaking changes in upstream images

New features

  • Added force remove option to all apps
  • Added support for Docker Desktop 2.2.0.4
  • Added support for multidev environments
  • Added ability to configure where you clone projects
  • Updated to Lando 3.0.0-aft.2 for speed, performance and stability improvements

Improvements

  • Improved user experience
  • Improved handling of installing to non-empty directories
  • Stopped removing local codebase on environment destruction

0.9.2

UPDATE IMMEDIATELY!!!

  • If you have an existing locally pulled down site that is not functioning click on that site in the sidebar, go to the Advanced tab and initialize a Force Rebuild.

Critical fixes

  • Fixed CRITICAL breaking changes in upstream images

New features

  • Added force remove option to all apps
  • Added support for Docker Desktop 2.2.0.4
  • Added support for multidev environments
  • Added ability to configure where you clone projects
  • Updated to Lando 3.0.0-aft.2 for speed, performance and stability improvements

Improvements

  • Improved user experience
  • Improved handling of installing to non-empty directories
  • Stopped removing local codebase on environment destruction

0.9.1

UPDATE IMMEDIATELY!!!

  • If you have an existing locally pulled down site that is not functioning click on that site in the sidebar, go to the Advanced tab and initialize a Force Rebuild.

Critical fixes

  • Fixed CRITICAL breaking changes in upstream images

New features

  • Added force remove option to all apps
  • Added support for Docker Desktop 2.2.0.4
  • Added support for multidev environments
  • Added ability to configure where you clone projects
  • Updated to Lando 3.0.0-aft.2 for speed, performance and stability improvements

Improvements

  • Improved user experience
  • Improved handling of installing to non-empty directories
  • Stopped removing local codebase on environment destruction

0.9.0

UPDATE IMMEDIATELY!!!

  • If you have an existing locally pulled down site that is not functioning click on that site in the sidebar, go to the Advanced tab and initialize a Force Rebuild.

Critical fixes

  • Fixed CRITICAL breaking changes in upstream images

New features

  • Added force remove option to all apps
  • Added support for Docker Desktop 2.2.0.4
  • Added support for multidev environments
  • Added ability to configure where you clone projects
  • Updated to Lando 3.0.0-aft.2 for speed, performance and stability improvements

Improvements

  • Improved user experience
  • Improved handling of installing to non-empty directories
  • Stopped removing local codebase on environment destruction

0.8.0

UPDATE IMMEDIATELY!!!

  • If you have an existing locally pulled down site that is not functioning click on that site in the sidebar, go to the Advanced tab and initialize a Force Rebuild.

Critical fixes

  • Fixed CRITICAL breaking changes in upstream images

New features

  • Added support for Docker Desktop 2.2.0.4
  • Added support for multidev environments
  • Added ability to configure where you clone projects
  • Updated to Lando 3.0.0-aft.2 for speed, performance and stability improvements

Improvements

  • Improved user experience
  • Improved handling of installing to non-empty directories
  • Stopped removing local codebase on environment destruction

0.7.0

New features

  • Added macOS Catalina Support!
  • Added a beta release channel
  • Added ability to toggle cache service #24
  • Added ability to toggle edge service #24
  • Added ability to toggle index service #24
  • Added ability to rebuild a given app
  • Added basic online/offline detection
  • Added support for phpmyadmin as toggleable service
  • Added surfacing of release notes
  • Added option to automatically quit Docker on Localdev quit

Improvements

  • Improved cancellation of app initialization
  • Improved application state detection
  • Improved handling when port 2222 is blocked
  • Improved shutdown and quit
  • Improved process handling and management
  • Improved revoked token detection and mitigation
  • Improved application destruction UX
  • Improved Docker state management
  • Improved error handling and logging
  • Improved "botched state" cleanup
  • Improved progress indicators
  • Improved UX on phpmyadmin selection

Bug fixes

  • Fixed bug in 0.6.0 causing develop screen to not show if user did not have pma installed
  • Fixed various initialization bugs
  • Fixed various "app is stuck" bugs
  • Fixed bug causing pre-0.6.0 installs to not be detected

Notes

  • Going forward Localdev will manage its own Lando configuration #18

0.6.0

New features

  • Added macOS Catalina Support!
  • Added a beta release channel
  • Added ability to toggle edge service #24
  • Added ability to rebuild a given app
  • Added basic online/offline detection
  • Added support for phpmyadmin as toggleable service
  • Added surfacing of release notes
  • Added option to automatically quit Docker on Localdev quit

Improvements

  • Improved cancellation of app initialization
  • Improved application state detection
  • Improved shutdown and quit
  • Improved process handling and management
  • Improved revoked token detection and mitigation
  • Improved application destruction UX
  • Improved Docker state management
  • Improved error handling and logging
  • Improved "botched state" cleanup
  • Improved progress indicators

Bug fixes

  • Fixed various initialization bugs
  • Fixed various "app is stuck" bugs
  • Fixed bug causing pre-0.6.0 installs to not be detected

Notes

  • Going forward Localdev will manage its own Lando configuration #18

0.5.7

  • Complete OSX Catalina Support!

0.5.6

  • Preliminary Catalina support

0.5.5

  • Complete OSX Catalina Support!

0.5.4

  • Added changelog display when updates are detected #123
  • Improved support for stable and beta channels
  • Fixed download and install from Settings #129

0.5.3

  • This is a test release for the edge/beta channel; No functional changes

0.5.2

  • This is a test release for the edge/beta channel; No functional changes

0.5.1

  • Added support and configuration for the edge (non-stable) release channel

0.5.0

  • Added ability to launch shell to use drush, composer, terminus, wp-cli, etc #13
  • Fixed Congratulations! It should be impossible... Docker bug
  • Updated to Docker Desktop 2.1.0.0

0.4.3

  • Added a stable release alias at https://pantheon-localdev.s3.amazonaws.com/localdev-stable.dmg
  • Added instance id to all error reports
  • Added instance id to config screen
  • Fixed bug where default error stack trace and message value were the wrong type #1
  • Locked down token length validation to 45 characters
  • Updated to Lando 3.0.0-rc.18, fixes bugs, improves error logging

0.4.2

  • Added "CLI connection string" to dashboard #10
  • Fixed bug where default error stack trace and message value were the wrong type #1
  • Changed localhost to 127.0.0.1 in DB connection info #10
  • Updated to Lando 3.0.0-rc.17

0.4.1

  • Fixed regression causing database creds to not surface correctly #112
  • Fixed bug causing site destroy to throw a name not defined error
  • Improved error capture to include identifying information if possible
  • Updated to Lando 3.0.0-rc.16+b72f0ce
  • Updated README.md to include useful troubleshooting materials

0.4.0

  • Added dev site and Pantheon Dashboard links to Develop tab #95
  • Added splash screen for when Docker needs to startup #90
  • Added pld namespacing to PLD containers so they don't collide with lando ones #25
  • Fixed inconsistencies between n-invoked progress runners #29
  • Improved sync between Docker engine status and sites running status #2
  • Removed redundant code pull on site initialization #4
  • Updated to Lando 3.0.0-rc.14

0.3.1


0.3.0

Rebased on Lando RC9

  • Added handling for frozen sites #101
  • Fixed scroll issue in footer #65
  • Fixed funky behavior when trying to add a git commit message #100
  • Fixed issue causing additional hyphens to be added to a sites name #76 #97
  • Fixed markdown showing in "Running" indicator #104
  • Improved handling of "multi inits" #24
  • Slow usage #89
  • Inability to launch some sites #47 #92 #93
  • Better (and faster) healthchecks #61
  • These general improvements to Lando have also been made.

0.2.3

  • Corrected a typo in FACTORY RESET #87
  • Improved the entire design and UX

0.2.2

  • Improved installation process UX

0.2.1

Rebased on Lando RC1 pre-release and switched to pantheonlocal.com domain.

  • Switched domain to pantheonlocal.com #83
  • Switched to Pantheon certificates #75
  • Rebased on Lando RC1 pre-release

0.2.0

First pass rebasing on almost-ready-to-be-released Lando RC1

  • Improved site init cancel #62
  • Improved stop, start, refresh and stop all UX #21
  • Improved Docker auto-start func #73
  • Rebased on new Lando RC1 API
  • Separated push into individual components for better UX #54
  • Prepped for custom proxyDomain certs #78

0.1.26

Some smaller UX improvements and just kicking out a new release because we've been stagnate for awhile.

  • Added some basic from-the-internet screenshots to the site list #20
  • Added a stubbed out loading screen with content TBD #30
  • Changed search to be case insensitive, white-space agnositc and inclusive #48
  • Improved default site screen to be got-sites aware #27
  • Set a minimum screen size for the app window #64
  • Updated autoupdate UX to use Bootstrap modals instead of nasty native JS alerts dialogs #58