Updated README, added some usage explanations on the stack:init comma…

…nd and a FAQ
kiboko-labs · Sep 29, 2020 · 272a614 · 272a614
1 parent 0ce6f17
commit 272a614
Show file tree

Hide file tree

Showing 9 changed files with 248 additions and 29 deletions.
diff --git a/README.md b/README.md
@@ -7,6 +7,7 @@ This project aims at building your Docker stack for [OroCommerce](https://oroinc
 
 * [Installation](#installation)
 * [Usage](#usage)
+* [Frequently Asked Questions](#frequently-asked-questions)
 * [Supported versions and flavors](#supported-versions-and-flavours)
   * [OroPlatform](#oroplatform)
   * [OroCRM](#orocrm)
@@ -60,6 +61,10 @@ You can invoke the following command that will guess what you need and a wizard
 
 `kloud stack:init`
 
+Once the command is finished, you will have a file named `.env.dist` containing the required environment variables for the stack.
+This file has to be renamed to `.env` in order to be used by Docker Compose.
+The command have set some ports values for all services, you may wish to change them depending on your environment.
+
 #### Available command line options
 
 * Database engine selection
@@ -107,6 +112,193 @@ If you need to test if the images you are using are following every constraint y
 
 `kloud image:test`
 
+Frequently Asked Questions
+---
+
+### I am having some warnings while launching `docker-compose up` for the first time
+
+If you are having this sort of messages:
+
+```
+WARNING: The MAILCATCHER_PORT variable is not set. Defaulting to a blank string.
+ERROR: The Compose file './docker-compose.yml' is invalid because:
+services.mail.ports contains an invalid type, it should be a number, or an object
+```
+
+Those warnings and errors are due to missing environment variables, probably because you did 
+not copy the `.env.dist` file to a `.env` file.
+
+### What is the use of the `I_AM_DEVELOPER_DISABLE_INDEX_IP_CHECK` environment variable?
+
+This environment variable is used to disable the IP check in the `public/index_dev.php` file.
+To benefit from this feature, you will need to apply the following patch: 
+
+```patch
+Index: public/index_dev.php
+IDEA additional info:
+Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
+<+>UTF-8
+===================================================================
+--- public/index_dev.php
++++ public/index_dev.php
+@@ -13,9 +13,12 @@
+
+ // This check prevents access to debug front controllers that are deployed by accident to production servers.
+ // Feel free to remove this, extend it, or make something more sophisticated.
+-if (isset($_SERVER['HTTP_CLIENT_IP'])
+-    || isset($_SERVER['HTTP_X_FORWARDED_FOR'])
+-    || !in_array(@$_SERVER['REMOTE_ADDR'], array('127.0.0.1', 'fe80::1', '::1'))
++if (!isset($_ENV['I_AM_DEVELOPER_DISABLE_INDEX_IP_CHECK'])
++    && (
++        isset($_SERVER['HTTP_CLIENT_IP'])
++        || isset($_SERVER['HTTP_X_FORWARDED_FOR'])
++        || !in_array(@$_SERVER['REMOTE_ADDR'], array('127.0.0.1', 'fe80::1', '::1'))
++    )
+ ) {
+     header('HTTP/1.0 403 Forbidden');
+     exit('You are not allowed to access this file. Check '.basename(__FILE__).' for more information.');
+```
+
+### How to access My application's frontend?
+
+The application frontend can be accessed through the port defined in the `HTTP_PORT`
+environment variable value.
+
+### How to configure the mailer in the `parameters.yml` file?
+
+The parameters should be set as the following:
+
+```yaml
+parameters:
+    mailer_transport: smtp
+    mailer_host: mail
+    mailer_port: 1025
+    mailer_encryption: null
+    mailer_user: null
+    mailer_password: null
+```
+
+Notice that the `MAILER_PORT` variable is not used, as this port is the one from your 
+computer's point of view, not a container's point of view in the stack.
+
+### How to configure the websocket service in the `parameters.yml` file?
+
+The parameters should be set as the following on Oro 4.1+:
+
+```yaml
+parameters:
+    websocket_bind_address: 0.0.0.0
+    websocket_bind_port: 8080
+    websocket_frontend_host: '*'
+    websocket_frontend_port: '%env(WEBSOCKET_PORT)%'
+    websocket_frontend_path: ''
+    websocket_backend_host: '*'
+    websocket_backend_port: '%env(WEBSOCKET_PORT)%'
+    websocket_backend_path: ''
+    websocket_backend_transport: tcp
+    websocket_backend_ssl_context_options: {  }
+```
+
+Notice that the `WEBSOCKET_PORT` variable is not used for the `websocket_bind_port`, as this
+port is the one from your computer's point of view, not a container's point of view in the stack.
+
+### How to configure the database service in the `parameters.yml` file?
+
+The parameters should be set as the following on Oro 4.1+:
+
+```yaml
+parameters:
+    database_driver: pdo_pgsql
+    database_host: sql
+    database_port: null
+    database_name: '%env(DATABASE_NAME)%'
+    database_user: '%env(DATABASE_USER)%'
+    database_password: '%env(DATABASE_PASS)%'
+    database_driver_options: {  }
+```
+
+Notice that the `DATABASE_PORT` variable is not used, as this port is the one from your 
+computer's point of view, not a container's point of view in the stack.
+
+### How to configure the search engine service in the `parameters.yml` file?
+
+The parameters should be set as the following:
+
+```yaml
+parameters:
+    search_engine_name: elastic_search
+    search_engine_host: elasticsearch
+    search_engine_port: null
+    search_engine_index_prefix: oro_search
+    search_engine_username: null
+    search_engine_password: null
+    search_engine_ssl_verification: null
+    search_engine_ssl_cert: null
+    search_engine_ssl_cert_password: null
+    search_engine_ssl_key: null
+    search_engine_ssl_key_password: null
+    website_search_engine_index_prefix: oro_website_search
+```
+
+Notice that the `ELASTICSEARCH_PORT` variable is not used, as this port is the one from your 
+computer's point of view, not a container's point of view in the stack.
+
+### How to configure the message queue service in the `parameters.yml` file?
+
+The parameters should be set as the following:
+
+```yaml
+parameters:
+    message_queue_transport: amqp
+    message_queue_transport_config:
+        host: amqp
+        port: '5672'
+        user: '%env(RABBITMQ_USER)%'
+        password: '%env(RABBITMQ_PASSWORD)%'
+        vhost: /
+```
+
+Notice that the `ELASTICSEARCH_PORT` variable is not used, as this port is the one from your 
+computer's point of view, not a container's point of view in the stack.
+
+### How to access to Mailcatcher's interface?
+
+The Mailcatcher interface can be accessed through the port defined in the `MAILCATCHER_PORT`
+environment variable value.
+
+### How to access RabbitMQ manager's interface?
+
+The RabbitMQ manager interface can be accessed through the port defined in the `RABBITMQ_PORT`
+environment variable value.
+
+### How to access Dejavu's interface for Elasticsearch?
+
+The Dejavu interface can be accessed through the port defined in the `DEJAVU_PORT`
+environment variable value.
+
+Additionnally, the `ELASTICSEARCH_PORT` variable should be defined in order to make
+Elasticsearch's API accessible from your computer.
+
+### How to access Elasticsearch's API?
+
+The Elasticsearch API can be accessed through the port defined in the `ELASTICSEARCH_PORT`
+environment variable value.
+
+### How to access Kibana's interface?
+
+The Kibana interface can be accessed through the port defined in the `KIBANA_PORT`
+environment variable value.
+
+### How to access Redis service from your computer?
+
+The Redis servcie can be accessed through the port defined in the `REDIS_PORT`
+environment variable value.
+
+### How to access MySQL or PostgreSQL service from your computer?
+
+The MySQL or PostgreSQL servcie can be accessed through the port defined in the `SQL_PORT`
+environment variable value.
+
 Supported versions and flavours
 ---
 

diff --git a/src/Domain/Stack/Compose/Normalizer/ServiceDenormalizer.php b/src/Domain/Stack/Compose/Normalizer/ServiceDenormalizer.php
@@ -88,7 +88,6 @@ public function denormalize($data, string $type, string $format = null, array $c
                     } else if (isset($matches[2])) {
                         $service->addEnvironmentVariables(new EnvironmentVariable(new Variable($matches[1]), $this->expressionParser->parse($matches[2])));
                     } else {
-                        var_dump($matches);
                         throw new \RuntimeException(strtr('Invalid environment variable format: "%value%".', ['%value%' => $value]));
                     }
                 } else if (!empty($value)) {

diff --git a/src/Domain/Stack/OroPlatform/Builder.php b/src/Domain/Stack/OroPlatform/Builder.php
@@ -43,7 +43,7 @@ public function __construct(string $stacksPath)
 
     public function matches(DTO\Context $context): bool
     {
-        return in_array($context->application, ['orocommerce', 'orocrm', 'oroplatform', 'marello'], true);
+        return in_array($context->application, ['orocommerce', 'orocrm', 'oroplatform', 'marello', 'middleware'], true);
     }
 
     public function build(DTO\Context $context): DTO\Stack

diff --git a/src/Domain/Stack/OroPlatform/Service/ElasticSearch.php b/src/Domain/Stack/OroPlatform/Service/ElasticSearch.php
@@ -31,11 +31,16 @@ public function matches(DTO\Context $context): bool
 
     private function buildImageTag(DTO\Context $context)
     {
-        if (Semver::satisfies($context->applicationVersion, '^3.0')) {
+        if (in_array($context->application, ['oroplatform', 'orocrm', 'orocommerce']) && Semver::satisfies($context->applicationVersion, '^3.0')
+            || in_array($context->application, ['marello']) && Semver::satisfies($context->applicationVersion, '^2.0')
+        ) {
             return 'docker.elastic.co/elasticsearch/elasticsearch-oss:6.8.12';
         }
 
-        if (Semver::satisfies($context->applicationVersion, '^4.0')) {
+        if (in_array($context->application, ['oroplatform', 'orocrm', 'orocommerce']) && Semver::satisfies($context->applicationVersion, '^4.0')
+            || in_array($context->application, ['marello']) && Semver::satisfies($context->applicationVersion, '^3.0')
+            || in_array($context->application, ['middleware']) && Semver::satisfies($context->applicationVersion, '^1.0')
+        ) {
             return 'docker.elastic.co/elasticsearch/elasticsearch-oss:7.9.1';
         }
 
@@ -57,11 +62,7 @@ public function build(DTO\Stack $stack, DTO\Context $context): DTO\Stack
                     new VolumeMapping('elasticsearch', '/usr/share/elasticsearch/data'),
                     new VolumeMapping('./.docker/elasticsearch/elasticsearch.yml', '/usr/share/elasticsearch/config/elasticsearch.yml'),
                 )
-                ->setRestartOnFailure(),
-            (new Service('dejavu', 'appbaseio/dejavu'))
-                ->addPorts(
-                    new PortMapping(new Variable('DEJAVU_PORT'), 1358)
-                )
+                ->setRestartOnFailure()
             )
             ->addVolumes(
                 new Volume('elasticsearch', ['driver' => 'local'])
@@ -98,6 +99,19 @@ public function build(DTO\Stack $stack, DTO\Context $context): DTO\Stack
             new EnvironmentVariable(new Variable('APPLICATION_DOMAIN')),
         );
 
+        if ($context->withDejavu === true) {
+            $stack->addServices(
+                (new Service('dejavu', 'appbaseio/dejavu'))
+                    ->addPorts(
+                        new PortMapping(new Variable('DEJAVU_PORT'), 1358)
+                    )
+            );
+
+            $stack->addEnvironmentVariables(
+                new EnvironmentVariable(new Variable('DEJAVU_PORT')),
+                );
+        }
+
         return $stack;
     }
 }
diff --git a/src/Domain/Stack/OroPlatform/Service/Kibana.php b/src/Domain/Stack/OroPlatform/Service/Kibana.php
@@ -28,11 +28,16 @@ public function matches(DTO\Context $context): bool
 
     private function buildImageTag(DTO\Context $context)
     {
-        if (Semver::satisfies($context->applicationVersion, '^3.0')) {
+        if (in_array($context->application, ['oroplatform', 'orocrm', 'orocommerce']) && Semver::satisfies($context->applicationVersion, '^3.0')
+            || in_array($context->application, ['marello']) && Semver::satisfies($context->applicationVersion, '^2.0')
+        ) {
             return 'docker.elastic.co/kibana/kibana:6.8.11';
         }
 
-        if (Semver::satisfies($context->applicationVersion, '^4.0')) {
+        if (in_array($context->application, ['oroplatform', 'orocrm', 'orocommerce']) && Semver::satisfies($context->applicationVersion, '^4.0')
+            || in_array($context->application, ['marello']) && Semver::satisfies($context->applicationVersion, '^3.0')
+            || in_array($context->application, ['middleware']) && Semver::satisfies($context->applicationVersion, '^1.0')
+        ) {
             return 'docker.elastic.co/kibana/kibana:7.8.1';
         }
 

diff --git a/src/Domain/Stack/OroPlatform/Service/Logstash.php b/src/Domain/Stack/OroPlatform/Service/Logstash.php
@@ -24,11 +24,16 @@ public function matches(DTO\Context $context): bool
 
     private function buildImageTag(DTO\Context $context)
     {
-        if (Semver::satisfies($context->applicationVersion, '^3.0')) {
+        if (in_array($context->application, ['oroplatform', 'orocrm', 'orocommerce']) && Semver::satisfies($context->applicationVersion, '^3.0')
+            || in_array($context->application, ['marello']) && Semver::satisfies($context->applicationVersion, '^2.0')
+        ) {
             return 'docker.elastic.co/logstash/logstash:6.8.11';
         }
 
-        if (Semver::satisfies($context->applicationVersion, '^4.0')) {
+        if (in_array($context->application, ['oroplatform', 'orocrm', 'orocommerce']) && Semver::satisfies($context->applicationVersion, '^4.0')
+            || in_array($context->application, ['marello']) && Semver::satisfies($context->applicationVersion, '^3.0')
+            || in_array($context->application, ['middleware']) && Semver::satisfies($context->applicationVersion, '^1.0')
+        ) {
             return 'docker.elastic.co/logstash/logstash:7.8.1';
         }
 

diff --git a/src/Domain/Stack/OroPlatform/Service/MySQL.php b/src/Domain/Stack/OroPlatform/Service/MySQL.php
@@ -3,14 +3,12 @@
 namespace Kiboko\Cloud\Domain\Stack\OroPlatform\Service;
 
 use Kiboko\Cloud\Domain\Stack\Compose\EnvironmentVariable;
-use Kiboko\Cloud\Domain\Stack\Compose\Label;
 use Kiboko\Cloud\Domain\Stack\Compose\PortMapping;
 use Kiboko\Cloud\Domain\Stack\Compose\Service;
 use Kiboko\Cloud\Domain\Stack\Compose\Variable;
 use Kiboko\Cloud\Domain\Stack\Compose\Volume;
 use Kiboko\Cloud\Domain\Stack\Compose\VolumeMapping;
 use Kiboko\Cloud\Domain\Stack\DTO;
-use Kiboko\Cloud\Domain\Stack\Resource;
 use Kiboko\Cloud\Domain\Stack\ServiceBuilderInterface;
 
 final class MySQL implements ServiceBuilderInterface
@@ -35,10 +33,10 @@ public function build(DTO\Stack $stack, DTO\Context $context): DTO\Stack
                     new PortMapping(new Variable('SQL_PORT'), 3306),
                 )
                 ->addEnvironmentVariables(
-                    new EnvironmentVariable(new Variable('MYSQL_ROOT_PASSWORD'), new Variable('SQL_ROOT_PASSWORD')),
-                    new EnvironmentVariable(new Variable('MYSQL_DATABASE'), new Variable('SQL_DATABASE')),
-                    new EnvironmentVariable(new Variable('MYSQL_USER'), new Variable('SQL_USER')),
-                    new EnvironmentVariable(new Variable('MYSQL_PASSWORD'), new Variable('SQL_PASSWORD')),
+                    new EnvironmentVariable(new Variable('MYSQL_ROOT_PASSWORD'), new Variable('DATABASE_ROOT_PASSWORD')),
+                    new EnvironmentVariable(new Variable('MYSQL_DATABASE'), new Variable('DATABASE_NAME')),
+                    new EnvironmentVariable(new Variable('MYSQL_USER'), new Variable('DATABASE_USER')),
+                    new EnvironmentVariable(new Variable('MYSQL_PASSWORD'), new Variable('DATABASE_PASSWORD')),
                 )
                 ->addVolumeMappings(
                     new VolumeMapping('database', '/var/lib/mysql'),
@@ -52,11 +50,11 @@ public function build(DTO\Stack $stack, DTO\Context $context): DTO\Stack
         ;
 
         $stack->addEnvironmentVariables(
-            new EnvironmentVariable(new Variable('SQL_ROOT_PASSWORD')),
-            new EnvironmentVariable(new Variable('SQL_DATABASE')),
-            new EnvironmentVariable(new Variable('SQL_USER')),
-            new EnvironmentVariable(new Variable('SQL_PASSWORD')),
-            new EnvironmentVariable(new Variable('SQL_PORT')),
+            new EnvironmentVariable(new Variable('DATABASE_ROOT_PASSWORD'), 'password'),
+            new EnvironmentVariable(new Variable('DATABASE_NAME')),
+            new EnvironmentVariable(new Variable('DATABASE_USER')),
+            new EnvironmentVariable(new Variable('DATABASE_PASSWORD'), 'password'),
+            new EnvironmentVariable(new Variable('DATABASE_PORT')),
         );
 
         return $stack;

diff --git a/src/Domain/Stack/OroPlatform/Service/PostgreSQL.php b/src/Domain/Stack/OroPlatform/Service/PostgreSQL.php
@@ -34,10 +34,10 @@ public function build(DTO\Stack $stack, DTO\Context $context): DTO\Stack
                     new PortMapping(new Variable('SQL_PORT'), 5432),
                 )
                 ->addEnvironmentVariables(
-                    new EnvironmentVariable(new Variable('POSTGRES_ROOT_PASSWORD'), new Variable('SQL_ROOT_PASSWORD')),
-                    new EnvironmentVariable(new Variable('POSTGRES_DB'), new Variable('SQL_DATABASE')),
-                    new EnvironmentVariable(new Variable('POSTGRES_USER'), new Variable('SQL_USER')),
-                    new EnvironmentVariable(new Variable('POSTGRES_PASSWORD'), new Variable('SQL_PASSWORD')),
+                    new EnvironmentVariable(new Variable('POSTGRES_ROOT_PASSWORD'), new Variable('DATABASE_ROOT_PASSWORD')),
+                    new EnvironmentVariable(new Variable('POSTGRES_DB'), new Variable('DATABASE_NAME')),
+                    new EnvironmentVariable(new Variable('POSTGRES_USER'), new Variable('DATABASE_USER')),
+                    new EnvironmentVariable(new Variable('POSTGRES_PASSWORD'), new Variable('DATABASE_PASSWORD')),
                 )
                 ->addVolumeMappings(
                     new VolumeMapping('./.docker/[email protected]/sql/uuid-ossp.sql', '/docker-entrypoint-initdb.d/00-uuid-ossp.sql', true),
@@ -58,7 +58,11 @@ public function build(DTO\Stack $stack, DTO\Context $context): DTO\Stack
         );
 
         $stack->addEnvironmentVariables(
-            new EnvironmentVariable(new Variable('SQL_PORT')),
+            new EnvironmentVariable(new Variable('DATABASE_ROOT_PASSWORD'), 'password'),
+            new EnvironmentVariable(new Variable('DATABASE_NAME')),
+            new EnvironmentVariable(new Variable('DATABASE_USER')),
+            new EnvironmentVariable(new Variable('DATABASE_PASSWORD'), 'password'),
+            new EnvironmentVariable(new Variable('DATABASE_PORT')),
         );
 
         return $stack;