Skip to content

Commit 272a614

Browse files
gplanchatgplanchat
committed
Updated README, added some usage explanations on the stack:init command and a FAQ
1 parent 0ce6f17 commit 272a614

File tree

9 files changed

+248
-29
lines changed

9 files changed

+248
-29
lines changed

‎README.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ This project aims at building your Docker stack for [OroCommerce](https://oroinc
77
88
* [Installation](#installation)
99
* [Usage](#usage)
10+
* [Frequently Asked Questions](#frequently-asked-questions)
1011
* [Supported versions and flavors](#supported-versions-and-flavours)
1112
* [OroPlatform](#oroplatform)
1213
* [OroCRM](#orocrm)
@@ -60,6 +61,10 @@ You can invoke the following command that will guess what you need and a wizard
6061

6162
`kloud stack:init`
6263

64+
Once the command is finished, you will have a file named `.env.dist` containing the required environment variables for the stack.
65+
This file has to be renamed to `.env` in order to be used by Docker Compose.
66+
The command have set some ports values for all services, you may wish to change them depending on your environment.
67+
6368
#### Available command line options
6469

6570
* Database engine selection
@@ -107,6 +112,193 @@ If you need to test if the images you are using are following every constraint y
107112

108113
`kloud image:test`
109114

115+
Frequently Asked Questions
116+
---
117+
118+
### I am having some warnings while launching `docker-compose up` for the first time
119+
120+
If you are having this sort of messages:
121+
122+
```
123+
WARNING: The MAILCATCHER_PORT variable is not set. Defaulting to a blank string.
124+
ERROR: The Compose file './docker-compose.yml' is invalid because:
125+
services.mail.ports contains an invalid type, it should be a number, or an object
126+
```
127+
128+
Those warnings and errors are due to missing environment variables, probably because you did
129+
not copy the `.env.dist` file to a `.env` file.
130+
131+
### What is the use of the `I_AM_DEVELOPER_DISABLE_INDEX_IP_CHECK` environment variable?
132+
133+
This environment variable is used to disable the IP check in the `public/index_dev.php` file.
134+
To benefit from this feature, you will need to apply the following patch:
135+
136+
```patch
137+
Index: public/index_dev.php
138+
IDEA additional info:
139+
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
140+
<+>UTF-8
141+
===================================================================
142+
--- public/index_dev.php
143+
+++ public/index_dev.php
144+
@@ -13,9 +13,12 @@
145+
146+
// This check prevents access to debug front controllers that are deployed by accident to production servers.
147+
// Feel free to remove this, extend it, or make something more sophisticated.
148+
-if (isset($_SERVER['HTTP_CLIENT_IP'])
149+
- || isset($_SERVER['HTTP_X_FORWARDED_FOR'])
150+
- || !in_array(@$_SERVER['REMOTE_ADDR'], array('127.0.0.1', 'fe80::1', '::1'))
151+
+if (!isset($_ENV['I_AM_DEVELOPER_DISABLE_INDEX_IP_CHECK'])
152+
+ && (
153+
+ isset($_SERVER['HTTP_CLIENT_IP'])
154+
+ || isset($_SERVER['HTTP_X_FORWARDED_FOR'])
155+
+ || !in_array(@$_SERVER['REMOTE_ADDR'], array('127.0.0.1', 'fe80::1', '::1'))
156+
+ )
157+
) {
158+
header('HTTP/1.0 403 Forbidden');
159+
exit('You are not allowed to access this file. Check '.basename(__FILE__).' for more information.');
160+
```
161+
162+
### How to access My application's frontend?
163+
164+
The application frontend can be accessed through the port defined in the `HTTP_PORT`
165+
environment variable value.
166+
167+
### How to configure the mailer in the `parameters.yml` file?
168+
169+
The parameters should be set as the following:
170+
171+
```yaml
172+
parameters:
173+
mailer_transport: smtp
174+
mailer_host: mail
175+
mailer_port: 1025
176+
mailer_encryption: null
177+
mailer_user: null
178+
mailer_password: null
179+
```
180+
181+
Notice that the `MAILER_PORT` variable is not used, as this port is the one from your
182+
computer's point of view, not a container's point of view in the stack.
183+
184+
### How to configure the websocket service in the `parameters.yml` file?
185+
186+
The parameters should be set as the following on Oro 4.1+:
187+
188+
```yaml
189+
parameters:
190+
websocket_bind_address: 0.0.0.0
191+
websocket_bind_port: 8080
192+
websocket_frontend_host: '*'
193+
websocket_frontend_port: '%env(WEBSOCKET_PORT)%'
194+
websocket_frontend_path: ''
195+
websocket_backend_host: '*'
196+
websocket_backend_port: '%env(WEBSOCKET_PORT)%'
197+
websocket_backend_path: ''
198+
websocket_backend_transport: tcp
199+
websocket_backend_ssl_context_options: { }
200+
```
201+
202+
Notice that the `WEBSOCKET_PORT` variable is not used for the `websocket_bind_port`, as this
203+
port is the one from your computer's point of view, not a container's point of view in the stack.
204+
205+
### How to configure the database service in the `parameters.yml` file?
206+
207+
The parameters should be set as the following on Oro 4.1+:
208+
209+
```yaml
210+
parameters:
211+
database_driver: pdo_pgsql
212+
database_host: sql
213+
database_port: null
214+
database_name: '%env(DATABASE_NAME)%'
215+
database_user: '%env(DATABASE_USER)%'
216+
database_password: '%env(DATABASE_PASS)%'
217+
database_driver_options: { }
218+
```
219+
220+
Notice that the `DATABASE_PORT` variable is not used, as this port is the one from your
221+
computer's point of view, not a container's point of view in the stack.
222+
223+
### How to configure the search engine service in the `parameters.yml` file?
224+
225+
The parameters should be set as the following:
226+
227+
```yaml
228+
parameters:
229+
search_engine_name: elastic_search
230+
search_engine_host: elasticsearch
231+
search_engine_port: null
232+
search_engine_index_prefix: oro_search
233+
search_engine_username: null
234+
search_engine_password: null
235+
search_engine_ssl_verification: null
236+
search_engine_ssl_cert: null
237+
search_engine_ssl_cert_password: null
238+
search_engine_ssl_key: null
239+
search_engine_ssl_key_password: null
240+
website_search_engine_index_prefix: oro_website_search
241+
```
242+
243+
Notice that the `ELASTICSEARCH_PORT` variable is not used, as this port is the one from your
244+
computer's point of view, not a container's point of view in the stack.
245+
246+
### How to configure the message queue service in the `parameters.yml` file?
247+
248+
The parameters should be set as the following:
249+
250+
```yaml
251+
parameters:
252+
message_queue_transport: amqp
253+
message_queue_transport_config:
254+
host: amqp
255+
port: '5672'
256+
user: '%env(RABBITMQ_USER)%'
257+
password: '%env(RABBITMQ_PASSWORD)%'
258+
vhost: /
259+
```
260+
261+
Notice that the `ELASTICSEARCH_PORT` variable is not used, as this port is the one from your
262+
computer's point of view, not a container's point of view in the stack.
263+
264+
### How to access to Mailcatcher's interface?
265+
266+
The Mailcatcher interface can be accessed through the port defined in the `MAILCATCHER_PORT`
267+
environment variable value.
268+
269+
### How to access RabbitMQ manager's interface?
270+
271+
The RabbitMQ manager interface can be accessed through the port defined in the `RABBITMQ_PORT`
272+
environment variable value.
273+
274+
### How to access Dejavu's interface for Elasticsearch?
275+
276+
The Dejavu interface can be accessed through the port defined in the `DEJAVU_PORT`
277+
environment variable value.
278+
279+
Additionnally, the `ELASTICSEARCH_PORT` variable should be defined in order to make
280+
Elasticsearch's API accessible from your computer.
281+
282+
### How to access Elasticsearch's API?
283+
284+
The Elasticsearch API can be accessed through the port defined in the `ELASTICSEARCH_PORT`
285+
environment variable value.
286+
287+
### How to access Kibana's interface?
288+
289+
The Kibana interface can be accessed through the port defined in the `KIBANA_PORT`
290+
environment variable value.
291+
292+
### How to access Redis service from your computer?
293+
294+
The Redis servcie can be accessed through the port defined in the `REDIS_PORT`
295+
environment variable value.
296+
297+
### How to access MySQL or PostgreSQL service from your computer?
298+
299+
The MySQL or PostgreSQL servcie can be accessed through the port defined in the `SQL_PORT`
300+
environment variable value.
301+
110302
Supported versions and flavours
111303
---
112304

‎src/Domain/Stack/Compose/Normalizer/ServiceDenormalizer.php‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,6 @@ public function denormalize($data, string $type, string $format = null, array $c
8888
} else if (isset($matches[2])) {
8989
$service->addEnvironmentVariables(new EnvironmentVariable(new Variable($matches[1]), $this->expressionParser->parse($matches[2])));
9090
} else {
91-
var_dump($matches);
9291
throw new \RuntimeException(strtr('Invalid environment variable format: "%value%".', ['%value%' => $value]));
9392
}
9493
} else if (!empty($value)) {

‎src/Domain/Stack/OroPlatform/Builder.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ public function __construct(string $stacksPath)
4343

4444
public function matches(DTO\Context $context): bool
4545
{
46-
return in_array($context->application, ['orocommerce', 'orocrm', 'oroplatform', 'marello'], true);
46+
return in_array($context->application, ['orocommerce', 'orocrm', 'oroplatform', 'marello', 'middleware'], true);
4747
}
4848

4949
public function build(DTO\Context $context): DTO\Stack

‎src/Domain/Stack/OroPlatform/Service/ElasticSearch.php‎

Lines changed: 21 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -31,11 +31,16 @@ public function matches(DTO\Context $context): bool
3131

3232
private function buildImageTag(DTO\Context $context)
3333
{
34-
if (Semver::satisfies($context->applicationVersion, '^3.0')) {
34+
if (in_array($context->application, ['oroplatform', 'orocrm', 'orocommerce']) && Semver::satisfies($context->applicationVersion, '^3.0')
35+
|| in_array($context->application, ['marello']) && Semver::satisfies($context->applicationVersion, '^2.0')
36+
) {
3537
return 'docker.elastic.co/elasticsearch/elasticsearch-oss:6.8.12';
3638
}
3739

38-
if (Semver::satisfies($context->applicationVersion, '^4.0')) {
40+
if (in_array($context->application, ['oroplatform', 'orocrm', 'orocommerce']) && Semver::satisfies($context->applicationVersion, '^4.0')
41+
|| in_array($context->application, ['marello']) && Semver::satisfies($context->applicationVersion, '^3.0')
42+
|| in_array($context->application, ['middleware']) && Semver::satisfies($context->applicationVersion, '^1.0')
43+
) {
3944
return 'docker.elastic.co/elasticsearch/elasticsearch-oss:7.9.1';
4045
}
4146

@@ -57,11 +62,7 @@ public function build(DTO\Stack $stack, DTO\Context $context): DTO\Stack
5762
new VolumeMapping('elasticsearch', '/usr/share/elasticsearch/data'),
5863
new VolumeMapping('./.docker/elasticsearch/elasticsearch.yml', '/usr/share/elasticsearch/config/elasticsearch.yml'),
5964
)
60-
->setRestartOnFailure(),
61-
(new Service('dejavu', 'appbaseio/dejavu'))
62-
->addPorts(
63-
new PortMapping(new Variable('DEJAVU_PORT'), 1358)
64-
)
65+
->setRestartOnFailure()
6566
)
6667
->addVolumes(
6768
new Volume('elasticsearch', ['driver' => 'local'])
@@ -98,6 +99,19 @@ public function build(DTO\Stack $stack, DTO\Context $context): DTO\Stack
9899
new EnvironmentVariable(new Variable('APPLICATION_DOMAIN')),
99100
);
100101

102+
if ($context->withDejavu === true) {
103+
$stack->addServices(
104+
(new Service('dejavu', 'appbaseio/dejavu'))
105+
->addPorts(
106+
new PortMapping(new Variable('DEJAVU_PORT'), 1358)
107+
)
108+
);
109+
110+
$stack->addEnvironmentVariables(
111+
new EnvironmentVariable(new Variable('DEJAVU_PORT')),
112+
);
113+
}
114+
101115
return $stack;
102116
}
103117
}

‎src/Domain/Stack/OroPlatform/Service/Kibana.php‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,11 +28,16 @@ public function matches(DTO\Context $context): bool
2828

2929
private function buildImageTag(DTO\Context $context)
3030
{
31-
if (Semver::satisfies($context->applicationVersion, '^3.0')) {
31+
if (in_array($context->application, ['oroplatform', 'orocrm', 'orocommerce']) && Semver::satisfies($context->applicationVersion, '^3.0')
32+
|| in_array($context->application, ['marello']) && Semver::satisfies($context->applicationVersion, '^2.0')
33+
) {
3234
return 'docker.elastic.co/kibana/kibana:6.8.11';
3335
}
3436

35-
if (Semver::satisfies($context->applicationVersion, '^4.0')) {
37+
if (in_array($context->application, ['oroplatform', 'orocrm', 'orocommerce']) && Semver::satisfies($context->applicationVersion, '^4.0')
38+
|| in_array($context->application, ['marello']) && Semver::satisfies($context->applicationVersion, '^3.0')
39+
|| in_array($context->application, ['middleware']) && Semver::satisfies($context->applicationVersion, '^1.0')
40+
) {
3641
return 'docker.elastic.co/kibana/kibana:7.8.1';
3742
}
3843

‎src/Domain/Stack/OroPlatform/Service/Logstash.php‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,11 +24,16 @@ public function matches(DTO\Context $context): bool
2424

2525
private function buildImageTag(DTO\Context $context)
2626
{
27-
if (Semver::satisfies($context->applicationVersion, '^3.0')) {
27+
if (in_array($context->application, ['oroplatform', 'orocrm', 'orocommerce']) && Semver::satisfies($context->applicationVersion, '^3.0')
28+
|| in_array($context->application, ['marello']) && Semver::satisfies($context->applicationVersion, '^2.0')
29+
) {
2830
return 'docker.elastic.co/logstash/logstash:6.8.11';
2931
}
3032

31-
if (Semver::satisfies($context->applicationVersion, '^4.0')) {
33+
if (in_array($context->application, ['oroplatform', 'orocrm', 'orocommerce']) && Semver::satisfies($context->applicationVersion, '^4.0')
34+
|| in_array($context->application, ['marello']) && Semver::satisfies($context->applicationVersion, '^3.0')
35+
|| in_array($context->application, ['middleware']) && Semver::satisfies($context->applicationVersion, '^1.0')
36+
) {
3237
return 'docker.elastic.co/logstash/logstash:7.8.1';
3338
}
3439

‎src/Domain/Stack/OroPlatform/Service/MySQL.php‎

Lines changed: 9 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,12 @@
33
namespace Kiboko\Cloud\Domain\Stack\OroPlatform\Service;
44

55
use Kiboko\Cloud\Domain\Stack\Compose\EnvironmentVariable;
6-
use Kiboko\Cloud\Domain\Stack\Compose\Label;
76
use Kiboko\Cloud\Domain\Stack\Compose\PortMapping;
87
use Kiboko\Cloud\Domain\Stack\Compose\Service;
98
use Kiboko\Cloud\Domain\Stack\Compose\Variable;
109
use Kiboko\Cloud\Domain\Stack\Compose\Volume;
1110
use Kiboko\Cloud\Domain\Stack\Compose\VolumeMapping;
1211
use Kiboko\Cloud\Domain\Stack\DTO;
13-
use Kiboko\Cloud\Domain\Stack\Resource;
1412
use Kiboko\Cloud\Domain\Stack\ServiceBuilderInterface;
1513

1614
final class MySQL implements ServiceBuilderInterface
@@ -35,10 +33,10 @@ public function build(DTO\Stack $stack, DTO\Context $context): DTO\Stack
3533
new PortMapping(new Variable('SQL_PORT'), 3306),
3634
)
3735
->addEnvironmentVariables(
38-
new EnvironmentVariable(new Variable('MYSQL_ROOT_PASSWORD'), new Variable('SQL_ROOT_PASSWORD')),
39-
new EnvironmentVariable(new Variable('MYSQL_DATABASE'), new Variable('SQL_DATABASE')),
40-
new EnvironmentVariable(new Variable('MYSQL_USER'), new Variable('SQL_USER')),
41-
new EnvironmentVariable(new Variable('MYSQL_PASSWORD'), new Variable('SQL_PASSWORD')),
36+
new EnvironmentVariable(new Variable('MYSQL_ROOT_PASSWORD'), new Variable('DATABASE_ROOT_PASSWORD')),
37+
new EnvironmentVariable(new Variable('MYSQL_DATABASE'), new Variable('DATABASE_NAME')),
38+
new EnvironmentVariable(new Variable('MYSQL_USER'), new Variable('DATABASE_USER')),
39+
new EnvironmentVariable(new Variable('MYSQL_PASSWORD'), new Variable('DATABASE_PASSWORD')),
4240
)
4341
->addVolumeMappings(
4442
new VolumeMapping('database', '/var/lib/mysql'),
@@ -52,11 +50,11 @@ public function build(DTO\Stack $stack, DTO\Context $context): DTO\Stack
5250
;
5351

5452
$stack->addEnvironmentVariables(
55-
new EnvironmentVariable(new Variable('SQL_ROOT_PASSWORD')),
56-
new EnvironmentVariable(new Variable('SQL_DATABASE')),
57-
new EnvironmentVariable(new Variable('SQL_USER')),
58-
new EnvironmentVariable(new Variable('SQL_PASSWORD')),
59-
new EnvironmentVariable(new Variable('SQL_PORT')),
53+
new EnvironmentVariable(new Variable('DATABASE_ROOT_PASSWORD'), 'password'),
54+
new EnvironmentVariable(new Variable('DATABASE_NAME')),
55+
new EnvironmentVariable(new Variable('DATABASE_USER')),
56+
new EnvironmentVariable(new Variable('DATABASE_PASSWORD'), 'password'),
57+
new EnvironmentVariable(new Variable('DATABASE_PORT')),
6058
);
6159

6260
return $stack;

‎src/Domain/Stack/OroPlatform/Service/PostgreSQL.php‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -34,10 +34,10 @@ public function build(DTO\Stack $stack, DTO\Context $context): DTO\Stack
3434
new PortMapping(new Variable('SQL_PORT'), 5432),
3535
)
3636
->addEnvironmentVariables(
37-
new EnvironmentVariable(new Variable('POSTGRES_ROOT_PASSWORD'), new Variable('SQL_ROOT_PASSWORD')),
38-
new EnvironmentVariable(new Variable('POSTGRES_DB'), new Variable('SQL_DATABASE')),
39-
new EnvironmentVariable(new Variable('POSTGRES_USER'), new Variable('SQL_USER')),
40-
new EnvironmentVariable(new Variable('POSTGRES_PASSWORD'), new Variable('SQL_PASSWORD')),
37+
new EnvironmentVariable(new Variable('POSTGRES_ROOT_PASSWORD'), new Variable('DATABASE_ROOT_PASSWORD')),
38+
new EnvironmentVariable(new Variable('POSTGRES_DB'), new Variable('DATABASE_NAME')),
39+
new EnvironmentVariable(new Variable('POSTGRES_USER'), new Variable('DATABASE_USER')),
40+
new EnvironmentVariable(new Variable('POSTGRES_PASSWORD'), new Variable('DATABASE_PASSWORD')),
4141
)
4242
->addVolumeMappings(
4343
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
5858
);
5959

6060
$stack->addEnvironmentVariables(
61-
new EnvironmentVariable(new Variable('SQL_PORT')),
61+
new EnvironmentVariable(new Variable('DATABASE_ROOT_PASSWORD'), 'password'),
62+
new EnvironmentVariable(new Variable('DATABASE_NAME')),
63+
new EnvironmentVariable(new Variable('DATABASE_USER')),
64+
new EnvironmentVariable(new Variable('DATABASE_PASSWORD'), 'password'),
65+
new EnvironmentVariable(new Variable('DATABASE_PORT')),
6266
);
6367

6468
return $stack;

0 commit comments

Comments
 (0)