From 272a6147f3206a3a6db5083ab36b16f509ff4965 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9gory=20Planchat?= Date: Tue, 29 Sep 2020 23:23:34 +0200 Subject: [PATCH] Updated README, added some usage explanations on the stack:init command and a FAQ --- README.md | 192 ++++++++++++++++++ .../Normalizer/ServiceDenormalizer.php | 1 - src/Domain/Stack/OroPlatform/Builder.php | 2 +- .../OroPlatform/Service/ElasticSearch.php | 28 ++- .../Stack/OroPlatform/Service/Kibana.php | 9 +- .../Stack/OroPlatform/Service/Logstash.php | 9 +- .../Stack/OroPlatform/Service/MySQL.php | 20 +- .../Stack/OroPlatform/Service/PostgreSQL.php | 14 +- .../Stack/OroPlatform/Service/RabbitMQ.php | 2 + 9 files changed, 248 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 4a0f4aa..67f0a42 100644 --- 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 index 191a7ef..7cacb8c 100644 --- 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 index 696974e..55b806a 100644 --- 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 index 56e979f..626f474 100644 --- 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; } } \ No newline at end of file diff --git a/src/Domain/Stack/OroPlatform/Service/Kibana.php b/src/Domain/Stack/OroPlatform/Service/Kibana.php index c56b414..f61e964 100644 --- 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 index 9422eb3..02c3036 100644 --- 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 index 2f5431c..4bee987 100644 --- 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 index 4737d69..8df4d03 100644 --- 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/postgres@9.6/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; diff --git a/src/Domain/Stack/OroPlatform/Service/RabbitMQ.php b/src/Domain/Stack/OroPlatform/Service/RabbitMQ.php index 4d0ef47..3bb0c02 100644 --- a/src/Domain/Stack/OroPlatform/Service/RabbitMQ.php +++ b/src/Domain/Stack/OroPlatform/Service/RabbitMQ.php @@ -61,6 +61,8 @@ public function build(DTO\Stack $stack, DTO\Context $context): DTO\Stack $stack->addEnvironmentVariables( new EnvironmentVariable(new Variable('RABBITMQ_PORT')), + new EnvironmentVariable(new Variable('RABBITMQ_USER'), 'rabbitmq'), + new EnvironmentVariable(new Variable('RABBITMQ_PASSWORD'), 'password'), ); return $stack;