Tip #1: docker build

a) Is there a different between CMD and ENTRYPOINT ?

One confusing aspect that I frequently encountered while writing a Dockerfile was the similarity between the CMD and ENTRYPOINT instructions. The documentation has greatly improved regarding this difference, but it can still be confusing for new comers to the Docker environment.

The short version:

- ENTRYPOINT is meant to configure a command that will always be executed when running a docker run myimage command. This instruction can only be overwritten by using the --entrypoint CLI parameter for thedocker run command

- CMD is meant to configure a set of default parameters for the command set up with the ENTRYPOINTinstruction. These parameters can be overridden by the extra parameters given to the docker run command immediately after the image name.

The confusion is created by the fact that both instructions can be used mostly in the same way: to configure an execution command for the image.

For example:

• run the following command with code below:

docker build -t myimage -f Dockerfile .

• running a docker run --rm myimage will output Welcome to Docker World
• running a docker run --rm myimage my world will output: Welcome to my world

As you may have spotted the command remained the same, echo, while the parameters used were those given at the command-line.

Now update the Dockerfile with the changes below and rerun the build command:

• running docker run --rm myimage will have the same output as in the previous run
• running docker run --rm myimage my world will output the following error now:

“docker: Error response from daemon: OCI runtime create failed: container_linux.go:348: starting container process caused “exec: \”my\”: executable file not found in $PATH”: unknown.”

This is because the parameters we added to the run command have overridden the CMD instruction in the Dockerfile. In this case Docker tried to execute an app called my with the parameter world.

There is another small trick that is important to know when using these instructions and relying on environment variables.

Both instructions have 2 forms:

• ENTRYPOINT/CMD [command, param1, param2] which will execute the command directly as PID 1 inside the container
• ENTRYPOINT/CMD command param1 param2 which will execute the command listed as a sub-process of the shell being used by the container

This is an important distinction because running as a sub-process of the shell it will give us access to the environmental variables that the shell is usually maintaining.

There is also a third form for CMD, because as we mentioned previously this instruction should mainly be used as a default list of parameters:

• CMD [param1, param2]

b) Deferring instruction execution with ONBUILD

ONBUILD comes very useful when we need to create base images that could be used for multiple projects by allowing us to defer the execution of the configured instruction to the downstream images.

It works by configuring trigger instructions to be run when building a later image. These instructions will be run as if they were added immediately after the FROM instruction in the current Dockerfile.

As an exercise, consider the following scenario: a DevOps or security team creates a base Docker image that copies the project’s source code to the image and then runs your preferred package manager to automatically install the project’s dependencies — this is a basic use case but this instruction opens up a whole lot more possibilities.

Then, this image could be used for many other projects using the same package manager without requiring changes for each project. All the project’s customization could be done in the project’s ownDockerfile.This will make it easier to maintain base project images that could be used even across environments — dev, staging, prod.

For example, below is a base image for installing a PHP project’s dependencies using Composer.

Add the code above in a file called Dockerfile.base. Then build the composer-baseimage by running this command:

docker build -f Dockerfile.base -t composer-base .

PS: For those of you unfamiliar with Composer, just add the code in the next block to a file called composer.json stored in the same folder as the Dockerfile

In another file, called Dockerfile.project, add the following instructions:

Build the image by running this command:

docker build -f Dockerfile.project -t my-project .

Now, when running the build command — docker run --rm my-project — Docker will create a new container and automatically start running the Composer application which will immediately start installing the project’s dependencies.

Using the above files it should display the following output:

c) The ARG instruction

One way to make Dockerfile files easier to maintain and reuse is to use arguments. Docker allows for arguments to be added to the build process by using the ARG instruction, which creates a variable inside the build scope containing the value of the argument passed through the --build-arg parameter.

To make it easier to understand how ARG works think of the instructions before a FROM definition as being part of the global scope, while instructions after a FROMdefinition as being part of the build scope.

For this exercise, let us use the following Dockerfile:

Looking at the instruction on line 1, what Docker does is to define a global scope key called BASE_TAG which will be used to configure the version tag used for the base image.

The ARG instruction can accept a default fallback value that will be used in case the command line parameter is missing. This is defined as a value for the key used by the ARG instruction.

An important thing to remember is that global scope argument will not propagate automatically inside a build scope. There is, however, a small workaround to this rule.

If we look at line 4 in our Dockerfile we notice that we run an echo command that will not output the BASE_TAG value but a simple blank line. To propagate the argument value inside the build scope we need to redeclare the argument with the same name after the FROMline. If we don’t specify a default value, the default value from the global scope definition will be automatically set.

d) Multi-stage build

Multi-stage builds has been a recent addition, but it is an extremely useful feature allowing for easier management of build scripts and smaller Docker images.

The first benefit is the fact that there is no longer a need to maintain separate Dockerfile files for each environment. We can prepare the Dockerfile for the production image and then add a new stage where we start from the production image and just add the development tools needed. This is useful because there is no longer the need to build and store the PRODUCTION image separately.

The smaller images are a consequence of the fact that we can separate the building tools from the application image. As such, we can start from a base image which contains our application’s build tools, run the build tools to build the application, then in a next stage we can start from a production ready image and copy only the newly built application.

Stages, by default, are numbered starting with the first encountered stage as zero, but they can also be statically named using the FROM [image:version] AS stage_tagformat.

Since examples can offer more context, let’s consider the following Dockerfile:

In order to build the production image we run the following command:

docker build -f Dockerfile -t prod_image --target=PROD .

Docker runs the build process starting at the FROM php:7.2-cli as PROD definition up to next one. Since we said that the target is PROD, Docker will stop there and save the layers as a new Docker image.

To create the development image we run, you guess it, the same command but having --target=DEV. In this case, Docker will build the PROD image then proceed in building the DEV image by using the layers from the PROD build.

There is a catch, unfortunately. If we wanted to build the STAGING image Docker will build the PROD stage first, then build the DEV stage second and then start building the STAGING stage using the PROD as a base image. The DEV stage layer will be discarded since it is not referenced as being used.

The first downside is in time taken for the DEV stage to build and the requirements it will have.

Secondly, if at any point the DEV stage will fail to build the whole process will fail to build.

This does not seem to be the case with BuildKit, but that is a topic on its own.

In this cases discussed until now, we used all the layers from the parent build, but the multi-stage build process also allows us to copy only specific files/folders from the previous build.

This can be achieved by using the --from=[stage_name/stage_id] parameters for the COPY instruction.

e) --tag "name:tag"

The tag parameter is a bit confusing in the context of the docker build command because in almost all the documentation it usually refers to the portion of the name of an image after the semicolon (:), also known as a version tag. The confusing part is the fact that if you use the Docker Hub to store the image the name part needs to be only the user name and the tag refers to the image version. But if you store the image in a private repository the name is required to contain the complete domain name of the registry, including the port number, and the path that this image is stored under.

For example: an image stored at: registry.example.com:5000/my_project would have the tag as: registry.example.com:5000/my_project/my_image:latest or for a more specific version registry.example.com:5000/my_project/my_image:1.0.0

Conclusions

I think that wraps it up for this first part. If you find it useful or have any feedback or suggestions please feel free to add them in comments section below.

Docker Tips&Tricks was originally published in webthoughts.koderhut.eu on Medium, where people are continuing the conversation by highlighting and responding to this story.

Structuring the tests

There are two documented ways of structuring your InSpec tests: Chef cookbook way, where the tests are embedded into the Chef cookbook and InSpec’s compliance profile way. I like to follow the second way because of two main reasons: I mostly write Ansible and SaltStack roles/states and because I like to reuse my tests to check the infrastructure state both before and after running any automation.
I’ll use as an example a profile I wrote for testing an Ansible role that installs and configures Samba.

The folder structure looks like this:

Creating your first profile

Getting started with a profile is quite easy with InSpec. Using the init profile command, InSpec will create a minimal profile along with a basic example.

For example, running:

$ inspec init profile samba

InSpec created a folder named samba in the current directory and in that folder it created a basic structure which we can update if you want to follow along with this article.

Anatomy of an InSpec.io Profile

An InSpec profile is a collection of assertions grouped as compliance controls in a standalone structure with its own distribution and execution flow.

Tests are written in InSpec DSL, an extension of Ruby DSL, optimized for writing audit controls, security and policy requirements.

The only two requirements of a profile are to have a controls folder where the tests will live and a file called inspec.yml in the profile’s root where we will store the metadata about the profile.

inspec.yml

The inspec.yml file is a straightforward YAML file where the only requirement is to have a key called name. This key will be used as the profile identifier by InSpec when generating the reports. There are a few more useful tags, so make sure to check out the docs. Link is down below.

Writing infrastructure tests

The tests will be located in the controls/folder. There you can either put everything in a single .rbfile or separate them in different files based on functionality.

Each .rb file will usually contain one or more control blocks.

Having controls in separate files offers the most flexibility when I need to run only specific tests.

For example, if I just want to check if the Samba server is installed I will only run the control file called controls/samba.rb

As you can see from the code above, in this file we have one control structure with three tests: one that checks that the samba package should be installed and two others that verify that the smbd, samba daemon, is enabled and running.

The package and service are InSpec DSL resources. At the moment of writing, InSpec has 80+ such resources covering the vast majority of audit needs. We also have the possibility of adding custom resources that live in the libraries/folder and which will be shipped along with the profile.

Dissecting an InSpec control block

A control block means a ‘regulatory control, recommendation, or requirement’, grouping together related assertions about the state of the system along with the documentation explaining them.

It only requires an identifier. And the recommendation is to keep it simple because it will be used to map the test results to the control identified in the report.

Inside a control block there are a few tags of special interest:

• impact: describing the impact the control has over the system. This can be used by reporting tools or by Chef’s own compliance tool.
• desc: a more detailed view of the purpose of the control
• tag: one or more tags that can be added to more easily group controls in reports
• ref: these keys can be used to provide additional information about the control. It can serve to add a link to a documentation page describing in more detail the assertions made by the control block
• describe: one or more describe blocks using a resource and grouping one or more tests
• a test is an individual assertion about the state of the resource or one of its properties. All tests begin with the keyword it or itsand are grouped within a describe block.

With the exception of the describe blocks everything in the control block is optional. Even the control block itself is optional. But then if we don’t use a control block we loose other useful functionality.

Deploying and using InSpec tests

InSpec has three modes of operation: locally, remotely through ssh and winrm for Windows environments. It can also be used to test the environment inside a Docker container using the docker backend.

To run the tests you need to use the execcommand as in the example below:

$ inspec exec -b local samba

Conclusion

InSpec is a nice small utility application that can be used in variety of scenarios ranging from compliance tests to using TDD in dealing with the infrastructure.

One other use case that quickly comes to mind is using it as part of the support tools for an application. Checking if the environment where the application conforms with the manufacturer’s specs and even if the application itself has all the components that it needs.

I will try to cover most of these cases in later articles, so stay tuned for more.

Testing your infrastructure with InSpec.io was originally published in webthoughts.koderhut.eu on Medium, where people are continuing the conversation by highlighting and responding to this story.

Since I first started working with Docker, around 2 years ago, I found it very useful because of its speed booting up a complete development environment. It also only takes a few seconds to switch between projects which convinced me to use it as a default environment for working.

Nevertheless, one thing that I found bothering me was that I had to shutdown a container mapping a host specific port when I needed another container using that same port. The most common example is a web-server container. I always needed to stop the Nginx container for one project whenever I switched to a different project. I know that with Docker’ speed this only requires a couple of commands. But it’s still a couple of clicks that get annoying fast when I need to do this a few times during the course of a day.

So I started looking around for a solution. And this is what I came up with.

Initial Environment Configuration

I started looking at Nginx to be used as a proxy, but it requires a lot of configuration to get started with a new project. Next on the list was HAProxy. Its configuration is quite clean and easy to understand. It also, only requires a couple of lines to route a new project.

Below you can find the steps to get you started with this setup.

First we need to create the HAProxy container. We do so by running:

$ docker run -d -v /etc/haproxy:/usr/local/etc/haproxy:ro -p 80:80 \    
        -p 443:443 --name web-gateway haproxy

This command will pull the latest HAProxy image and create a container from it. With this command Docker will also map a host folder, where we will keep the HAProxy configuration, and the HTTP(S) ports to the container. Bind mount-ing the configuration from the host will allow us to edit the configuration from the host and the container will just reload it.

Now that we configured the entry point to our server it is time to configure the web applications that we want to serve.

Note: for this article I will use two simple Nginx basic setups, but the exact same steps can be applied to any Docker-ized network application.

Next we will create three containers: one serving as a default server and two simulating serving two different apps.

$ docker run -d -v /var/www/default:/usr/share/nginx/html:ro \
    --name default-backend nginx

$ docker run -d -v /var/www/web1:/usr/share/nginx/html:ro \
    --name default-backend nginx

$ docker run -d -v /var/www/web2:/usr/share/nginx/html:ro \
    --name default-backend nginx

Probably the first question you might have right now is how will the three new containers communicate with the HAProxy container since we didn’t map any host port? The answer is very simple: we will use Docker’s container networking.

Depending on how you would like to connect the apps you may choose to create separate networks for each container or reuse a network for several containers. In the later case, the apps will be aware of each other and accessible through the container’ name or IP.

For the purpose of this article I will create a separate network for each container so that we will keep the encapsulation features provided by Docker.

Let’s create the default server network:

$ docker network create —-attachable -d bridge default-webapp

We are using the ‘bridge’ driver because we will be using only the current machine. If you have a multiple machine setup you can use the ‘overlay’ driver. For more info, check-out the Docker documentation page.
The ‘attachable’ option will allow us to manually attach the network to our containers, which we will need to do later.
Finally, we provide a name for the network through the last parameter of the command.

Using the same command go ahead and create the networks for the other 2 containers using the ‘web1’ and ‘web2’ names.

Now that we configured the application containers, the HAProxy container as well as the networks let’s glue them together.

Run the following commands to connect the HAProxy container to the default Nginx server:

$ docker network connect default-webapp web-gateway 
$ docker network connect default-webapp default-backend

Now the two containers are accessible from each container using the container name. This gives us a flexible environment to work with because we no longer need to keep track of IPs and we can swap containers without changing any configuration. If, for example, you want to test your app with Apache or httpd just remove the Nginx container and create the new one using the same container name. Attach it to the network and you are done. The HAProxy will not need any other configuration change to proxy the connection to your new container.

Do the same for the other two containers by using the above two commands, but be careful to use the proper network and container names :)

Now that we connected the containers together it is time to configure HAProxy.

On the host create a file called `haproxy.cfg` under `/etc/haproxy` and paste the following configuration:

The sections that we will be focusing are the ‘frontend’ and ‘backend’.
The ‘frontend’ section declares a mapping of IP and port where HAProxy will listen to for connections. In our config we are configuring HAProxy to listen on all our IPv4 addresses using port 80 and 443.

The ‘default-backend’ option configures a default backend server where a request will be sent in case there are no other ACL’s matching.

The ACL’s (Access Control List) are HAProxy’s way for identifying where a request should be routed to in order to get a response. We will need to create a new ACL entry for each new application/domain we want to serve.

The ‘backend’ sections configure the servers that should answer to a request. Here, we can add as many containers we would like to respond to a request to our application.

As we can see, because we are using named Docker containers we can simply use the container name to route our request from the HAProxy to the application container.

Now restart the HAProxy container by running:

$ docker restart web-gateway

That’s it! Now, whenever we start a new project, we simply add a new network, connect HAProxy to it and add a new ACL line and backend server configuration.

Final thoughts

Using named Docker containers and container networking we can use a more descriptive and reusable HAProxy configuration. By using FQDN for containers we can have the same HAProxy configuration moved to a network where we use bare-bone servers and/or VMs instead of Docker containers. We can also use such servers along side containers allowing us to have quite a flexible environment.

Although this article focuses on a development environment this setup can be used in a production setup as well, as long as all the necessary security measures are addressed.

Serving multiple web apps using HAProxy and Docker containers was originally published in webthoughts.koderhut.eu on Medium, where people are continuing the conversation by highlighting and responding to this story.

One of the features I like when working with multiple inheriting services in a Symfony project is that it allows a developer to define parent and derived services. That means that two services can share the service configuration definition inside the Symfony DependencyInjection Container (aka DIC).

Instead of copying the same configuration lines for each related service, a developer can define a parent service and then just inherit the configuration in the services extending the parent. A benefit of this technique is that it makes cleaner and easier to manage service definitions.

The Problem

In a recent project I was working on I found myself in need to override the arguments of an abstract parent service definition. Although the Symfony documentation is informative and up-to-date with all the framework’s features, the only proposed solution I was able to find for this scenario was by modifying the service configuration using PHP code. Of course, there was the possibility of writing a CompilerPass and changing the arguments but that meant writing a lot of unnecessary code for my case.

So, I started wondering if the same can be achieved by only using YAML or XML definitions. Looks like it’s possible.

Going under the hood

One thing that really stuck with me along the years is that whenever I need a good, clean solution for a programming problem I need to get my hands “dirty” and get deeper into the code.

After a bit of debugging through the DIC component’s internals I found that the DefinitionDecorator::replaceArgument() method is called from the ResolveDefinitionTemplatesPass::resolveDefinition() method if the arguments in the inheriting service definition have a key starting with index_.

#Symfony/Component/DependencyInjection/Compiler/ResolveDefinitionTemplatesPass.php

private function resolveDefinition(ContainerBuilder $container, DefinitionDecorator $definition)
{
...
// merge arguments
foreach ($definition->getArguments() as $k => $v) {
    if (is_numeric($k)) {
        $def->addArgument($v);
        continue;
    }

    if (0 !== strpos($k, 'index_')) {
        throw new RuntimeException(sprintf('Invalid argument key "%s" found.', $k));
    }

    $index = (int) substr($k, strlen('index_'));
    $def->replaceArgument($index, $v);
}
…
}

#Symfony/Component/DependencyInjection/DefinitionDecorator.php

public function replaceArgument($index, $value)
{
    if (!is_int($index)) {
        throw new InvalidArgumentException('$index must be an integer.');
    }

    $this->arguments['index_'.$index] = $value;

    return $this;
}

In simple terms, whenever we need to override the argument of a parent service simply add a key starting with ‘index_’ and the index number of the argument. Keep in mind that both Yaml and XML are “translated” to PHP code meaning that the arguments index will start at 0 (zero).

The downside of this solution is that it is limited to __constructor() dependency injection. If you need to replace a setter or property injected dependency you will have to use their documented solutions.

Quick example

Below you can find an example configuration for both Yaml as well as XML for overriding the abstract service ‘mail_manager’ second argument’s definition:

# services.yml

services:
    my_alternative_mailer:
        # ...

    mail_manager:
        abstract: true
        arguments:
            - '@my_email_formatter'
            - '@my_mailer'

    #injecting the alternate mailer
    newsletter_manager:
        class:  NewsletterManager
        parent: mail_manager
        arguments:
            index_1: '@my_alternative_mailer'

    #using the mailer defined in the parent definition
    greeting_card_manager:
        class:  GreetingCardManager
        parent: mail_manager

#services.xml
...
<services>
    <service id="my_alternative_mailer" class="...">
       …
    </service>

    <service id="mail_manager" abstract=”true”>
        <argument type="service” id=”@my_email_formatter” />
        <argument type="service” id=”@my_mailer'” />
    </service>

    <service id="newsletter_manager" class="NewsletterManager" parent="mail_manager">
        <argument type="service" id=”@my_alternative_mailer'” index="1" />
    </service>
</services>

Conclusion

If you need to quickly override a parent service arguments definition then this solution might help you accomplish that task faster. Using this technique we remove the need for creating compiler passes and it provides a cleaner and easier solution to managing different dependencies in similar or inheriting services.

Disclaimer: The Symfony logo is a trademark of Fabien Potencier.

Overriding parent dependencies in Symfony 3 was originally published in webthoughts.koderhut.eu on Medium, where people are continuing the conversation by highlighting and responding to this story.

Deployer is a modular, lightweight deployment automation tool. A few of its top features are modularity, atomic deploys and parallel deployments.

In this article we will create a recipe to automate the deployment of an OctoberCMS app on multiple servers.

Prerequisites

First, we need to install Deployer on the deployment machine. We have three ways to accomplish this.1

• The simpler way is by downloading the PHAR2 archive from the main website. For this run the following command in the terminal:

$ cd ~/ 
$ mkdir deployer 
$ cd deployer/ 
$ wget http://deployer.org/deployer.phar -O deployer 
$ chmod +x deployer 
$ mv deployer /usr/local/bin/deployer

• We can now run the Deployer app from anywhere on our deployment system.
• If you want to integrate Deployer into your project you can use Composer.
  For this article we will create a separate project so that we do not mix Deployer with our code.
  In our terminal let’s write the following:

$ cd ~/ $ mkdir deployer 
$ cd deployer/ 
$ composer require deployer/deployer:~3.0

• After Composer finishes we can start Deployer by running:

$ php vendor/bin/dep

• For geeks, myself included, you can download the source from the Github repository and then build Deployer from it.

$ cd ~/ 
$ mkdir deployer 
$ cd deployer/ 
$ git clone https://github.com/deployphp/deployer.git 
$ php ./build

Deployment recipes

Recipes are PHP script files containing the tasks Deployer needs to perform to deploy the application. By default, Deployer provides a common.phprecipe where, as name suggests, are stored a few frequently used tasks.
Note: The common.php file is not downloaded with the PHAR archive so we will need to add it to our deployment project before continuing. You can find a copy on the Github repo from the links below.

Beside the common tasks recipe the Deployer devs have also added, in their Github repo, recipes for some of the most popular frameworks, like Symfony and Laravel to mention a few. There you can also find boilerplate recipes for platforms like Magento, Drupal or WordPress. Before starting your own recipe from scratch first check-out if there isn't a boilerplate already built by using the links at the bottom of this article.3

To start writing our recipe we first need to create a deploy.php file in the root folder of our deployment project. In this file we will define a few tasks to run in order to deploy our OctoberCMS app.
After you created the deploy.php file in your preferred editor, add the 'common' recipe by adding the next line in the deploy.php file:

require_once 'recipes/common.php';

Now, let’s configure a few default things. Add the next few lines to the deploy.php file:

set('repository', 'git@github.com:koderhut/YOUR-REPO-URL.git');

set('keep_releases', 2);

set('shared_dirs', [
    'storage/framework/cache',
    'storage/framework/sessions',
    'storage/framework/views',
    'storage/cms/cache',
    'storage/logs',
    'storage/temp',
    'vendor',
]);

set('shared_files', ['.env']);

env('code_path', '/var/www/YOUR_OCTOBERCMS_CODE_PATH_HERE');

env('branch', 'master-prod');

The lines above configure Deployer to only keep 2 other versions of our application’s code for us to revert back to in case our current deployment goes wrong. Then, we instruct Deployer to retrieve the code via Git from our repository. This article assumes your repo is publicly available, but if that is not the case I will describe the additional configurations you need in order to use private repos in a later article.

The shared_dirs and shared_files lines above instruct Deployer to create symlinks to these folders and files in our deployed project folder. This is very useful when you have configuration files which you don't want to add in a repository or folders containing media files, user uploads or content that is not otherwise required by the application to run.

In our scenario we need to create symlinks to folders like the logs/ folder, the folder containing the sessions and cache and even our third-party vendors code. These folders are not needed or even recommended to be stored inside our application's repository. By creating symlinks to these folders we won't have multiple copies of them occupying unnecessary space or loose session or caching data between the time we copied the files and when our deployment finished.

Also, the .env file contains environment specific configuration data, such as database login info, which should not be stored within the app repo.
The last two configuration lines are setting up a few default values for Deployer. These lines instruct Deployer which Git branch to download from the repository and the path where to deploy the code on the server. The configs are optional at this point and you can also specify them in the server configuration. Specifying them in the server configuration section is useful if you want to use the same deployment script for both testing and production environments.

Tagging the deployment

*Quick reference: In a Deployer script a task is a PHP closure function that contains the PHP code necessary to deploy our app. The task is created using the task PHP function which is part of the Deployer code.
Before deploying the code let's first create a Git tag. For this we will create a new task called deploy:tag-deployment in our deploy.php file:

task('deploy:tag-deployment', function() {
    $codePath = env('code_path');
    $time     = date('d/m/YTH-i-s');

    cd($codePath);

    runLocally("git tag -a -m 'Deployment of version {$time}' '{$time}'  && git push origin --tags");
});

We’ve now created a new Git tag and pushed it to the main repo. Let’s go ahead and create the deploy task.

task('deploy', [
//    'deploy:tag-deployment', //ONLY USE THIS TASK IF NOT DEPLOYING USING THE PARALLEL FEATURE
    'deploy:prepare',
    'deploy:release',
    'deploy:update_code',
    'deploy:shared',
    'deploy:vendors',
    'deploy:writable',
    'deploy:symlink',
    'deploy:symlink:web',
    'deploy:cp-htaccess',
    'cleanup',
])->desc('Deploy your project');

after('deploy', 'success');

You may have noticed that we are using the same task function but we are passing an array as the second argument instead of the closure as we've previously done. That is no mistake. The task function supports either a closure or an array of task names. Using an array we're instructing Deployer to call the tasks in the order we set. It is a shorthand for a closure in which we call the tasks ourselves in a specific order. The Deployer docs calls it 'task grouping', I like to call it the 'deployment storyline.'

We finish the script with an after function call to simply print a message that the deployment completed successfully. As with the task function, after is a function defined by Deployer which is executing a closure after the specified task has been executed successfully.4

Server configuration

We are almost done. We just need to add the server configuration and we will be ready to start deploying the code.
Since the server configuration may contain sensitive information we will separate the server configuration data from the script. Go ahead and create a new file called server_config.php and add the following lines:

server('octo-deploy-prod', '192.168.56.123', '22')
    ->user('vagrant')
    ->identityFile('ssh1/id_rsa.pub', 'ssh1/id_rsa', 'OPTIONAL_SSH_ENCRYPTION_KEY')
    ->env('deploy_path', '/var/www/octo.dep')
    ->env('branch', 'master')
    ->stage('test-october-deploy');

server('octo-deploy-test', '192.168.56.124', '22')
    ->user('vagrant')
    ->identityFile('ssh2/id_rsa.pub', 'ssh2/id_rsa', 'OPTIONAL_SSH_ENCRYPTION_KEY')
    ->env('deploy_path', '/var/deploy_test/www/octo.dep')
    ->env('branch', 'master')
    ->stage('test-october-deploy');

*Note: make sure you change the paths to the SSH key file and the deployment path according to your requirements. This setup is only for the purpose of this article and should not be considered full-prof.

The previous lines define two deployment servers. As I mentioned before, you can configure the deployment path and even the Git branch to be deployed during the server config for a more granular and server-specific configuration. We’ve also named these configurations octo-deploy-prodand octo-deploy-test in order to be able to select the server where we deploy the code during run-time solely based on a parameter. To make it easier for us to deploy the code on multiple servers we also configured a stage5 name.

In this manner we grouped all the servers and when we start the deployment, Deployer is smart enough to execute the same script on all the servers in the selected stage.

You can add as many servers you need to this setup. Separating them into testing and production stages you can use the same deploy script to deploy on each environment based on a single parameter passed at run-time.

Let's include the servers config into our script by adding the next line of code into the deploy.php file, right under the first require_once:

require_once 'server_config.php';

That’s the entire deployment script. You can now run it using the following command from the deployment project’s root folder:

$ php vendor/bin/dep deploy test-october-deploy

Final thoughts

Is simple, isn’t it? You are now ready to start deploying your OctoberCMS apps automatically. In a later article I will provide a few more tips and recipes on deployment using Deployer scripts. Until then, please leave your comments and feedback using the comments section below or review the full files associated with this article on my Github repo.

Github repository

References:

1 — Deployer Installation docs
2 — PHAR archives
3 — Boilerplate recipes
4 — Deployer docs — Tasks
5 — Deployer docs — Servers

Automatic deployment with Deployer was originally published in webthoughts.koderhut.eu on Medium, where people are continuing the conversation by highlighting and responding to this story.

Fast: Twig compiles templates down to plain optimized PHP code. The overhead compared to regular PHP code was reduced to the very minimum.

Secure: Twig has a sandbox mode to evaluate untrusted template code. This allows Twig to be used as a template language for applications where users may modify the template design.

Flexible: Twig is powered by a flexible lexer and parser. This allows the developer to define its own custom tags and filters, and create its own DSL

Quote from the Twig documentation

In this article I will be talking about a problem I faced during the development of a plug-in for OctoberCMS: accessing object data inside a Twig template using custom accessors.

Short description of the context

The plug-in I am referring to is called TemplateTokens and it allows an OctoberCMS end-user or theme developer to add custom variables, also called tokens inside the plug-in. These tokens will be available inside the Twig templates during rendering and, at least for the moment, only output the set value.

The problem I was facing was the fact that I wanted to maintain the simple method of accessing a variable that Twig provided and at the same time be able to provide the end-user a flexible way of configure, update or delete a token.

Twig provides two ways of accessing object properties in its templates: either using the dot(.) notation or thorough the attribute() function. Both of these methods follow the same code path:

- check if foo is an array and bar a valid element;

- if not, and if foo is an object, check that bar is a valid property;

- if not, and if foo is an object, check that bar is a valid method (even if bar is the constructor — use __construct() instead);

- if not, and if foo is an object, check that getBar is a valid method;

- if not, and if foo is an object, check that isBar is a valid method;

- if not, return a null value.

Quote from the Twig documentation

As you may notice through its object access logic, Twig offers out of the box a quick way to access dynamic properties using custom accessors.

In my case I am retrieving a collection of objects from the database. I then expose that collection of objects, through a wrapper to the Twig templates. This allowed me to maintain the Twig’s dot notation method of accessing variables and at the same time control the data to be accessed.

The idea covered all my requirements. It kept the templates simple by providing the end-user, or theme developer, the Twig’s dot notation way to access the data. At the same time the wrapper offers a simple interface to access the stored data. Dispatching the retrieving of the tokens from a data source to the collection object.

Now, let’s see how we can access the data.

One Problem, 3 solutions

After a bit of debugging and code browsing I was able to find three possible ways of attacking this problem.

1. Implement a single method into the wrapper that will be called using the attribute() function I mentioned above
This solution means that you will have a single method in your object that you would call from the template and pass it the name of the token. Although, this conforms with the Twig’s standards it will quickly become tiresome for the end-user.
Think what it will take to write 20 times the following line:

{{ attribute(foo, 'getData', 'token_name') }}

It’s not that fun, right? It is also prone to user errors.
Luckily the next two solutions will make it a bit easier for the end-user.

2. Implement the magic methods __get() and __isset() into the wrapper
This is a simple approach and is also one of the proposed methods described in the Twig docs.
This solution is possible because of the second check from the list we viewed above — if foo is an object, check that bar is a valid property.
It accomplishes this by calling the PHP magic method __isset() and providing it with the name of the property to check. This in turn creates a new problem: the object needs to know which properties exist. For dynamic properties you will need to implement custom logic to check if the parameter passed is a valid property of the object.
In my case that was handled by the collection while the wrapper, which was accessed by Twig directly, did not have a clue if a token with that name existed. Luckily, the Eloquent collection object had a few methods that helped with this. Good guy, Eloquent. :)
To continue, if the __isset() method returns TRUE then Twig continues and tries accessing the variable as:

$object->varName;

Below is a quick example of a class definition allowing for this type of access:

class A 
{
    public function __isset($varName)
    {
        return (bool)isset($this->$varName);
    }

    public function __get($varName)
    {
        return $this->$varName;
    }
}

This means that Twig will call the __get() magic method to retrieve the value.
You can find a quick working example in the repo I prepared for this article or the Twig docs.

3. Implement the magic method __call() into the wrapper
*Warning: This solution is not documented and it might break the Twig standards.
This is one of the most flexible solution I could think of, simply because:

• it requires implementing only 1 method, the __call() magic method
• it allows the end-user to access both object properties as well as object methods using the same exact simple notation that Twig offers
• it makes just one call to your object, instead of two as per the above solution
• it allows for customized access rules — permitting access to otherwise unavailable methods or properties.

But, being flexible does come with a few tradeoffs:

• having only one method to implement means that you will have to check if the parameter received is either a method of the object or a property
• it also means that you will have to implement the logic for accessing the object data as well as the restrictions and validations needed all in one method. I know that we can use some fancy design patterns here, but it is still only one method with more than one responsibility.

public function __call($method, $params)
{
    if (isset($this->$method) || method_exists($this, $method)) {
        //Do something cool here
    }

    return $aValue;
}

Conclusion

Depending on your requirements you can use any of the methods described in this article. I found the call to the __get() method useful with Magento's models which have their own implementation of __get() method to retrieve the data. And the second solution fits perfectly with the current implementation for the plug-in I mentioned.
Checkout the Github repo examples and let me know your thoughts, examples or feedback using the form below.

Links

1. Github repo

Access Twig object variables using custom accessors was originally published in webthoughts.koderhut.eu on Medium, where people are continuing the conversation by highlighting and responding to this story.

The documentation covers well how to set up permissions for when using backend controllers for plug-in configuration, but no mention of how to accomplish the same when using a SettingsModel implementation.

Hint: It’s all in the plug-in definition

To register an access permission open your ‘Plugin.php’ plug-in definition class and add the following method:

class Plugin
    extends PluginBase
{
    ...
    public function registerPermissions()
    {
        return [
            'vendor_name.plugin_name.config_permission' => [
                'label' => 'Permission Label',
                'tab'   => 'Tab Name'
            ],
        ];
    }

}

The registerPermissions() method configures a permission type that you will need to add to a backend user in order to allow that user access to those configuration options.
The method needs to return an array of permissions that have the same form as in the code section above. The array element’s key is composed from the vendor name, plug-in name and an identifier for the permission all connected using the dot notation. The value of the array’s element is itself an array composed of two required elements: label and tab. The label is used to display a friendly text in the user interface. The tab element is used for grouping multiple permissions under specific tabs for easier access.

Now that we set the permissions let’s instruct OctoberCMS to enforce these rules.
To do so, in your plug-in’s definition class edit the registerSettings() method:

class Plugin
    extends PluginBase
{
    ...
    public function registerSettings()
    {
        return [
            'name_of_group' => [
                'label'       => 'Group label',
                'description' => 'Quick description',
                'icon'        => 'icon-rss',
                'class'       => 'VendorName\PluginName\Models\ModelClassName',
                'order'       => 500,
                'keywords'    => 'rss feed',
                'category'    => 'Settings category',
                'permissions' => ['vendor_name.plugin_name.config_permission'],
            ]
        ];
    }

}

Quick recap on the configs needed

The registerSettings() method is used to configure a plug-in’s settings page inside the OctoberCMS platform. This is well documentated in the docs and I will not go in too much detail in this article, but only point out a few of the key settings which I had trouble understanding too.
First, the key of each element in the returned array represents the name that OctoberCMS will use to identify a configuration page and also generate the links to it if you are implementing the SettingsModel for plug-in configuration. You can use any name you want as keys, but be careful because that name will be used in URLs as well. So, it needs to be URL friendly.
The category key is used to group the different configuration pages of a plug-in in the left sidebar of the Settings section. One issue that I had was the fact that I was using this config as a vendor name group tag, but OctoberCMS uses the exact value of that key in order to generate the group-code attribute of the tag. This means that if you use a translation tag for the value, OctoberCMS will automatically generate a separate group for two plug-ins even though the translated value is the same.
Finally, the permissions tag. The value for this key requires to be an array of values representing the permissions a user requires to have in order to gain access to that specific configuration page. The values for this tag are combined in the same way as we registered them above: the vendor_name followed by the plug-in name and either a * (asterisk symbol) or a specific access identifier. Using the asterisk symbol means that any user which has any permission of type vendor_name.plugin_name can access that page.

Conclusion

To make the long story short, first register the permission identifiers with the OctoberCMS platform by using the registerPermissions() method. Then, add a permissions key with an array of permission identifiers to each configuration page you register with OctoberCMS through the registerSettings() method.
The permissions key we discussed throughout article also applies when your plug-in uses backend controllers. In this case OctoberCMS will only hide the link to your configuration page, but the page will still be accessible with a direct link. To properly secure the config page when using a backend controller you also need to add a few validations as described in the documentation.

*Disclaimer: The OctoberCMS name and logo used in this article are property of octobercms.com and its creators.

Configure access permissions for OctoberCMS plug-ins was originally published in webthoughts.koderhut.eu on Medium, where people are continuing the conversation by highlighting and responding to this story.

Myself, I believe I am a security conscious person and for me WP doesn’t have a good track record in this regard. This coupled with the fact that most of the WP code, if any, is not built using an object oriented arhitecture and making it very difficult at times to extend or maintain it, made me search for an alternative.

That’s how I found BoltCMS and OctoberCMS. Both of these have the easines of use that WP gives a writer, but unlinke WP these CMS’s help the developer as well. Both systems code is based on industry standards giving developers a clean environment to work with either maintaining the system or adding new functionality as need requires. It also helps designers and front-end developers by integrating Twig, a nice, friendly templating engine allowing them to bring their vision of the UI to the users using a flexible, secure and easy to learn syntax and making template portability between CMSs a breeze.

In this article I will talk about OctoberCMS only, but be sure to check-out BoltCMS too. If you just want to see the code jump at the bottom of the article to find the Github link.

Digging into the code

I presume you already have OctoberCMS install and if not you can use the link above. I will not detail here the installation process for OctoberCMS because it is an easy process and well documentated on their own website.

Enough with the introductions and let’s jump into the code by extending a component from a third-party plugin.

For this article we will extend RainLab’s Blog plugin and more precisly the Post component. We will add a new property and a new attribute to each post that will contain the full article URL.

Before we begin we need to install RainLab’s Blog plug-in for OctoberCMS. So, head over to the plug-in’s page and checkout the installation instructions.

After installing the plug-in we will need to create a new plug-in of our own in order to not have our work erased when we update the Blog plug-in.

So, in the console write the following command:

$ php artisan create:plugin KoderHut.BlogExtension

You can substitute KoderHut with your own name or your company’s name.

At this point we created our first OctoberCMS plug-in. This command will only create a skeleton folder structure and add a class called Plugin and a Yaml file called version.yaml which will store the versions of our plug-in. You can find more info on this latter file in the docs.

Inside the Plugin class you will find a method called pluginDetails(). This method is used by OctoberCMS to display the info about the plug-in to the end-user. Check-it out and update the info with your own details.

Next let’s tell OctoberCMS that our plug-in requires RainLab’s Blog plug-in in order to function.

To do this just add the next line into the Plugin class:

/**
 * Plugin dependecies
 *
 * @var array
 */
public $require = ['RainLab.Blog'];

The $require class property is read by OctoberCMS to check for dependencies amoung plug-ins.

Now that we added our dependency let’s proceed and overwrite RainLab’s Post component. For this we need to create a new component in our module. Do this by writing the following in your command line:

$ php artisan create:component KoderHut.BlogExtension Post

I warned you that OctoberCMS will make your developer life easy, no?

Now, you should find that a new folder, named components, was created in your plug-in folder. It contains a class called Post, a folder with the same name with a Twig file called default.htm. The Twig file is used to render the component’s HTML, but in our case we will not need it and you can delete it.

By default, your Post class will extend the ComponentBase class. We will need to change that to extend RainLab’s Post class instead.

First, update the ‘use’ statements with the following:

use Cms\Classes\ComponentBase,
    Cms\Classes\Page;

use RainLab\Blog\Components\Post as RainLabPost,
    RainLab\Blog\Models\Post as BlogPost;

Next, update the class definition to this:

/**
 * Class Post
 *
 * @package KoderHut\BlogExtension\Components
 */
class Post
    extends RainLabPost
{...}

Now, let’s update the properties definitions and add a new property to set the page that will be used to view the post. This page also contains information about the URL which we will need in order to properly generate the URL back to the post.

So, add the following code to the Post class and overwrite any existing methods:

/**
 * Override of original method
 * - add new setting for the post page id
 *
 * @return array
 */
public function defineProperties()
{
    $parentProps = parent::defineProperties();

    $properties = array_merge(
        $parentProps,
        [
            'postPage' => [
                'title'       => 'rainlab.blog::lang.settings.posts_post',
                'description' => 'rainlab.blog::lang.settings.posts_post_description',
                'type'        => 'dropdown',
                'default'     => 'blog/post',
                'group'       => 'Links',
            ],
        ]
    );

    return is_array($properties) ? $properties : $parentProps;
}

/**
 * Retrieve the postPage properties
 *
 * @return string
 */
public function getPostPageOptions()
{
    return Page::sortBy('baseFileName')->lists('baseFileName', 'baseFileName');
}

The defineProperties() method adds the new property to the component, while the getPostPageOptions() method retrieves the stored setting.

Now, we add the URL back to the post by overriding the loadPost() method with the following code:

/**
 * Reference to the page name for linking to posts.
 * @var string
 */
public $postPage;

/**
 * Override of original method
 * - add the post URL to the post entity
 *
 * @return mixed
 */
protected function loadPost()
{
    $post     = parent::loadPost();
    $postPage = $this->property('postPage');

    if ($post instanceof BlogPost) {
        $post->setUrl($postPage, $this->controller);
    }

    return $post;
}

The final step to use our new component is either drag and drop it from the OctoberCMS components tab into the page, or if your page already contains the Post component change the component definition code from this:

[blogPost]
slug = "{{ :slug }}"
postPage = "blog/post"

to this:

[KoderHut\BlogExtension\Components\Post blogPost]
slug = "{{ :slug }}"
postPage = "blog/post"

Final thoughts

Although OctoberCMS is in beta at the moment of writing this article I can already see the power and flexibility it provides to both non-technical end-users as well as developers. For end-users, the plug-in system is well designed and simple that with just a few clicks one can add all types of functionality. The number of plug-ins rises fast for both paid as well as free and pretty soon I believe there will be no need to go back to WP.

Also, having its code well organized, following industry standards and taking full advantage of the Laravel 5 framework that powers it, as well as all the design patterns and good practices established by the community it makes a developer’s life really easy.

If you missed any step or just want to quickly checkout the source code for the plug-in, you can find it on my Github account or visiting the link below.

I hope you enjoyed the article. Any feedback is appreciated and sharing is welcomed.

BlogExtension — Github source: https://github.com/rendler-denis/blogextension

Extending an OctoberCMS component was originally published in webthoughts.koderhut.eu on Medium, where people are continuing the conversation by highlighting and responding to this story.