DocsTelepresence
1.0
Local development with PHP
Local development with PHP
Author: Solomon Roberts (@BadgerOps)
Install Telepresence with Homebrew/apt/dnf
You will need the following available on your machine:
kubectl
command line tool (here's the installation instructions).- Access to your Kubernetes cluster, with local credentials on your machine. You can test this by running
kubectl get pod
- if this works you're all set.
OS X
On OS X you can install Telepresence by running the following:
Ubuntu 16.04 or later
Run the following to install Telepresence:
If you are running another Debian-based distribution that has Python 3.5 installable as python3
, you may be able to use the Ubuntu 16.04 (Xenial) packages. The following works on Linux Mint 18.2 (Sonya) and Debian 9 (Stretch) by forcing the PackageCloud installer to access Xenial packages.
A similar approach may work on Debian-based distributions with Python 3.6 by using the Ubuntu 17.10 (Artful) packages.
Fedora 26 or later
Run the following:
If you are running a Fedora-based distribution that has Python 3.6 installable as \`python3\`, you may be able to use Fedora packages. See the Ubuntu section above for information on how to invoke the PackageCloud installer script to force OS and distribution.
Arch Linux
Until we have a *correct and working* AUR package, please install from source. See issue #135 for the latest information.
Windows
See the Windows support documentation.
Install from source
On systems with Python 3.5 or newer, install into \`/usr/local/share/telepresence\` and \`/usr/local/bin\` by running:
Install the software from the list of dependencies to finish.
Install into arbitrary locations by setting other environment variables before calling the install script. See the install script for more information. After installation you can safely delete the source code.
Other platforms
Don't see your favorite platform? Let us know and we'll try to add it. Also try installing from source.
Note: this is heavily influenced by the awesome Local Java development doc by Cesar Tron-Lozai (@CesarTronLozai)
PHP
Telepresence
can help you speed up your development process for any technology, as long as you deploy your service as a Docker image into a Kubernetes container.
In this tutorial we will focus on how to setup a local development environment for a (micro)-service Bar
written in PHP.
This is very useful if your application is formed of many such services which cannot run on a single development machine. In which case it's easy to setup a separate Kubernetes cluster dedicated for development.
Telepresence
will help us locally develop our service Bar
as if it was still inside the Kubernetes cluster. It's a win-win!!
Architecture
The idea is quite simple, Telepresence
will start a Docker container on your local machine, remove the running pod for Bar
and replace it with a two-way proxy to your local docker container.
If other services in your cluster want to talk to Bar
, they'll get redirected to your local process. If your local process wants to talk to any other services running in your cluster, Telepresence
will redirect the calls to your cluster.
It will also maintain all the environment variables defined in your deployment. It's magical.
In order to run our PHP application in a local Docker container, we can simply start a container which has PHP and Apache installed, mount the source directory to our code, and start coding!
In this tutorial we will be using PHP 7.2 and an Apache based container.
PHP-FPM NOTE:
this could also work with PHP-FPM + Nginx, you'd just need to adjust the default xdebug port of 9000 because that will conflict with the PHP-FPM listener port. I haven't had time to test PHP-FPM + Nginx, and will update this tutorial when I'm able to.
Building inside a docker container
As mentioned above, the goal is to compile and run our code inside a Docker container which Telepresence
can use to replace the pod running in your cluster.
Let's build the command step by step.
telepresence
RunsTelepresence
!--container-to-host 9000
Forward port 9000 inside the container back to your computer's localhost on port 9000. This allows us to use xdebug for debugging and stepping through code.--new-deployment bar
Create a new deployment calledbar
- you could also use `-swap-deployment bar
if you want to test against an existing configured cluster.--docker-run
TellsTelepresence
to run a Docker containers--rm
Tells Docker to discard our image when it terminates (no need to clutter your computer)-v$(pwd):/var/www/html
Mounts the current directory (result of thepwd
command) into a/var/www/html
folder inside the Docker container. This is where your source code will be; and mounted in the container where Apache is configured to look for php/html files to serve.- you could also specify the fully qualified path to your code repo if you don't want to execute this command in your code directory.
-p 8080:80
Forward Apache on80
to http://localhost:8080 so you can hit your web service with your browser on your local computer.myapp:01
The container that you are wanting to execute with the Telepresence command.
And that's it! You can easily create a telepresence.sh
file in the root of your project with the following:
telepresence.sh
Example of how to test Telepresence + PHP
The key piece here is the --container-to-host 9000
(Note, if you're using php-fpm, then you'll want to forward a different port for xdebug, since php-fpm uses 9000)
This creates a reverse connection from the container that your code is executing in back to the host machine so your xdebug listener can receive the connection.
Create an index.php
with the following content:
Next, create a Dockerfile with the following contents:
This is taking the base PHP:7.2-apache docker container and inserting our xdebug configuration so xdebug will run when we execute our myapp
container.
Next, you'll build the myapp
container:
Finally, execute your Telepresence command we built earlier:
And here is what example output should be (Using Telepresence build 0.102 in Oct of 2019 )
We can see that the container port 9000 is forwarded to our host port 9000, and Apache launches.
I use PHPSTorm for PHP development, so I used the PHPStorm xdebug guide to configure my browser (with the xdebug extension) and debugger in PHPStorm. We've also set up IntelliJ IDEA to debug with the same steps.
You should then be able to turn on your debug listener in your IDE, set a breakpoint, and navigate to http://localhost
in your browser to load the code and hit your breakpoint!
This tutorial adapted from a very basic example in this blog post - if you have any problems or questions, feel free to join the telepresence slack or reach out to @BadgerOps on twitter.