How to use the Platform.sh CLI from the web container

[bogdan-vasilescu]

Goal

Have the Platform.SH CLI installed and authenticated in the web container.

Assumptions

• Access to a project hosted on Platform.sh
• Your project account has administrator rights
• Knowledge on using the project web interface or Platform.sh CLI

Problems

Using the Platform.sh CLI directly from the web (application) container can be required to automate certain tasks, like renewing the SSL certificate or triggering a snapshot based on a cron schedule.

Due to the non-interactive deployment flow, using a regular username and password authentication is not possible. We will use token-based authentication to have the CLI installed and configured on each deployment.

Steps

0. Create a dedicated account to use for automated tasks

This step is optional, but _ strongly recommended_: for automated tasks, a dedicated user should be created and added to the project. Adding an API token to a project is a security risk, as it means the token will be visible to the other project members who have SSH access, so they will then also have access to the token’s account.

1. Create an API token

Log in and navigate to Account settings > API tokens, available here. Click on Create API token.

You will be asked for the token name - enter a name to easily identify your token in the future, in case of multiple tokens (CLI automated is one example). Click on Create API token to save the token.

Once done, the newly created token will be displayed at the top of the page, and can be copied to the clipboard using the Copy button. After this, you will not be able to view the API token again.

2. Add the token as an environment variable in the project

Once the API token is added as an environment variable in the project, it will be automatically detected and used by the CLI tool. After the installation is done, you should see the PLATFORMSH_CLI_TOKEN variable when running env.

• Option 1: Using the web interface

  Open the project web interface and navigate to the environment in which you want to use the CLI, then click on Configure environment and go to the Variables tab. Add a variable named env:PLATFORMSH_CLI_TOKEN and set its value to the previously created token.

  

• Option 2: Using the CLI

  If you have the CLI tool installed and configured, you can add the variable from the command line:

  platform variable:create -e <ENVIRONMENT_NAME> --level environment --name env:PLATFORMSH_CLI_TOKEN --sensitive true --value <TOKEN>
  

  Replace the <environment name> and <token string> with the correct values for your use case.

3. Install the CLI tool in the application container

Once the variable has been added to the environment, it is required to download and install the CLI tool in a build hook.

Modify .platform.app.yaml in the project to include:

hooks:
    build: |
        curl -fsSL https://raw.githubusercontent.com/platformsh/cli/main/installer.sh | bash

This will download the CLI to a known directory, .platformsh/bin , which will be added to the PATH at runtime (via the .environment file). Redeploy your environment and log into the application container with SSH, then run platform. You should see the welcome prompt and a list of your current projects.

Conclusion

Having the CLI tool set up in an environment opens up further automation possibilities - renewing the SSL certificate, triggering snapshots, etc.