stakkr-org/stakkr

View on GitHub
docs/pages/configuration.rst

Summary

Maintainability
Test Coverage
Configuration
=============

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.


Services
-----------------
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

      services:
        adminer:
          enabled: true
        mysql:
          enabled: true
          version: 5.7
          ram: 1024M
          root_password: root
        apache:
          enabled: true
        php:
          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

      services:
        any_service:
          # 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: []

HTTPS
-----
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.

Aliases
-------
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

  services:
  ...

  aliases:
    composer:
      description: Run a PHP composer command
      exec:
        - 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.

.. WARNING::
   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
`documentation`_


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
~~~~~~
-  Logs for Apache and PHP are located into ``logs/``
-  Logs for MySQL are located into ``data/mysql/`` (slow and error).

Configuration
~~~~~~~~~~~~~~~
-  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/``


.. IMPORTANT::
   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.