Goal
Access Platform.sh-hosted services from a local computer, over a secure SSH tunnel.
Assumptions
- The Platform.sh CLI is installed locally.
- Whatever additional software is needed (local web server, local mysql client, etc.) is already installed locally.
Problems
By default the Platform.sh CLI will use the current environment. However, when using a 3rd party integration from GitHub or GitLab the desired environment will likely be a PR environment, not the environment that the user is working on directly. That will require extra commands as shown below.
Steps
1. Open an SSH tunnel
Run the following command locally:
platform tunnel:open
That will open an SSH tunnel to the current environment and map all services defined on the application to local ports. Accessing those ports locally with the appropriate tool (mysql command line, Redis CLI client, etc.) will connect to the service on the environment.
2. Export relationships
Run the following command locally:
export PLATFORM_RELATIONSHIPS="$(platform tunnel:info --encode)"
That will create a PLATFORM_RELATIONSHIPS environment variable locally that provides user/password/host/port credentials to connect to the current environment. A local application that checks that environment variable in order to connect to services on Platform.sh will work just the same as if it were on Platform.sh. (It will not, however, make any other environment variables available.)
It is also possible to combine both commands into a single line, like so:
platform tunnel:open && export PLATFORM_RELATIONSHIPS="$(platform tunnel:info --encode)"
3. Disconnect from the tunnel
When done, clean up the open connections by running:
platform tunnel:close
Alternative: Connect to a Pull Request environment
Both commands above will, by default, use the current branch name/environment. However, the environment created by a Pull Request from GitHub, Bitbucket, or GitLab will be different and thus the above commands will not connect to them. To access a Pull Request environment modify both commands to specify the environment name.
For example, a GitHub Pull Request #42 will have an environment name on Platform.sh of pr-42, so run:
platform tunnel:open -e pr-42 && export PLATFORM_RELATIONSHIPS="$(platform tunnel:info --encode -e pr-42)"
The -e pr-42 (or equivalently --environment pr-42) tells the CLI to connect to the pr-42 environment rather than the environment that corresponds to the branch currently checked out.
Conclusion
With access to the remote services, customers can take whatever action they need. That includes running code locally against a remote service, accessing the service using a management tool appropriate for that service, or any other task. Just remember the caveat about Pull Request environments.