8/21/2017 - 9:07 PM

Design document to explain the changes done in amahi codebase

Design document to explain the changes done in amahi codebase

Design Document

Amahi now supports Docker. It is an open source software for automating the deployment of applications inside software containers. A container image is a lightweight, stand-alone, executable package of a piece of software that includes everything needed to run it: code, runtime, system tools, system libraries, settings.

For more information related to contianers refer to :

The idea was to get/build images of different applications and run them using docker on the hda. The benefit of using containers as opposed to the earlier method is that each container runs in an isolated environment. So they can each have different versions of different applications. For example we can have an app running on php5 and another app running on php7. Using this method if we had an image available for an app then we can directly run it using docker without any problems.

Architecture Overview : How it works? Diagram Explain the flow.

Lets assume we are trying to run multiple container apps. Let them be App1, App2, App3 and App4.

NOTE: Each app will have its own networking stack and hence can run a service on any port that they want.

App1 - 9000, 80 App2 - 8000, 80 App3 - 5000, 80 App4 - 22, 80

Each app has a web server running on port 80 (let’s assume) and they have some other service running on different ports. There can be multiple services running on different ports.

We want the web interface of each of the app to be accessible to a user. Assume a user is running their HDA at IP address: and domain

They want to access App1 at, App2 at and so on. Inside the HDA each app is running inside an isolated environment with their own networking stack and hence they are not reachable from the outside world. So how do we work around this problem? The answer to that is reverse proxy.

We have apache running on our HDA which handles all the requests coming on * So for container apps we bind their web server port with a port on the host.

App1 -> 80 binds to -> 35001 on host App2 -> 80 binds to -> 35002 on host App3 -> 80 binds to -> 35003 on host App4 -> 80 binds to -> 35004 on host

This “binding” is similar to port forwarding. Docker by default runs these containers on a separate network and each of those containers have an IP address (local, accessible only inside the host machine) and run their own networking stack.

Once the port binding is complete if we access -> we should get the web interface of App1 and so on. But for our users we want the app to be reachable at So earlier the hda used to create a virtual host file for each app which used to run the relevant app server based on the url. For container apps, the present approach does this:

The apache running on host reverse proxies all requests coming on to http://localhost:35001 , This way for the user the url is and they can still access the web interface of the app.

Files Modified

Following files have been modified or added.

Gemfile # Added gem docker-api                                           
app/models/app.rb # container installation function added
app/models/webapp.rb # Reverse proxy implementation                     
misc/webapps/app-container.conf # Handles reverse proxy configuration of containerised apps              
spec/models/app_spec.rb # Test cases                           

# A set of scripts to test container app installation and uninstallation         

Brief overview of code

The container app installation is triggered using a function : install_container_app in app/models/app.rb.

The installation process remains the same and follows the same flow of control as before.

script/install-ap calls install_bg function in app.rb and that takes care of the app installation.

In install_bg function we check if the app type is container and if yes then the rest is managed by install_container_app function. If it's not a container type app then see the else statement, where we just create a webapp for normal app.

if installer.kind.include? "container"
                # Try installing the container app
                # Mark the installation as failed if it returns false
                # For container app webapp creation will be handled inside the "install_container_app" function
                if !install_container_app(installer, webapp_path, identifier)
                    self.install_status = 999
                # Create the webapp normally if its not a container app
                self.create_webapp(:name => name, :path => webapp_path, :deletable => false, :custom_options => installer.webapp_custom_options, :kind => installer.kind)

For container type apps the webapp creation is handled by the install_container_app function itself. Please note the way we are checking if an app is of container type? Notice : if installer.kind.include? "container". The idea is that we might need to handle installation of different kind of container apps differently. So on while adding container apps, for the kind field we have to use something like : container-php5, container-python, container-custom, etc. So to check if an app is container type we have to see if the installer.kind includes "container" pattern inside it.