Docker Tomcat container SSH tips and tricks

Explains how to define environment vars available for tomcat inside docker container when JAVA_OPTS is not enough. We’ll explore some examples are based on one of our favorite customer’s projects.

Intro

Hello! In this post we’ll discuss a real customer use case and talk about some of the issues we solved in the process.

The customer’s architecture requirements included interfacing with a third party service into our custom PHP framework code. As the customer’s requirements also stipulated the service code must be written in Java (or .Net) we had to introduce Tomcat into the equation.

Even though PHP and Tomcat shared the server on the initial system, we decided to wrap all services within their own Docker containers.

Creating a Docker container for Tomcat

Let’s start with a docker-compose file that will define our tomcat container. We used tomcat:8.5.13-jre8-alpine as the base image.

At first glance this file contains 3 big sections, volumes, ports and expose.

The Volumes section will map files and folders needed to run a tomcat instance, included our app. You will notice in the example below that I included, in addition with .war file, JKS certificates and some configuration files I will explain later in this post.

The ports section will just bind container’s listen port with internal tomcat port (8080).

In the expose section we open some ports, in particularly 8009, that is required for server admin.

version: '2.1'

services:
  my_tomcat:
    container_name: my_tomcat
    image: tomcat:8.5.13-jre8-alpine
    volumes:
      - ./conf/catalina.properties:/usr/local/tomcat/conf/catalina.properties
      - ./client-keystore.jks:/etc/tomcat/client-keystore.jks
      - ./truststore.jks:/etc/tomcat/truststore.jks
      - ./myApp.war:/usr/local/tomcat/webapps/myApp.war
    env_file: ./environment.env
    ports:
      - "8080:8080"
    expose:
      - "8009"
      - "8080"

Setting our environment vars

As you may have noticed, we isolated the environment variables out of the docker-composer, in a new environment.env file, specified in env_file.

In addition to defining container variables, it will define JVM  requirements, such as JAVA_OPTS.

SHELL=/bin/sh


TOMCAT7_GROUP=tomcat7

TOMCAT_CFG_LOADED="1"

JAVA_OPTS="-Djavax.net.debug=ssl,handshake,keymanager,verbose  -Dendpoint=https://3rd-party.domain.com/services/api.wsdl -Djavax.net.ssl.keyStore=/etc/tomcat/client-keystore.jks -Djavax.net.ssl.keyStorePassword=secret -Djavax.net.ssl.trustStore=/etc/tomcat/truststore.jks -Djavax.net.ssl.trustStorePassword=changeit -Djava.awt.headless=true -Xms512m -Xmx2048m -XX:+UseConcMarkSweepGC -Dhttps.protocols=TLSv1,TLSv1.1,TLSv1.2 -Djdk.tls.client.protocols=TLSv1.1,TLSv1.2 -Dsun.security.ssl.allowUnsafeRenegotiation=true"

SECURITY_MANAGER="false"

For this example, we’re telling the JVM to show verbose debug info for ssl and keymanager use (-Djavax.net.debug), which is the endpoint of the service (-Dendpoint), keystore and truststore files and passphrases repectively (-Djavax.net.ssl.keyStore, -Djavax.net.ssl.keyStorePassword, -Djavax.net.ssl.trustStore and -Djavax.net.ssl.trustStorePassword), among others.

Unfortunately, this is not enough with Alpine based container. In shortest explanation, when you start the container it runs catalina.sh that loads default configuration from the image.

But don’t panic, here’s the trick: the custom configuration can be placed in the catalina.properties file, letting those vars available for the system to be accessed like below:

System.getProperty("endpoint");

These custom properties file will be mounted as volume, replacing the default one and voila.

./conf/catalina.properties:/usr/local/tomcat/conf/catalina.properties

Adding and managing a Keystore

Once you have created your certificates stores (there is a powerful tool provided by Java, the keytool, which will be a topic for our future blog post), just copy the catalina.properties from standard tomcat and append variables at the end:

endpoint=https://3rd-party.domain.com/services/api.wsdl
javax.net.ssl.keyStore=/etc/tomcat/client-keystore.jks
javax.net.ssl.keyStorePassword=secret
javax.net.ssl.trustStore=/etc/tomcat/truststore.jks
javax.net.ssl.trustStorePassword=changeit

Final Thoughts

While this was a unique project, the common solution often works well. When I ran into common issues I also found a lot of recommendations for adding or updating a JAVA_OPTS environment variable. We did end up improvising to a point, but this was mostly reserved for edge cases.

I am glad you’re still here! Thank you and hope you have enjoyed reading. See you in next posts.

oAuth – Part 2

A practical example of oAuth integration into your system for authentication process.

Hello readers, today we will walk through a practical example about how to implement a simple login using the oAuth concepts described
in the previous post. To accomplish this goal we going to to create a new Erdiko project with three additional package that will help us to interact with Facebook API. Those packages are Erdiko-Authenticate and oauth2-client  and oauth2-facebook from The League of Extraordinary Packages. But before we can start coding we need to create a developer account and register our app.

How to register your app

This is the easy step; let’s demonstrate how to register using Facebook.
The first step is login in the developers site and sign in with a valid Facebook user. The next step is set you as Developer. To do this go to account, click on the button and follow instructions. Easy, right?
And the last step is to complete and submit this form. That’s it! Now you have registered your app to use Facebook API.

Prepare host project for the example

In this step we just need to create a new Erdiko project, for more details please refer to Erdiko

composer create erdiko/erdiko oauth_authenticate_sample

The next step is add the additional libraries.

In both cases, inside the project directory, will add new required packages

composer require erdiko/authenticate
composer require league/oauth2-client
composer require league/oauth2-facebook

setup erdiko-authenticate

Once it’s added we will need to add the config file in app/config/default/authenticate.json this is an example:

{
  "authentication": {
    "available_types": [{
      "name": "mock",
      "namespace": "erdiko_authenticate_Services",
      "classname": "Mock",
      "enabled": true
    }]
  },
  "storage": {
    "selected": "session",
    "storage_types": [{
      "name": "session",
      "namespace": "erdiko_authenticate_Services",
      "classname": "SessionStorage",
      "enabled": true
    }]
  }
}

we will revisit this file in future sections.

SETUP oAuth2 Client (from thephpleague)

This package doesn’t need a special configuration, but let’s take a look at constructor parameters we will user in our extension.

$provider = new \League\OAuth2\Client\Provider\GenericProvider([
    'clientId'                => 'demoapp',    
    'clientSecret'            => 'demopass',   
    'redirectUri'             => 'http://example.com/yourredirecturl/',
    'urlAuthorize'            => 'http://example.com/oauth2/authorize',
    'urlAccessToken'          => 'http://example.com/oauth2/token',
    'urlResourceOwnerDetails' => 'http://example.com/oauth2/resource'
]);

clientId and clientSecret, come from the dashboard of your registered app, in the picture below are App ID and App Secret.

redirectUri, is a public URL in your server where you will be redirected after oAuth server finish the authentication process (Facebook in our example)

The last three keys (urlAuthorize, urlAccessToken and urlResouceOwnerDetails) will change based on which service we are using. In the above block, we assume that the the oAuth server is placed in example.com, maybe our custom implementation.

Create new Service class

We will implements AuthenticationInterface that way we can inject it in our authenticate package thru autenticate.json config file we added previously.

In authentication section you will have to add a new entry in available_types array:

{
      "name": "oauth",
      "namespace": "app_services",
      "classname": "oAuthAuthenticator",
      "enabled": true
}

In the constructor method of this class we will create a provider instance for the client, but we will use the third package (oauth2-facebook) to simplify things:

namespace app\services;


use erdiko\authenticate\AuthenticationInterface;
use \League\OAuth2\Client\Provider\Facebook;

class oAuthAuthenticator  implements AuthenticationInterface
{
    protected $provider;

    public function __construct()
    {
        session_start();

        $this->provider = new Facebook([
            'clientId'          => '1925853064368417',
            'clientSecret'      => '55ea4c1a56ca6d1db485b954ZZZ',
            'redirectUri'       => 'https://example.com/login/setlogin',
            'graphApiVersion'   => 'v2.8',
        ]);
    }

    public function login($credentials)
    {
        if(!$this->checkLoggedUser()) {
           $authorizationUrl = $this->provider->getAuthorizationUrl();
           $_SESSION['oauth2state'] = $this->provider->getState();
           header('Location: ' . $authorizationUrl);
           return;
        }
    }

    protected function checkLoggedUser()
    {
       return (
            isset($_SESSION['code']) 
            && isset($_SESSION['oauth2state'])
       );
    }

    public function verify($credentials)
    {
       return true;
    }
}

 

As you can see in the login method, I’ve added a simplistic check for a logged user, if there’s no record in session will redirect to login popup. Now we’re delegating the authentication process to Facebook, and the result of this process will be finally handled by method getSetLogin in the login controller.

Use new service in a Login Controller

In this example we are using a Login Controller just to keep authentication logic isolated. This is a normal erdiko controller, where we will have three basic actions: getLogin – that will load a basic -authenticator and invoke the login method. This action will be loaded when you click on Login with Facebook buttons that you can find everywhere these days.

public function getLogin()
{
   $authenticator = new BasicAuthenticator(new User);
   
   $authenticator->login(array(),'oauth');
}

getSetLogin – a callback method – is responsible to manage Facebook response and storage user in SESSION.

public function getSetLogin()
{
    $authenticator = new BasicAuthenticator(new User());
    if (empty($_GET['state']) || ($_GET['state'] !== $_SESSION['oauth2state'])) {

        unset($_SESSION['oauth2state']);
        throw new \Exception('Invalid state.');
    }
    $token = $this->provider->getAccessToken('authorization_code', [
        'code' => $_GET['code']
    ]);
    try{
        $user = $this->provider->getResourceOwner($token);
        $authenticator->persistUser($user);
    } catch (\Exception $e) {
        throw new \Exception($e->getMessage());
    }
}

Finally, we have the getLogout action, that will destroy the SESSION and user won’t be longer authenticated.

public function getLogout()
{
   $authenticator = new BasicAuthenticator(new User());
   $authenticator->logout();
   \erdiko\core\helpers\FlashMessages::set("Good bye, ".$authenticator->currentUser()->getUsername(), "success");
   $this->getLogin();
}

Conclusion

It’s pretty easy to add oAuth features on your system as you can see. Delegating the authentication process to a trusted server, providing users with the ability to use existing trusted accounts is a clear win.

Hope you enjoy this small example! Thanks for reading and hope to see you in my next post!

oAuth – Part 1

OAuth 2.0 is the industry-standard protocol for authorization.

Overview

Welcome, today I will go through the oAuth protocol, some definitions and how it works. In a later post I will show an example of how easy it is to use oAuth with the Erdiko Authenticate package and php league packages.

What is oAuth?

I bet most of you have the same question. We can simply say that it is a protocol definition for authenticate and authorize third party applications to have access to certain user data, without sharing password with the third party app.
In other words, your application will have a token provided from a trusted service (let’s say Facebook, Twitter or any other commercials) once a user has authenticated. That way, you delegate the authentication process to this third-party server. Additionally, with this token you can access to some user’s information, previously granted by user, e.g. profile information.
When using this method we can store the token so our application doesn’t need to remember any extra authentication credentials, don’t need to fill profile fields every time register in a website, relay the security in a Trusted System.

OAuth 2.0

As per oAuth 2 site:
OAuth 2.0 is the industry-standard protocol for authorization. OAuth 2.0 supersedes the work done on the original OAuth protocol created in 2006.

The new version focus on client develop simplicity, and provides specific flows for Web, Desktop and Mobile developments.

Components

Components or oAuth Roles, are the main pieces involved in the auth flow.
  • Client
  • Resource Server
  • Authorization Server
  • Resource Owner
Now let’s break them down:
Client (The Third-Party Application)

Is the application that is attempting to get access to the user’s account. It needs to get permission from the user before it can do so.

Resource Server (The API)

This is the server or service used to access user’s information through an API.

The Authorization Server

This server presents the interface where the user approves or denies the request. In smaller implementations, this may be the same server as the API server, but larger scale deployments will often build this as a separate component.

Resource Owner (The User)

The resource owner is the person who is giving access to some portion of their account.

Protocol Flow

  1. The application requests authorization to access service resources from the user
  2. If the user authorized the request, the application receives an authorization grant
  3. The application requests an access token from the authorization server (API) by presenting authentication of its own identity, and the authorization grant
  4. If the application identity is authenticated and the authorization grant is valid, the authorization server (API) issues an access token to the application. Authorization is complete.
  5. The application requests the resource from the resource server (API) and presents the access token for authentication
  6. If the access token is valid, the resource server (API) serves the resource to the application

You can implement this abstract flow in different ways based on the target architecture: Web Application and Client Application. Where the first one could be any of common web sites that allow us to login using our Facebook or Twitter user, and the last one could be a mobile or desktop app.

In both cases, before start using oAuth, you need to register the application in the Service Provide system, that way you will obtain a client_id and client_secret. The client_secret should be kept confidential and only used between application and Service Provider.

Once you have registered your app,  the first step is to get authorization from the user.

This is usually accomplished by displaying an interface provided by the service to the user.

The version 2 provides several “grant types” for different use cases. The grant types defined are:

  • Authorization Code for apps running on a web server, browser-based and mobile apps
  • Password for logging in with a username and password
  • Client credentials for application access
  • Implicit was previously recommended for clients without a secret, but has been superseded by using the Authorization Code grant with no secret.

The first step is create a login link to redirect a user to Auth Server where will be authenticated. This link might include the callback URL (this could vary depends on server implementations, some systems require the callback URL in the app registration form). This is the URL user will be redirected to after login.

In case of success this redirect will include a Grant Code, that will be needed in the Token Exchange step.

After a succeed login, with Grant Code and Access Token the client app, will request the access token, that will be used as credential on future request.

Final thoughts

Hope this roughly overview brought up some light into the oAuth Protocol concepts. In the next episode, I will bring you a practical example of how to implement a client module with erdiko/authenticate package.

Dependency Injection

Dependency Injection is a widely used design pattern. We will define the concepts of this pattern and show a popular PHP implementation with a simple example.

What is DI?

Dependency Injection is a software design pattern that implements Inversion of control by decoupling software modules, introduced by Martin Fowler.

Usually a dependency injection container is used to manage and automate the construction and lifetimes of interdependent objects.

di_uml

Design pattern explanation and Use

Basically, if your class needs an object of other class, in this pattern you pass the dependency object as a constructor parameter or via property setters, instead of invoke factory or create dependency. You make it someone else’s problem.
Example 1:
class MyClass {
    private $objectA;
    public function __construct(ObjectA $object) {
        $this->objectA = $object;
    }
}
Example 2:
class MyClass {
    private $objectA;

    public function setObjectA(ObjectA $object) {
        $this->objectA = $object;
    }
}

In both examples, we don’t care how or where to create the objectA we just use it.

Some popular PHP DI-Container implementations

  • PHP-DI: is an interesting implementation of DI Container that has integration with several frameworks and IDEs like PHPStorm.
  • Symfony DependencyInjection: The DependencyInjection component allows you to standardize and centralize the way objects are constructed in your application.
  • Zend – DI: DI Container implementation for Zend framwork.
  • Pimple: Is a Dependency Injection Container from SensioLabs.

Pimple Presentation

This is an implementation from SensioLabs, and you guessed it, the same guys that created the Symfony libraries.

This is a friendly implemented package, lightweight and easy to use.
To install you just need to add to your composer.json,
$ ./composer.phar require pimple/pimple ~3.0
and you’re ready to use it!
$container = new \Pimple\Container();
Since it implements \ArrayAccess interface, you can store variables and factories as it was an array.
example of parameters:
$container['cookie_name'] = 'SESSION_ID';
an example of factory as a closure:
$container['session'] = $container->factory(function ($c) {
    return new Session($c['session_storage']);
});
It also provides methods to protect parameters, modify services after defined, extends, and more.
For more info refer to Pimple site.

Example Use Cases

Let’s imagine that we want to create factories dynamically based on a JSON configuration like this:
auth_config1
Then we can create a Trait with a method that will fill our container based on an argument that could be an array create from the decode of above JSON.
traits_builder
Here’s how we can use this trait:
di_using
Let’s break down the example above:
the class that implements the __construct method has defined a member attribute, container, that is an instance of Pimple.
Since we are using traits to buildAuthenticator, the result of the foreach block will be assigned into the class container attribute.
Within the build, we need to create a new temporary Pimple object. This is a hack I found to store nested containers.
This is needed because otherwise each time you attempt to add a sub-item within the “AUTHENTICATION” it overrides the previous one.
So once we have created all factories, we just set the temporal container in “AUTHENTICATION” cell of the main container.
To use your created object in the container you just need to do something like that:
$auth = $this->container["AUTHENTICATION"]["mock"];
$result  = $auth->doSomething();

Final Thoughts

This pattern is very useful and widely used these days especially in modern web development, in particular if you see it used in the Angular framework.
Even when you should pick the product that better match your requirements in each case, I can say that I feel very comfortable with Pimple. As I showed, it is very flexible, allowing you to create your own wrap class to customize its behavior and fit your needs.
Hope you enjoyed! Thanks for reading and see you on next posts!

User Auth… What does it really mean?

Auth, a widely use term that can be a bit confused. We will show the meaning and how to work with both definitions as a system.

Auth, a term we can see every where these days. But, what does it really mean?
Honestly, it can be confusing when just saying Auth. Are you talking about authorization or authenticating?
More over, which is the difference between those two terms? Yeah, you got the point!

So now that I have your attention, let’s start by explaining what each is and how they are different and then how we can use both in our systems.

Difference between Authenticate and Authorize

We can roughly say, in the context of computer systems, authenticate is the process that ensures and confirms a user’s identity.

In other hand we can say that authorize or authorization, is the process responsible to determine the level of access that a user has in relation with a resource.

As you may already guessed, both of these should work together as a team.

That’s cool, but how to do that?

Let’s start with Authentication

Okay, starting from a very basic example, where you need to present two keys to the system, for example, username and password, where the first one will identify you and should be unique all system wide, and the other one would confirm that you are who you said you are.

Nowadays there are other architectures that requires multi-level security layers, tokens like oAuth, and so on, but I won’t go deeper on those in this post since this is just an overview.

So, going back to the previous example, you can tackle it at different level. That means, you can go with Sysadmins and request to keep .htaccess and .htpasswd files up to date, or you can choose to tackle at application level.

As you may guess, we will discuss the last one, programmatically. Here, again, we have a bunch of alternatives based on languages, patterns, etc.

My first thought when I had to work on that was, “why should I choose one? why not define an structure that let users select and implement the most appropriate for  each project?”
Yeah, sounds great, but how can I accomplish it? Well, actually is not a big deal (unless you’re trying to reinvent the wheel), is just take a look at already implemented things. The Database layer was my inspiration.

Let me explain how so. I’ve started defining a minimal interface that any Authenticator class should implement, that way I ensure that my controllers will not be broken when I change the configuration.

iauth

As a second step, I’ve added another two interfaces, one that defines requires method to store and retrieve “session” record of current user, and the other that ensure we have at least a “login” method.

storage_interface

Finally, I mixed all this stuff in a basic atuhenticator class, that with the use of Dependency Injection pattern (Pimple in my case) allow us to load based on a config file, any authenticator class that implements our interfaces. That means, I can choose to authenticate against a plain text file, database record or oAuth server like Facebook or Twitter, I just need to implement the logic for the selected service and put it in a config file.

mock_auth

And what about Authorization?

The good news is there’s a lot of alternatives. The bad news is that most of then are not implemented for all languages, instead, it seems that each programming language pick one and discard the other.

Don’t worry, most of them can be categorized in one of those big groups:

  • Role-based access control

from wikipedia

In computer systems security, role-based access control (RBAC) is an approach to restricting system access to authorized users. It is used by the majority of enterprises with more than 500 employees, and can implement mandatory access control (MAC) or discretionary access control (DAC). RBAC is sometimes referred to as role-based security.

Role-based-access-control (RBAC) is a policy neutral access control mechanism defined around roles and privileges.

  • Access Level Control

from wikipedia

An access control list (ACL), with respect to a computer file system, is a list of permissions attached to an object. An ACL specifies which users or system processes are granted access to objects, as well as what operations are allowed on given objects. Each entry in a typical ACL specifies a subject and an operation. For instance, if a file object has an ACL that contains (Alice: read,write; Bob: read), this would give Alice permission to read and write the file and Bob to only read it.

  • Identity Management

from wikipedia

In computer security, identity and access management (IAM) is the security and business discipline that “enables the right individuals to access the right resources at the right times and for the right reasons”. It addresses the need to ensure appropriate access to resources across increasingly heterogeneous technology environments and to meet increasingly rigorous compliance requirements.

In my case, I based on Ruby On Rails’ CanCan gem. Is very nice the way they implemented the “ability” class to grant users and groups the access to specific resource.
This time I’ve based on AC\Kilinka (compose package from American Council) and basically extended it to cover my needs.
Let’s breakdown a bit to make things more clear, there are two big parts, Authorizer and Guard, and two interface that defines them.
The first one, GuardInterface define four basic methods that will be responsible for get and check policies related with an specific resource, the other one, AuthorizerInterface, has two method, one for register guards and “can”, that decides if an action on a resource is permitted.
kalinka_guardinterface
kalinka_authorizerinterface

 

This package also provides some basic implementations. I’ve chosen RoleAuthorizer that better match to my needs, because users used to have a role associated. However, you can use a SimpleAuthorizer that allows you to allow/deny access by user instead of group.

The main difference is the way you config your permissions, here’s an example of what I did in a JSON format:
auth_json

Final thoughts

I have presented a brief overview about how you can identify users and manage permissions to your app resources.
Hope you enjoyed, thanks for reading, and stay tuned in this blog because we will bring you a new Erdiko packages that implements those things, soon!

Docker + xdebug

Presenting various ways to setup and configure your docker container with xdebug and how to integrate with your IDE.

Debugging, an issue that all developers should live with.

There are several strategies we can use to manage debugging, from stopping execution after dump / print the content of the variable we want to inspect (I still with this more often that I’d like to admit) to more sophisticated tools or web-server  modules.

Okay, it does not enough complicated so, now let’s add DevOps. Yeah, if you want to use a tool like xdebug (here is a great tutorial about how to install it Remote PHP Debugging with Xdebug) within Docker containers.

Some questions came to my mind when I stumbled upon this situation: How do I setup the container? How can I expose xdebug outside of my containers? How can I integrate remote debugging with my IDE workflow?

Well, I don’t have the answer for all this questions, but I will show some examples and tips various ways to setup xdebug inside your docker container and connect it with PHPStorm.

Creating Docker container

This step is pretty much the same for all alternatives and OS platforms. Here we will discuss the very basic settings to create a container.

My example will be based on a clean Erdiko project, so I already have the structure to test, umm debug, some code.  To try out the container clone from github, https://github.com/arroyolabs-blog/docker-xdebug

So let’s start creating a custom Dockerfile that will look like this:

FROM php:5.6-fpm
MAINTAINER Leo Daidone <leo@arroyolabs.com>

RUN apt-get update && apt-get install -y \
    libpq-dev \
    libmemcached-dev \
    curl

# Xdebug
# here is the installation
RUN pecl install xdebug \
    && docker-php-ext-enable xdebug
# here I'm copying the config file we will discuss in the next section
COPY ./etc/xdebug.ini /usr/local/etc/php/conf.d/

RUN usermod -u 1000 www-data

CMD ["php-fpm"]

We need to create this file instead of use the official php:5.6-fpm image, because we need to run the pecl install command within the created container. Note that I also copied “xdebug.ini” from etc folder, both, folder and file should exists in the same directory as Dockerfile, otherwise you will need to change the source path to the real location of your custom “xdebug.ini”. I choose this way because I think is easier to maintain an .ini file instead of a bunch of bash command.

Now we will need a docker-compose.yml to orchestrate the whole setup. Let’s break down the example below:

version: '2'
services:
  data:
    image: busybox
    volumes:
      - ../:/var/www/code
      - ./nginx/:/etc/nginx/conf.d

  web:
    image: nginx
    volumes_from: [data]
    links:
      - fpm
    ports:
      - "8088:80"

  fpm:
    build:
      context: .
      dockerfile: Dockerfile-PHP
    volumes_from: [data]
    environment:
      PHP_IDE_CONFIG: "serverName=docker"

I’ve defined three services, data, a busybox with the only purpose of mount and map volumes that will be shared by the other services. One web service that is an official Docker nginx image, the web server I will use in this example, finally, fpm, that will be based on our previous Dockerfile and where we will discuss variations in the next section.

Note that I’m not exposing the 9000 port (the default xdebug port) in any of Docker settings. This is the first trick for Linux, do not expose the port, just use it. That way when you try to use you IDE, you will not see an error like

Can't start listening for connections from 'xdebug': Port 9000 is busy.

Setting up xdebug

xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_handler=dbgp
; port 9000 is used by php-fpm
xdebug.remote_port=9000
xdebug.remote_autostart=1
; no need for remote host
xdebug.remote_connect_back=1
xdebug.idekey="PHPSTORM"

This is the basic configuration I use with the Docker code defined in the previous section. It should work fine on Linux boxes, but I found some issues trying to run it in Mac OS. I will show you some changes I tried that worked on both OS.

First issue I found when I tried to make my project works on Mac was the ports’ binding and interfaces. How can I overcome the port busy error?

After some tries I found a nice trick, I recommend, add an alias to our interface with static IP.

In Mac:

sudo ifconfig en0 alias 10.254.254.254 255.255.255.0

In Linux:

sudo ip addr add 10.254.254.254/24 brd + dev eth0 label eth0:1

Now in order to use this new static IP, we need to add this two new lines in our xdebug.ini:

xdebug.profiler_enable=0
xdebug.remote_host=10.254.254.254

I suggest set to zero all other lines except for “remote_enable” and of course “remote_port“.

Finally, our docker-compose.yml shold looks like this:

version: '2'
services:
  data:
    image: busybox
    volumes:
      - ../:/var/www/code
      - ./nginx/:/etc/nginx/conf.d

  web:
    image: nginx
    volumes_from: [data]
    links:
      - fpm
    expose:
      - "9000"
    ports:
      - "8088:80"

  fpm:
    build:
      context: .
      dockerfile: Dockerfile-PHP
    volumes_from: [data]
    environment:
      PHP_IDE_CONFIG: "serverName=docker"
      PHP_XDEBUG_ENABLED: 1 # Set 1 to enable.
      XDEBUG_CONFIG: remote_host=10.254.254.254

Note that now I’m exposing “9000”, this is because I’m using a different IP address to bind this port. Also I’ve added two new environment vars, one to enable xdebug and other to set the remote host address.

Configuring you IDE

As I mention above, I’m going to use PHPStorm to show you how to setup a Debug client. For practical purpose it will be separated in two sections, the first one based on Linux approach, and other for Mac.

But first let me start with common steps for all platforms:

you will need to go to Settings ( linux shortcut: ctrl+alt+s; Mac shortcut: Cmd+, ) and check in Language & Frameworks / PHP / Debug looks like the image

linux_xdebug

After that go to DBGp Proxy and follow the steps for each platform

preferences

Linux example

Since you are using localhost (127.0.0.1) and xdebug has PHPSTORM as ide_key those two values can be empty here:

linux_dbgp

now you have to go to Debug configuration:

server_dropdown

with the green plus sign, add a new PHP Remote Debug, change Name to docker, fill Ide Key field, and click on periods to add a new server

linux_remote

after you click on periods this new window will be opened. Again, click on green plus sign to add a new server that will be named docker, fill all field as it’s being shown, including Use path mappings check, this is a very important step, you need to let IDE know how to related docker path with local path.

linux_servers

Mac example

Assuming here you are using the tweak settings with IP alias, the steps are the same as linux, just need to change values for the one in screenshots:

preferences_2

run_debug_configurations

Note this time Host field is not 127.0.0.1 but the new alias IP.

servers

Finally, to start debugging just click on the phone icon and green bug icon

server_dropdown

add some breakpoints and happy debug!

 

Thanks for reading, I hope you have enjoyed this article and don’t miss our next entry where I will bring you a tutorial about PHPdbg, and how to use it with Docker.

Go basics – Control Structures (Part 2)

Presenting two important concepts you’ll need to know for your GoLang journey: Objects and Concurrency. Understanding these will allow us to talk about toolkits, frameworks, ORMs.

Today I’m going to present two important concepts you’ll need to know for your Go journey: Objects and Concurrency. That will allow us to talk about toolkit, frameworks, ORMs and so on, in future posts.

Object-Oriented Programming (OOP)

Overview

Is Go an Object Oriented language? If we use the most simple definition of Object as an abstract data type that has state (data) and provide a behaviour (code), I say Yes.

Since there is no inheritance in Go, we need to think in terms of composition. Except for that, we can find many of the same features like:

  • methods on any type we define, with no boxing or unboxing
  • automatic message delegation via embedding
  • polymorphism via interfaces
  • namespacing via exports

Now let me introduce some concepts with examples that will illustrate it.

Pointers

Go has pointers, but no pointer arithmetic.

x := 5

y := &x

fmt.Println(*y)

Output :

5

y points to x and the value of y is obtained using a * operator. The & operator is used to get the address of a variable.

The new operator is used to allocate memory to a pointer variable.

x := new(int)

*x = 9

fmt.Println(*x)

Output :

9

Structures

Are user-define data types which contains named fields. We can think of them as “object” in Go.

We declare structures using the type and struct keyword. Individual elements of the structure are accessed using the dot operator.

In the next example I also show composition:

type Person struct {
   Name string
   Address Address
   age int
}

type Address struct {
   Number string
   Street string
   City   string
   State  string
   Zip    string
}

Note that Go makes a difference between lower case and capitals in field definitions. The letter case refers to the scope of the field.  Name and Address (above) are public variables and age is a private variable. Capital names are publicly accessible.

This example in PHP looks like:

<?php
class Person {
    public $Name;
    public $Address;
    private $age;
}

class Address {
   public $Number;
   public $Street;
   public $City;
   public $State;
   public $Zip;
}

PHP does not have type hinting at the variable definition level, only the function level.

This type hinting / scalar values gives Go an upper hand when it comes to syntax checking.

Method

We can declare methods on any user-defined type.

A method declaration in Go is just like a function, except it has an explicit receiver, declared immediately before func. This function also takes advantage of named return variables, pre-initializing them for us.

Let’s extend the structures/classes defined in the previous example

func (p *Person) Greet() {
    fmt.Println("Hi, my name is", p.Name)
}

func (p *Person) Location() {
    fmt.Println("I’m at", p.Address.Number, p.Address.Street, p.Address.City, p.Address.State, p.Address.Zip)
}

In PHP:

<?php

class Person {
    public $Name;
    public $Address;
    private $age;
 
    public function __construct($Name,Address $Address, $age)
    {
        $this->Name = $Name;
        $this->Address = $Address;
        $this->age = $age;
    }

    public function Greet()
    {
        print_r("Hi, my name is " . $this->Name);
    }

    public function Location()
    {
        print_r("I’m at "
                . $this->Address->Number 
                . " " . $this->Address->Street
                . " " . $this->Address->City
                . " " . $this->p.Address->State
                . " " . $this->Address->Zip
        );
    }
}

class Address {
    public $Number;
    public $Street;
    public $City;
    public $State;
    public $Zip;

    public function __construct($Number, $Street, $City, $State, $Zip)
    {
        $this->Number = $Number;
        $this->Street = $Street;
        $this->City   = $City;
        $this->State  = $State;
        $this->Zip    = $Zip;
    }
}

Interfaces

An interface type is defined by a set of methods. A value of interface type can hold any value that implements those methods.

package main

import "fmt"
import "math"

type geometry interface {
    area() float64
    perim() float64
}

type rect struct {
    width, height float64
}

type circle struct {
    radius float64
}

func (r rect) area() float64 {
    return r.width * r.height
}

func (r rect) perim() float64 {
    return 2*r.width + 2*r.height
}

func (c circle) area() float64 {
    return math.Pi * c.radius * c.radius
}

func (c circle) perim() float64 {
    return 2 * math.Pi * c.radius
}

func measure(g geometry) {
    fmt.Println(g)
    fmt.Println(g.area())
    fmt.Println(g.perim())
}

func main() {
    r := rect{width: 3, height: 4}
    c := circle{radius: 5}

    measure(r)
    measure(c)
}

And this how it looks in PHP

<?php
interface geometry
{
    public function area();
    public function perim();
}

class rect implements geometry
{
    public $width;
    public $height;

    public function area()
    {
        return $this->width * $this->height;
    }

    public function perim()
    {
        return (2 * $this->width) + (2 * $this->height);
    }
}

class circle implements geometry
{
    public $radius;

    public function area()
    {
        return pi() * pow($this->radius,2);
    }

    public function perim()
    {
        return 2 * pi() * $this->radius;
    }
}

function measure($geometry) {
    print_r($geometry);
    print_r($geometry->area());
    print_r($geometry->perim());
}

$r = new rect();
$r->width = 3;
$r->height = 4;

$c = new circle();
$c->radius = 5;

measure($r);
measure($c);

Concurrency

Concurrency refers not only to CPU parallelism, but also to asynchrony: letting slow operations like a database or network-read run while the program does other work.

Even though, “Concurrency is not parallelism”, if this sentence means nothing to you, I suggest to check out Rob Pike’s excellent talk on the subject. It’s a great explanation with funny examples of gophers working in parallel and concurrent, you will enjoy all 30 minutes.

Go has a rich support for concurrency via goroutines and channels. This is one of the highlights of the language.

goroutines

A goroutine is a lightweight thread of execution.

Goroutines can be described as functions which run concurrently from other functions.

They’re invoked following the go keyword. As the function is invoked it runs concurrently and the rest of the code is executed without waiting for the completion of that function.

In comparison with other languages, we can consider goroutines as “green threads“. What does it mean? Go use multiplexing strategies to group goroutines and run them in a less number of OS threads. The advantages, among others, is that you can run concurrent applications in a single core system, threads are managed by virtual machine or binary library using User space instead of Kernel space, they start faster and with a low stack that can grow based on needs, just to mention some.

Here’s a small example of a goroutine:

package main

import "fmt"

func f(from string) {
    for i := 0; i < 3; i++ {
        fmt.Println(from, ":", i)
    }
}

func main() {
    f("direct")
    go f("goroutine")

    go func(msg string) {
        fmt.Println(msg)
    }("going")

    var input string
    fmt.Scanln(&input)
    fmt.Println("done")
}

Channels

Channels are the pipes that connect concurrent goroutines. We can think on channels as process intercommunication. Go uses cooperative multitasking between goroutines. So if one routine never yields, then the other will never run.

You can send values into channels from one goroutine and receive those values into another goroutine.

We can use channels to synchronize execution across goroutines.

Channels must be created before being used, using the chan keyword.

package main

import "fmt"

func main() {
    messages := make(chan string)
    go func() { messages <- "ping" }()
    msg := <-messages
    fmt.Println(msg)
}

Since I couldn’t find a better example without the need of writing a post explaining its concepts, I bring you a simple one in Java using multi-threading:

import java.io.IOException;
import java.net.ServerSocket;
import java.net.Socket;

class Server
{
   public static void main(String[] args) throws IOException
   {
      ServerSocket socket = new ServerSocket(9000);
      while (true)
      {
         final Socket s = socket.accept();
         Runnable r = new Runnable()
                      {
                         @Override
                         public void run()
                         {
                            doWork(s);
                         }
                      };
         new Thread(r).start();
      }
   }
   static void doWork(Socket s)
   {
   }
}

Thanks for reading! I hope you enjoy it.

See you on the next post!

Go basics – Control Structures

Hello readers, in this episode we’re going to talk about languages structures, as a preface to future post where I will show you all this stuff in action, with OOP and concurrency examples and reviewing some toolkits and frameworks.

Of course, this is not an exception, on each topic of this post I will show you an example of how it can be used and a comparison with languages to make it easy to understand for those whom come from PHP, C, Java, etc.

Loops and Bifurcations 

For

Go has only one looping construct, the for loop.
The basic for loop has three components separated by semicolons:

– the init statement: executed before the first iteration
– the condition expression: evaluated before every iteration
– the post statement: executed at the end of every iteration

The init statement will often be a short variable declaration, and the variables declared there are visible only in the scope of the for statement.

The loop will stop iterating once the boolean condition evaluates to false.

Note: Unlike other languages like C, Java, or Javascript there are no parentheses surrounding the three components of the for statement and the braces { } are always required.

Following there’s some examples that shows each variation with its equivalent in PHP:

While loop in GO
var counter int = 0

for counter < 100 {

    counter += 1

}
PHP Version
<?php 
while($counter < 100){ 
     $counter++; 
}
 Foreach in Go
import "fmt"

for key, value := range list {
    fmt.Printf("%d => %s\n",key, value)
}
PHP Version
<?php 
foreach($list as $key=>$value){     
    echo "{$key} => {$value}\n"; 
}
Common For loop in Go looks like C
for i := 0; i < 10; i++ {
	fmt.Println("The value of i : ", i)
}

If-else

The if statement in Go, like For statement, does not need to be surrounded by  ( ), but the braces { } are required.

Like for, the if statement can start with a short statement to execute before the condition.

Variables declared by the statement are only in scope until the end of the if.

As many other languages, it support the else statement.

 Chained if statement in GO
if value, ok := m[key]; ok {
    fmt.Println("value is:", value)
}
PHP Version
if( isset($_POST['id'])) {
    $id = $_POST['id'];
}
If-else in Go
if _string == "my example" { 
    fmt.Println("this is ",$string) 
} else {
    fmt.Println("this is no my string") 
}
If-else in PHP
<?php
if($_string == "my example"){
   echo "this is ".$string;
} else {
   echo "this is no my string";
}

switch

This is a multiple choice statement that allows us to select between more than two options, and most of the time faster than if-else.

The differences against other languages is that each case body breaks automatically, unless it ends with a fallthrough statement,

and Switch without a condition is the same as switch true.

This construct can be a clean way to write long if-then-else chains.

Switch in Go
switch i {
	case 0 : fmt.Println("Zero")
	case 1 : fmt.Println("One")
	case 2 : fmt.Println("Two")
	case 3 : fmt.Println("Three")
	case 4 : fmt.Println("Four")
	case 5 : fmt.Println("Five")
	case 6 : fmt.Println("Six")
	case 7 : fmt.Println("Seven")
	case 8 : fmt.Println("Eight")
	case 9 : fmt.Println("Nine")
	default : fmt.Println("Unknown Number")
}
Switch in PHP
<?php

switch $i {
	case 0 : 
               echo "Zero";
               break;
	case 1 : 
               echo "One";
               break;
	case 2 :
               echo "Two";
               break;
	case 3 : 
               echo "Three";
               break;
	case 4 : 
               echo "Four";
               break;
	case 5 :
               echo "Five";
               break;
	case 6 :
               echo "Six";
               break;
	case 7 : 
               echo "Seven";
               break;
	case 8 : 
               echo "Eight";
               break;
	case 9 : 
               echo "Nine";
               break;
	default : 
               echo "Unknown Number";
}

Functions

Functions are defined using the keyword func followed by the function name, arguments and the return values.

func say_hello() {
    fmt.Println("Hello From the function")
}

Parameter

Functions may have a return value. This value can also be named.

Simple function in Go
func Add(first, second int) (result int){ 
    return first + second 
}
Same example in PHP
<?php
function add($first, $second) {
   return ($first + $second);
}

Multi-types result

This is one of Go goodies that does not has equivalence in other common languages like PHP or C. In Go we can return multiple values of different types, also naming each returned parameter. Let me show an example:

func divide(n,d int) (result float, err error) {
    if d == 0 {
        err = errors.New("")
    } else {
        result = n / d
    }
    return result, err
}

Variadic

Functions can take 0 to undefined variables of a particular data type.

func sum(args ...int) (total int) {
	total := 0
	for _, i := range args {
		total = total + i
	}
	return total
}

Closure

Go supports anonymous functions, which can form closures. Anonymous functions are useful when you want to define a function inline without having to name it.

func Sequence() func() int {
    i := 0
    return func() int {
        i += 1
        return i
    }
}

nextValue := Sequence()

fmt.Println(nextValue()) // 1
fmt.Println(nextValue()) // 2
fmt.Println(nextValue()) // 3
fmt.Println(nextValue()) // 4

Do not miss the second part of this post where we will use this concepts while discuss OOP and concurrency.

Go basics – Data Types

Today we are going to walk thru basics of Go language. Starting with a list of supported data types and defining custom types.

I’ll try to show you some examples of how to deal with basic Go stuff and compare with PHP as a reference.

Data types

Integer

Integers are numbers without a decimal component. Go lang support four types for integer based on the amount of bits can address, and three  extra types based on machine architecture.

Since computers use a base-2 for representation, 8, 16, 32 and 64 tell us how many bits each of the types use. Then for the first sub set of integers Go also split them on signed and unsigned.

Signed Integers: int8, int16, int32, int64.

Unsigned Integers: uint8, uint16, uint32, uint64.

Also, a byte is an alias for uint8 and a rune for int32.

For the second sub set, the machine dependent integers we have: uint, int and uintptr.

Floating Point Numbers

Generally known as Real Numbers, represents those numbers with decimal component.

Go has two floating point types : float32 and float64.

It also has two complex number types : complex64 and complex128.

String

This data type is represented by a sequence of characters with a definite length.

Literals in Go can be created in 2 ways, with double quotes, that allows the use of special characters like \n and \t, but cannot contain new lines, or with backticks quotes, that permits the use of new lines.

You can concatenate two or more strings, like lots of languages except PHP that use a dot (.), with plus sign (+), and each individual character can be obtained using indexes.

var example string = "weird\t string\n sample!”

otherway := `weird

sample!`

In comparison with PHP, here are a couple of examples of string operations:

 PHP
$part_1 = "weird"; 
$part_2 = "string"; 
$part_3 = "sample!";
Length in PHP
$stringLength = strlen($part_1); // 5
Length in Go!
var string_length int = len(example) 
Concatenations in PHP
$full_str = "{$part_1} {$part_2}";
$full_str .= $part_3
Concatenations in Go!
var full_str string
full_str = part_1 + " " + part_2

Boolean

Booleans are a special 1 bit integer type used to indicate True or False.

The logical operators which can be used on booleans are:

and &&

or ||

not !

Arrays, Slices, Maps

Array is a set of elements of an specific type. [n]T is an array of n elements of type T, where n is the length of the set and T represents the type, i.e. to create an array of ten element length of string, it should looks like [10]string.

Examples:

  var a [10]int

  x := [5]float64 {
       34,
       63,
       56,
       84,
       23
  }

The above example in PHP looks like:

$x = array(34, 63, 56, 84, 23);

or just

$x = [34, 63, 56, 84, 23];

Slice is a segment, not fixed of an Array.

Creation of slice is via make command.

x := make([]int, 5)

It also can be initialized from array by indexes.

 

x := a[3:] //the first 3 elements of a

x := a[2:5] // specific range, elements from 2 to 5

A map is an unordered collection of key-value pairs. Also known as an associative array, a hash table or a dictionary, maps are used to look up a value by its associated key.

var x map[string]int

x["Hello"] = 1

Custom Data Types

Struct:

A structure is a user defined data type which contains named fields. In Go structs are used to represents object by the association of method to pointer of this type.

type dog struct {
	breed string
	age int
	owner string
}

type cow struct {
	age int
	farm string
}

The dot operator is used to access each field by name. The above example in PHP will look like:

<?php
class Dog {
    private $breed;
    private $age;
    private $owner;
}

class Cow {
    private $age;
    private $owner;
}
Interfaces:

In Go an interface is two things: it is a set of methods, but it is also a type.
The interface{} type, the empty interface, is the source of much confusion. The interface{} type is the interface that has no methods. Since there is no implements keyword, all types implement at least zero methods, and satisfying an interface is done automatically, all types satisfy the empty interface. That means that if you write a function that takes an interface{} value as a parameter, you can supply that function with any value.

We’ll talk about Loops, Control Structures and some design patterns in future posts. Thanks for reading

Let’s Go!

The Go programming language, also known as golang, is an open source project created by Robert Griesemer, Rob Pike, and Ken Thompson in 2007 and sponsored by Google as an intended to resolve common criticisms of other languages while maintaining their positive characteristics.

It’s heavily based on C, but designed to be more concise and secure. Go has become increasingly popular for seasoned developers and new programmers alike,

used in many open source and commercial software applications.

Some notable companies using Go within their applications include Google, Dropbox, CloudOS, MongoDB, Docker and Uber.

 

Go Language Basics

Go is a statically typed, compiled, garbage-collected, concurrent general purpose programming language. Go is considered as an object oriented programming language and it uses object composition instead of class inheritance.

Go was based on several languages besides C: Pascal, Modula, Oberon, Newsqueak, and Limbo.

It is a traditionally compiled, object oriented, functional language that features static typing, garbage collection, concurrency, memory safety, and high readability.

Some of the major advantages of Go include:

  • Concise, simple syntax.
  • Extremely fast compile times.
  • The ability to divide routine threads into sub threads, allowing for a high degree of concurrency.
  • Built-in support for strings and maps.
  • Go includes a huge standard library, including its own built-in web server.
  • The language supports most major operating systems and computer hardware.

 

Objects In Go

Since a standard definition does not exist, let’s use this one, “An object is an abstract data type that has state (data) and behaviour (code)”.

Go doesn’t have something like  `object`, even though it does have a type that matches the same definition of a data structure that integrates both code and behaviour.

In Go this is called a ‘struct’.

With struct we define a new data type containing the name of fields (attributes) that will keep the “state” of the object. To implement the behaviour of this object in Go,

we use functions bound to a pointer of this struct. Here’s an example to illustrate it:

image

 

Relationships between Objects In Go

Instead of inheritance Go strictly follows the composition over inheritance principle. Go accomplishes this through both subtyping (is-a) and object composition (has-a) relationships between structs and interfaces.

The mechanism Go uses to implement the principle of object composition is called embedded types. This way we have a field that is a subtype of other object, but this filed remains in a different entity.

Because of that Go provides two alternatives, “Pseudo sub typing” and “True sub typing”.

We accomplish this pseudo is-a relationship in go using what is called an Anonymous field.

Over the next posts I will bring you a more detailed explanation about this concepts while introduce you data types and language characteristics with some examples on each topic.