View on GitHub


Test Coverage

If you used a recipe, simply edit the ``stakkr.yml`` file manually to change a service
version or set any parameter. Else, copy the file ``stakkr.yml.tpl`` to ``stakkr.yml``
and set the right configuration parameters you need.

Configuration is validated. Read carefully the message in case of error.

Main configuration parameters should be defined in the ``services`` section.

You can define a list of services you want to have. Each service consists of a yml
file in the ``services/`` directory of the source code.
Each container ("Service") will have a hostname which is the ... service name.
To reach, for example, the elasticsearch server from a web application
use ``elasticsearch``. To connect to mysql it's ``mysql``.

Example of a LAMP stack :

.. code:: yaml

          enabled: true
          enabled: true
          version: 5.7
          ram: 1024M
          root_password: root
          enabled: true
          enabled: true
          version: latest
          ram: 1024M
          blocked_ports: [25, 465, 587]

To have a complete list of services, launch :

.. code:: shell

    $ stakkr services

The parameters are pretty generic, but some services could define new
parameters such as databases for passwords :

.. code:: yaml

          # Enable it or not. Default false
          enabled: false
          # Version on docker hub
          version: latest
          # Limited as much as possible to keep computer resources usage
          ram: 512M
          # Displayed after stakkr has started
          service_name: Portainer (Docker Webadmin)
          # Same than above
          service_url: http://{}
          # Port to block for outgoing connexions. Requires :
          # - "cap_add: [NET_ADMIN, NET_RAW]" in compose file
          # - iptables on the container
          blocked_ports: []

Stakkr is now full https with an self-signed certificate. If you don't
want to accept the certificate everytime, you can ask chrome to accept all *localhost*
certificates by calling ``chrome://flags/#allow-insecure-localhost`` as a URL.

To enter a container you can use the ``stakkr console`` command. Nevertheless, to avoid
doing :

.. code:: bash

    stakkr console php
    cd app
    composer install

You can set the following alias in the ``stakkr.yml`` file :

.. code:: yaml


      description: Run a PHP composer command
        - container: php
          user: www-data
          args: [php, /home/www-data/bin/composer]

And then :

.. code:: bash

    cd app
    stakkr composer install

An alias is a dictionary with :

* A key that is the command name (``composer`` above)
* A description displayed when you run ``stakkr``
* An exec list with all commands to run when ``stakkr {alias}`` is invoked.
    * ``container`` is the container name
    * ``user`` the user to run the command
    * ``args`` a dictionnary with the command cut in pieces (that's required).

Network and changes in general
You can define your own network in compose.ini by setting a ``subnet``.
It's optional, and it's probably better to let it like that.

   If you change that, run ``docker system prune -f -a --volumes`` which removes orphans images, stopped container, etc ...

   As we use ``traefik`` as a reverse proxy, no need to expose any ports
   or to access containers directly via their IP.

   Also, if you change any parameter such as an environment variable
   run a ``stakkr restart --recreate`` to make sure that you start from
   a clean environment.

Special case of Elasticsearch
ElasticSearch needs a few manual commands to start from the version 5.x. Before starting stakkr, do the following :

.. code:: shell

    $ mkdir data/elasticsearch
    $ sudo chown -R 1000:1000 data/elasticsearch
    $ sudo sysctl -w vm.max_map_count=262144

Special case of xhgui service
To be able to profile your script, add the service xhgui and read the

Other useful parameters

Project name (will be used as container's prefix). It should be
different for each project.

.. code:: yaml

    environment: dev # Environment variables sent to containers

    proxy: # traefik
      enabled: true # By default it's enabled
      domain: localhost # append domain. Example : http://apache.my_project.localhost
      http_port: 80 # Http Port to expose
      https_port: 443 # Https Port to expose

    project_name: '' # detected automatically, usually the main directory name

    subnet: '' # if you really need to override the default network

    uid: # if you really need to set a specific uid for files, current user by default
    gid: # same for gid, current user's group by default

Files location

Public Files
-  All files served by the web server are located into ``www/``

Services Data
-  MySQL data is into ``data/mysql``
-  Mongo data is into ``data/mongo``
-  ElasticSearch data is into ``data/elasticsearch``
-  Redis data is into ``data/redis``
- ...

-  Logs for Apache and PHP are located into ``logs/``
-  Logs for MySQL are located into ``data/mysql/`` (slow and error).

-  If you need to override the PHP configuration you can put a file in
   ``conf/php-fpm-override`` with a ``.conf`` extension. The format is
   the fpm configuration files one. Example:
   ``php_value[memory_limit] = 127M``.
-  If you need to override the mysql configuration you can put a file in ``conf/mysql-override``
   with a ``.cnf`` extension.

Add binaries
You can add binaries (such as phpunit) that will automatically be
available from the PATH by putting it to ``home/www-data/bin/``

   You can use ``home/www-data`` to put everyhting you need to keep:
   your shell parameters in `.bashrc`, your ssh keys/config into `.ssh`, etc.