Updated docs, easier quick start with example

docs/source/configuration_conception.rst

@@ -25,7 +25,7 @@ Test and production environment
 
 They are mostly the same except fact, that the domains are different and, the test environment does not have real SSL enabled.
 
-**Domain suffix design pattern**, is a pattern where we have a BASE DOMAIN eg. riotkit.org, then in test environment we add a suffix, so it is riotkit.org.localhost on our test environment.
+**Domain suffix design pattern**, is a pattern where we have a BASE DOMAIN eg. riotkit.org, in test environment we add a suffix, so it would be riotkit.org.localhost on our test environment.
 This practice gives us out-of-the-box working DNS on local testing machine.
 
 

docs/source/first-steps.rst

@@ -12,7 +12,8 @@ To install:
 Let's go!
 ---------
 
-Project template is hosted on **git** version control system and it's updater bases on it, to easily distinct changes made by you from the incoming update.
+Project template is hosted on **git** version control system, with git it's possible to update your environment with newer template version.
+Updates are not mandatory, and the template may be not always backwards compatible, because it's a template you can use fully or only parts of it.
 
 1. Create your project directory (replace "your-project-name" with a proper name):
 
@@ -30,9 +31,11 @@ Project template is hosted on **git** version control system and it's updater ba
 2. Take a look around, check documentation for:
 
 - :ref:`structure`
-- :ref:`features`
+- :ref:`features` 
 - :ref:`configuration_reference`
 
+You may be interested with placing your docker container definitions at **./apps/conf**
+
 3. Configure the project:
 
 Before you will start changing the configuration, please a look at the :ref:`configuration_conception`.
@@ -49,3 +52,9 @@ Before you will start changing the configuration, please a look at the :ref:`con
     make help
     make start
 
+5. Access configured domain on web browser
+
+Go to http://the-configured-domain-here.localhost, enjoy.
+
+You may want to check a complete example: :ref:`general_concept`
+

docs/source/general_concept.rst

@@ -1,3 +1,6 @@
+
+.. _general_concept:
+
 General conception
 ==================
 
@@ -67,7 +70,7 @@ Main domain and domain suffix concept
 -------------------------------------
 
 **MAIN_DOMAIN** can be defined in **.env** and reused in YAML files together with **DOMAIN_SUFFIX**.
-It opens huge possibility of creating test environments which have different DNS settings.
+It opens huge possibility of creating test environments, which have different DNS settings.
 Sounds like a theory? Let's see a practical example!
 
 **Scenario for test environment:**
@@ -93,7 +96,7 @@ Sounds like a theory? Let's see a practical example!
     Then the SOME SERVICE will have address http://some-service.iwa-ait.org
 
 
-It's so much flexible that you can host multiple subdomains on main domain, but you can also use totally different domain.
+It's so much flexible that you can host multiple subdomains on main domain, but you can also use totally different domains.
 
 **Example:**
 
@@ -116,3 +119,36 @@ It's so much flexible that you can host multiple subdomains on main domain, but
 
 - some-service.iwa-ait.org.localhost
 - other-service.example.org.localhost
+
+**Complete example**
+
+In `.env` file:
+
+.. code:: bash
+
+    MAIN_DOMAIN=iwa-ait.org
+    DOMAIN_SUFFIX=.localhost
+
+
+In `./apps/conf/docker-compose.phpmyadmin.yaml`:
+
+.. code:: yaml
+
+    db_mysql_admin:
+        image: phpmyadmin/phpmyadmin
+        environment:
+            - PMA_HOST=db_mysql
+
+            # gateway configuration
+            - VIRTUAL_HOST=pma.${MAIN_DOMAIN}${DOMAIN_SUFFIX}
+            - VIRTUAL_PORT=80
+        labels:
+            org.docker.services.dashboard.enabled: true
+            org.docker.services.dashboard.description: 'MySQL database management'
+            org.docker.services.dashboard.icon: 'pe-7s-server'
+            org.docker.services.dashboard.only_for_admin: true
+
+
+Now you can access http://pma.iwa-ait.org.localhost in your browser.
+On production server just remove the DOMAIN_SUFFIX value to have http://pma.iwa-ait.org - simple enough, huh?
+

docs/source/index.rst

@@ -34,6 +34,7 @@ Goals:
    configuration_conception
    features
    ansible
+   configuration_reference
 
 From authors
 ============