This guide contains information to help onboard developers to work on the Platform.sh integration, hereafter referred to as "the plugin".
At the very least you will need to have the following installed:
- Lando 3.5.0+, preferably installed from source.
While not a hard requirement it's also probably a good idea to install both
node 14 and
# Clone this repo git clone https://github.com/lando/platformsh.git && cd platformsh # Install dependencies with lando lando start # Or install them with yarn yarn
This plugin contains various working and tested Lando apps in the examples folder. You should use these or create new ones to help with plugin development.
Note that each one of these examples contains the following section in its Landofile.
plugins: "@lando/platformsh": ./../../
This tells Lando that this app should use the source version of the
@lando/platformsh plugin you cloned down in the installation. This is useful because it allows you to isolate development within this repo without interferring with any other apps using the stable and global version of the plugin.
This means that you should almost always develop against apps in the
examples folder and that those apps should always contain the above
plugins config. If you have an extant Lando application you want to develop against you can temporarily tell it to use the cloned down version of the plugin with the same line.
plugins: "@lando/platformsh": /path/to/plugin
Whether you are working off an existing example or a new one you should make sure that you are updating or adding new tests as you go. See leia testing below for more detail.
Here are some things that deviate from Lando-normal that you should be aware of.
Platform.sh uses a more complex container lifecycle than Lando. That lifecycle is detailed here.
Most of the Platform.sh magic comes from a configuration file located in every service at
/run/config.json. Lando generates and injects this file into each container.
It is constructed by combining the Platform.sh configuration files eg
services.yaml etc and some extra things.
Services and Types
Inside of the
services folder you will see where we define the Lando service that corresponds to each platform application container and service. Each service can either be a
platform-appserver or a
plaform-service and each of these are defined in the
platform-appserver means it is an applicaton container eg a supported Platform.sh "langauge" eg a
type you can define in a
platform-service means it something that goes in the
If you want to add support for a new platform service or application container simply add a new one into the
services folder and make sure you set the
parent to either
_platformsh_appserver as appropriate.
Also note that you will likely need to add it to
getLandoServiceType which maps a
type to a
type. See https://github.com/lando/platformsh/blob/main/lib/services.js#L9 for
index.js you will see that
lando is overriding the core
lando ssh command. This serves two main purposes:
- To select the default
serviceto run on. The default service will be set to the closest
.platform.app.yamlLando can find. The
nameof the application in that file is also the name of the service.
- To make sure all
lando sshcommands are prefixed with
/helpers/psh-exec.sh is a helper script that makes sure the user environment is set correctly before commands are run. Primarily this makes sure that
$HOME is not set to
/app and that the
PLATFORM_ variables are set before the command is run.
index.js all tooling commands are prefixed by
Troubleshooting Python Source in Platform.sh Containers
When viewing container logs, you may see references to python files like
You will find the python source code in the following directories:
Known issues and caveats
We recommend reviewing the known issues and caveats in the usage documentation.
If you want to help with contributing documentation here are some useful commands once you've cloned and installed the project.
# launch local docs site yarn docs:dev # build docs locally yarn docs:build
If you are more interested in the internals of the docs they use VuePress2 and our Special theme.
It's best to familiarize yourself with how Lando does testing in general before proceeding.
Generally, unit testable code should be placed in
lib and then the associated test in
tests in the form
FILE-BEING-TESTED.spec.js. Here is an example:
./ |-- lib |-- stuff.js |-- test |-- stuff.spec.js
And then you can run the tests with the below.
# Run unit tests yarn test:unit
We do end to end testing with our made-just-for-Lando testing framework Leia. Leia allows us to define tests as a series of commented shell commands in human readable markdown files. Here is a simple example:
Start up tests -------------- # Should start up successfully lando start Verification commands --------------------- # Should be able to connect to all mariadb relationships lando mariadb main -e "show tables;" Destroy tests ------------- # Should be able to destroy our app lando destroy -y
Note that the headers here are important and are defined in our
yarn generate:tests script. The Start up tests header specifies things that should run before the main series of tests. Verification commands is the main body of tests and is required. Destroy tests specifies any needed clean up commands to run.
If you check out the various READMEs in our examples you will notice that they are all Leia tests.
Before running all or some of the tests you will need to generate them.
# Generate tests yarn generate:tests # Run ALL the tests, this will likely take a long time yarn test:leia # Run the tests for a single example yarn leia examples/mariadb-10.2/README.md -c 'Destroy tests'
If you've created new testable examples then you will also need to let GitHub Actions know so they can run on pull requests.
To do that you will either want to add the tests to an existing workflow that makes sense or create a new workflow. If you are creating a new workflow you should just copy an existing one and modify the filename and
name key to something that makes sense.
To add the new tests to the workflow just modify
jobs.leia-tests.strategy.matrix.leia-tests with the new tests.
jobs: leia-tests: strategy: matrix: leia-tests: # This should be the filename, without .leia.js extension in the test directory # NOTE that you will need to run yarn generate:tests to see these - test: platform-sh-maria-db-10-1-example # This should be the directory that the test was generated from source: examples/mariadb-10.2 - test: platform-sh-maria-db-10-2-example source: examples/mariadb-10.2
Now open a pull request and the new tests should run!
For a deeper dive on Leia you can go here.
To deploy and publish a new version of the package to the
npm registry you need only create a release on GitHub. That said, in order to create a release and succesfully publish it to
npm you will want to make sure:
- You have tagged the commit you want to deploy in
gitand pushed it up to GitHub
- You have bumped the version in your
package.jsonso that it doesn't collide with a version already published to
In order to help with the above we recommend you run the convience command
yarn release which will take care of both.
Also note that if you create a "pre-release" it will tag the
npm package with
edge instead of the default
latest tag. Also note that while you can toggle the pre-release checkbox after the initial release creation this will not trigger a new release and/or promote the release from
latest. If you want to deploy to
latest then create a new release without pre-released checked.
# Will pull the most recent GitHub release yarn add @lando/platformsh # Will pull the most recent GitHub pre-release yarn add @lando/platformsh@edge
If you want to contribute code then just follow this flow.