📝 Update lando guide (#2240)

* 📝 First draft of the updated lando doc * 🚨 Apply Vale recommendations * 📝 Apply recommendations * 📝 Follow most of Vale's recommendations * 📝 Apply suggestions from code review Co-authored-by: Aaron Collier <[email protected]> * 📝 apply recommendations * 📝 Apply suggestions from code review Co-authored-by: Aaron Collier <[email protected]> * 📝 Apply recommendations * 📝 Update docs/src/development/local/lando.md Co-authored-by: Aaron Collier <[email protected]> * 📝 Update docs/src/development/local/lando.md Co-authored-by: Aaron Collier <[email protected]> Co-authored-by: Aaron Collier <[email protected]>
platformsh · Apr 6, 2022 · 9ffca94 · 9ffca94
1 parent 678676d
commit 9ffca94
Show file tree

Hide file tree

Showing 2 changed files with 107 additions and 26 deletions.
diff --git a/docs/src/development/local/lando.md b/docs/src/development/local/lando.md
@@ -1,46 +1,126 @@
 ---
-title: Using Lando for local development
+title: Use Lando for local development
 sidebarTitle: "Lando"
+description: Find out how to include Lando in your local development workflow.
 weight: 3
 ---
 
-[Lando](https://github.com/lando/lando) is Platform.sh's recommended local development tool.  It is a third party tool developed by [Tandem](https://thinktandem.io), which now includes direct support for Platform.sh projects.  Lando can read your Platform.sh configuration files and produce an approximately equivalent configuration using Docker with minimal effort on the part of the developer.
+[Lando](https://docs.lando.dev) is third-party local development tool for which several stacks are available (LAMP, LEMP, MEAN).
+Lando supports Platform.sh PHP projects out of the box through a plugin.
+The Lando Platform.sh plugin can read your Platform.sh configuration files and produce an equivalent local environment using Docker.
 
-At this time, Lando supports only PHP-based applications but works with any service supported by Platform.sh.  Support for other application languages is in progress.
+The Lando Platform.sh plugin is currently in beta and supports only PHP-based applications.
+Support for more languages is in progress.
 
-See the [Lando documentation](https://docs.lando.dev/platformsh/) for installing and setting up Lando on your system.
-A quick-start guide is included below, but the Lando documentation is the primary source of truth.
+Lando works with most services supported by Platform.sh [except for](https://docs.lando.dev/platformsh/caveats.html#unsupported-things) Vault KMS and network storage.
+See a list of [supported services](https://docs.lando.dev/platformsh/config.html#services-yaml).
 
-## Quick start
+A quick-start guide is included below.
 
-First, ensure that you have the Platform.sh CLI installed and that you have authenticated your account.  Then, [install Lando](https://docs.lando.dev/basics/installation.html) and Docker per Lando's installation instructions.
+For a complete reference, consult the following resources:
 
-If you do not yet have your project checked out, run:
+- [Lando Platform.sh plugin documentation](https://docs.lando.dev/config/platformsh.html) and [source code](https://github.com/lando/platformsh)
+- [Lando documentation](https://docs.lando.dev/)
 
-```bash
-$ lando init --source platformsh
-```
+## Before you begin
 
-That will offer an interactive dialog to select the Platform.sh project to download, and then setup basic Lando configuration.
+You need hardware that meets the [requirements](https://docs.lando.dev/getting-started/installation.html#hardware-requirements).
 
-If you already have your project checked out locally, change into the project directory and run:
+Lando doesn't automatically pull and set up environment variables that have been set in the Console.
+To use a build hook that requires environment variables, manually [add them](https://docs.lando.dev/platformsh/config.html#environment-variables).
 
-```bash
-$ lando init --source cwd --recipe platformsh
-```
+## 1. Install Lando
 
-That will use your existing git clone and add the appropriate Lando configuration.
+Follow the [Lando installation instructions](https://docs.lando.dev/getting-started/installation.html).
 
-Either way, start the local environment by running:
+## 2. Initialize Lando
 
-```bash
-$ lando start
-```
+{{< codetabs >}}
 
-You can then download data from the environment for your current branch and load it into your local Lando environment by running:
+---
+title=On a new Platform.sh project without code
+file=none
+highlight=false
+---
+
+For a quicker start, create a project based on the Platform.sh [PHP template](https://github.com/platformsh-templates/php).
+The template provides the most basic configuration for running a custom PHP project built with Composer.
+It also includes the required Platform.sh configuration files out of the box.
+
+1. [Create a new project based on the PHP template](https://console.platform.sh/projects/create-project/template?query=php).
+2. Clone that project locally in one of these ways:
+    - Using the [Platform.sh CLI](../../gettingstarted/introduction/own-code/cli-install.md) by running `platform get <PROJECT_ID>`
+    - Using [git](../../administration/web/_index.md#git)
+3. In the project's folder, run `lando init --recipe platformsh --source platformsh`.
+4. Follow the instructions provided by the interactive prompt.
+   On the `Which project?` step, select the project created in the first step.
+
+<--->
+
+---
+title=On an existing Platform.sh project
+file=none
+highlight=false
+---
+
+If your code isn't present locally, retrieve your codebase with one of these methods:
+
+- Using the [Platform.sh CLI](../../gettingstarted/introduction/own-code/cli-install.md) by running `platform get <PROJECT_ID>`
+- Using [git](../../administration/web/_index.md#git)
+
+Otherwise, access the directory with your project.
+
+Run `lando init --recipe platformsh --source cwd` and follow the instructions provided by the interactive prompt.
+
+{{< /codetabs >}}
+
+The `init` command generates the `.lando.yml` file required to start Lando.
+
+## 3. Start Lando
+
+To start your app and services, run `lando start`.
+
+## 4. Access your local app
+
+The last lines of the `lando start` command from the previous step contains URL to the different app and services.
+Access your app and services by opening the according URLs in your browser.
+
+## What's next
+
+- [Import data and download files](https://docs.lando.dev/platformsh/sync.html) from your remote Platform.sh site.
+- If you make changes in the Platform.sh [configuration files](../../overview/structure.md) during development, run `lando rebuild` for these to be taken into account in Lando.
+- To keep your Lando image up-to-date, see how to [update Lando](https://docs.lando.dev/getting-started/updating.html).
+
+## Troubleshooting
+
+- Make sure that the [Platform.sh configuration files](../../overview/structure.md) are present in your local repository.
+- Check that your [services](https://docs.lando.dev/platformsh/config.html#services-yaml) are supported by Lando.
+- Check [caveats and known issues](https://docs.lando.dev/platformsh/caveats.html).
+- Carefully check the output of the Lando commands you run to spot warnings and errors.
+- Run `lando rebuild`.
+- Restart Lando in debug mode by running `lando restart -vvv`.
+- Check that you don't face common issues, such as [DNS rebinding protection](https://docs.lando.dev/help/dns-rebind.html).
+- For more extensive troubleshooting, check the [Lando documentation](https://docs.lando.dev/help/logs.html#install-logs).
+
+### Access logs
+
+Access the global logs by running `lando logs`.
+
+To access specific logs:
+
+1. Run `lando list` to get a list of the services you are using.
+2. Choose the one you'd like to inspect.
+3. Run `lando logs -s <SERVICE_TO_INSPECT>`.
+
+For more guidance regarding logs, check the [Lando logs documentation](https://docs.lando.dev/help/logs.html)
+
+### Untrusted SSL certificate
+
+When you access your local Lando sites through HTTPS, you get an error message in your browser.
+This is expected behavior.
+
+Find out how to solve it in the [Lando blog](https://lando.dev/blog/2020/03/20/_5-things-to-do-after-you-install-lando/).
 
-```bash
-lando pull -r database -m web/sites/default/files
-```
+### Something still wrong?
 
-Where the value after `-r` is the relationship name in the application for the service you want to download, and `-m` is the Platform.sh mount path you want to download.  You may specify as many relationships (multiple `-r` switches) and as many mounts (multiple `-m` switches) as you wish.
+[Get in touch with Lando](https://docs.lando.dev/platformsh/support.html).
diff --git a/styles/Vocab/Platform/accept.txt b/styles/Vocab/Platform/accept.txt
@@ -91,6 +91,7 @@ transclusion
 [Uu]ncomment
 unencrypted
 [Uu]nmount
+[Uu]ntrusted
 webpack
 Xdebug
 Zend