General setup¶

For local development, we are using Docker and Docker Compose. The following steps will help you set up the project on your local machine.

Prerequisites¶

composer
docker
Access to SynQup's GitLab repository

Upgrading MongoDB¶

This is only relevant if you’re upgrading an old development environment. You only need to perform these steps if you have local data you want to migrate. Otherwise, running

rm -rf docker-assets/mongo/data/*

should be totally sufficient. You can then upgrade to the latest version directly (which should be the repo state anyway), as the data files and directories will be recreated with the new schema.

If you were using an older version of MongoDB before updating, change the version of the Mongo container image to the latest version. Spin up the project and connect to MongoDB. Run the following command:

db.adminCommand({setFeatureCompatibilityVersion: "7.0"})

Replace 6.0 with the version before the current version.

Afterwards, stop your containers and change the image to the latest version. Start up the containers again: you should now have a running MongoDB container with your data.

After a few days, you can set the compatibility version to the latest version.

Create Project Directory¶

For now you can simply create the root-synqup directory:

synqup
└───synqup

For easier module development we will create a separate content root for the modules directory. That's why we will have a directory structure like this after completing this guide:

synqup
└───synqup  
│   └───src
│   └───composer.json
│   └───...
└───modules
└───module-1
└───module-2
└───...

If you are working with local repositories, you will need this symlink. It is necessary for the SynQup Message inspection.

if [ -d ../modules ]; then ln -s ../modules synqup-packages; fi

or simply

ln -s ../modules synqup-packages

Clone synQup Repository¶

Go into the synqup/ directory and clone the synqup repository: git clone git@gitlab.com:flowberry1/flowberry.git synqup

You can now open the project in PhpStorm by opening the synqup/synqup directory.

Optional: Prepare Multi-Environment-Setup¶

This step is optional. But if you are setting up multiple synQup-instances you might want to rename all containers as well as their network. You have to change the following values of the docker-compose.yml:

services.redis.container_name
services.web.container_name
services.rabbitmq.container_name
services.mysql.container_name
services.mongo.container_name
networks.backend.name
networks.backend.ipam.config.subnet -> switch subnet to avoid ip-collisions

In order to make multiple synqup-instances runnable at the same time you have to update the ports as well:

services.web.ports
services.rabbitmq.ports
services.mysql.ports
services.mongo.ports
services.mailcatcher.ports
networks.backend.name
networks.backend.ipam.config.subnet -> switch ip address

For example, change the ports of the web container like this:

services:  
web:  
ports:  
- "81:80"  
- "444:443"

Execute Install Script¶

Now run ./bin/scripts/install to build the images, bring up the containers and prepare the environment. Your containers should be up and running now.

You may run into several error-messages like this:

Failed loading /usr/local/lib/php/extensions/no-debug-non-zts-20220829/xdebug.so:  /usr/local/lib/php/extensions/no-debug-non-zts-20220829/xdebug.so: cannot open shared object file: No such file or directory

This is fine for now, we will take care of that while setting up Xdebug.

Prepare Composer / Tokens¶

Perform these steps if you want to install synqup-modules via composer from the synqup-repositories:

Generate an access token with scope "read registry + read_api" in Click User Icon -> Edit Profile -> Access Tokens
run the following commands in your synqup-apache container:

composer config repositories.14106690 composer https://gitlab.com/api/v4/group/14106690/-/packages/composer/
composer config repositories.78432076 composer https://gitlab.com/api/v4/group/78432076/-/packages/composer/
composer config gitlab-token.gitlab.com %YOUR_ACCESS_TOKEN%

Notes:

14106690 is the group-id of the synqup-modules group https://gitlab.com/groups/flowberry1/synqup-modules
78432076 is the group-id of the synqup-data model group https://gitlab.com/groups/flowberry1/data-model/

Your composer.json should contain the following repositories:

"repositories": {
  "78432076": {
    "type": "composer",
    "url": "https://gitlab.com/api/v4/group/78432076/-/packages/composer/"
  },
  "14106690": {
    "type": "composer",
    "url": "https://gitlab.com/api/v4/group/14106690/-/packages/composer/"
  }
}

Verify that you’re able to require packages by installing the data model: composer req synqup/commerce-bundle:^4 synqup/common-bundle:^4

Confirm that the data model was installed correctly (you can find it in vendor/synqup/commerce-bundle and vendor/synqup/common-bundle) and is present in config/bundles.php.

If not, run composer sync-recipes -v (but it should just work out of the box for all official synQup modules - other modules may not follow Symfony’s bundle spec as closely!)

This will install the modules in the vendor directory. If you want to develop modules locally you should read the following sections of this guide. If you want to make changes to the data model locally, you should remove these packages now (composer rm synqup/commerce-bundle)

Configure Module Directory¶

Now we are going to create a separate directory for our modules. This directory is then configured as volume of the apache-container. This step must be performed once per project.

Create directory¶

The modules are stored in a separate directory located one level above the synqup folder. We want to have the following directory structure:

synqup
└───synqup  
│   └───src
│   └───composer.jsob
│   └───...
└───modules
└───module-1
└───module-2
└───...

Create directory: mkdir ../modules
Find and copy realpath: realpath ../modules
- e.g. /home/synqup/projects/synqup/modules

Configure Volume¶

Now it is necessary to configure a volume according to the following pattern: {absolute path}/:/var/www/{name of module folder}.

In our case, the file docker-compose.yml is edited as follows:

web:    
container_name: "synQup-apache"    
networks:    
-  ...  
depends_on:    - ...    
build:    
...  
volumes:    - ...
- /home/elio/projects/synqup-projects/synqup/modules/:/var/www/modules

Rebuild container¶

docker compose up -d

Info

The apache-container is recreated in this step

Configure PHPStorm¶

In the settings of PHPStorm a new so called Content Root has to be added: File -> Settings -> Directories -> Add Content Root -> Select modules directory -> Apply. Now both folders (release and modules) are visible in PHPStorm.

Verify Configuration¶

To make sure everything is wired up correctly, we can simply create a file test.txt in the modules directory. Now check if that file is available in the container: docker exec -i synqup-prod-apache ls /var/www/modules. This should display your file.

Local Module Development¶

Cloning existing Modules¶

Clone Repository¶

Make sure you completed the preparation steps
Go into the modules directory and clone your repository
Optional: you can validate your configuration by checking docker exec -i synqup-prod-apache ls /var/www/modules. This should display your cloned repository.

Register Modules in composer.json¶

In order to install modules from your local directory, we have to add the following to the composer.json above our existing repositories:

"repositories": {
  "modules": {
    "type": "path",
    "url": "/var/www/modules/*"
  },
  "78432076": {
    "type": "composer",
    "url": "https://gitlab.com/api/v4/group/78432076/-/packages/composer/"
  },
  "14106690": {
    "type": "composer",
    "url": "https://gitlab.com/api/v4/group/14106690/-/packages/composer/"
  }
}

It is also possible to register modules/repositories individually, but it is recommended to use the way shown above.

However, you can register a repository-path via composer-cli like this (with the shopware-6 module as example):

docker exec -i synqup-apache composer config repositories.shopware6Local path /var/www/modules/shopware-6

Run this command in your apache container.

This commands adds the following entry to the composer.json file:

"shopware6Local": {  
  "type": "path",  
  "url": "/var/www/modules/shopware-6"  
}

You can also add the repository to your composer.json file manually.

Install Module¶

Now install the module: composer req your/module-name

Because we added the repository path to our composer.json, the module is installed from the local directory. If everything is configured correctly you will see the following output:

Installing synqup/shopware-6 (x.x.x): Symlinking from /var/www/modules/shopware-6

A symlink is created, so the module in the container is updated on every change of the local repository.

Add Git-Repository to PHPStorm¶

Go to File -> Settings -> Version Control -> Directory Mappings -> Add to add the git-repository to PHPStorm. You have to choose the module directory and "Git" as VCS.

Creating New Modules (Work in Progress)¶

There are many ways how this could be approached. Feel free to add them to this documentation.

Module Make Command¶

Create the first module using the module:make command - feel free to ask for help here, as getting the first package installed and working posed a challenge in the past for most of our devs

Via new gitlab-project¶

Create new gitlab project
add composer json, add gitlab ci
create directory for module in your modules directory
git clone NAME . to clone in current directory
create module template
add composer repo ro composer.json

XDEBUG¶

Fix XDebug (Optional)¶

Sometimes you may experience this error:

Failed loading /usr/local/lib/php/extensions/no-debug-non-zts-20200930/xdebug.so:  /usr/local/lib/php/extensions/no-debug-non-zts-20200930/xdebug.so: cannot open shared object file: No such file or directory

Then do the following in the apache container:

go into file /usr/local/lib/php/extensions
ls -la - you will find another directory, e.g. no-debug-non-zts-20210902
Edit the file nano /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
Fix path in that file and add the correct directory from above

Activate Or Deactivate¶

Edit the file nano /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini There you can (un)comment xdebug

Prepare PHPStorm¶

Edit PHPStorm settings

PHP->Debug->DBGp Proxy
- IDE KEY = PHPSTORM
- Port = 9003
PHP->Servers
- Name: Docker
- Host: localhost
- Port: 80
- use path mappings
  - synqup to “/var/www/html”
  - modules to /”var/www/modules”

Test XDebug Configuration¶

You can use the CreateUserCommand to test if your xdebug configuration is working. Set a breakpoint in that command and execute it:

export PHP_IDE_CONFIG=serverName=Docker && php -dxdebug.mode=debug -dxdebug.client_host=172.17.0.1 -dxdebug.client_port=9003 -dxdebug.start_with_request=yes bin/console synqup:user:create

If this address is not working for you, you can try 192.168.99.1.

Note for windows / WSL / MAC users: If you are experiencing a could not connect to debugging client error, you have to use host.docker.internal and not the ip-address.

Xdebug-Troubleshooting¶

If you suffer from dying php-processes if xdebug is active, you should consider to downgrade your xdebug version. The problem occured in version 3.3.5, but does not seem to happen in version 3.1.5.

pecl uninstall xdebug
pecl install xdebug-3.1.5
echo "zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20210902/xdebug.so" > /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

PhpStorm Data Sources (Work in Progress)¶

MySQL Integration¶

If you want to use the PHPStorm MySQL integration, you have to add a new data-source:

Host: localhost
Port: The port you have configured in your mysql.portskey in the docker-compose.yml
User and Password are specified in the .env file (DATABASE_URL), should be root/root if you did not change anything

MongoDb Integration¶

You can do the same thing for the mongo-db:

Host: localhost
Port: The port specified in the mongo.ports key in the docker-compose.yml
User and password are specified in the .env, should be empty in both cases

Supervisor config / Multiworker debugging¶

The file supervisor.conf must be created in /bin/scripts/supervisor.conf:

[supervisord]  
[program:flowberry-worker]  
process_name=%(program_name)s_%(process_num)02d  
command=php bin/console messenger:consume pm job_high job_mid job_low --limit=15  
#command=php -dxdebug.mode=debug -dxdebug.client_host=192.168.99.1 -dxdebug.client_port=9003 -dxdebug.start_with_request=yes bin/console messenger:consume pm job_high job_mid job_low --limit=15  
autostart=true  
autorestart=true  
stopasgroup=true  
killasgroup=true  
numprocs=4
redirect_stderr=true  
stopwaitsecs=3600  
stdout_logfile=/dev/fd/1  
stdout_logfile_maxbytes=0

If you want to run the workers you can simple run this command: supervisord -c bin/scripts/supervisor.conf -n If you want to use xdebug while running multiple workers, you have to perform the following steps:

Execute in apache-container export PHP_IDE_CONFIG=serverName=Docker
Replace command in config from line 4 with the command in line 5: php -dxdebug.mode=debug -dxdebug.client_host=192.168.99.1 -dxdebug.client_port=9003 -dxdebug.start_with_request=yes bin/console messenger:consume pm job_high job_mid job_low --limit=20
Start worker with: export PHP_IDE_CONFIG=serverName=Docker && supervisord -c bin/scripts/supervisor.conf -

Shopware 6 Dev Toolkit¶

git clone git@gitlab.com:flowberry1/synqup-modules/shopware-6-modules/shopware-6.git
git clone git@gitlab.com:flowberry1/synqup-modules/shopware-6-modules/shopware-6-api-client.git
git clone git@gitlab.com:flowberry1/synqup-modules/shopware-6-modules/shopware-6-mapping-extension.git
git clone git@gitlab.com:flowberry1/synqup-modules/mapping-toolkit.git
git clone git@gitlab.com:flowberry1/data-model/common-bundle.git
git clone git@gitlab.com:flowberry1/data-model/commerce-bundle.git

composer require synqup/common-bundle
composer require synqup/commerce-bundle
composer require synqup/mapping-toolkit
composer require synqup/shopware-6-admin-api-client
composer require synqup/shopware-6
composer require synqup/shopware-6-mapping-extension

User interface¶

Your user also needs to have a JWT token. You can create it in the docker backend image:

docker ps
docker exec -it [first-chars-of the-container-id] bash

First, type docker ps to find all containers. Then paste this placeholder to the second command to log in. Then create a JWT token for your user.

php bin/console lexik:jwt:generate-keypair
php bin/console lexik:jwt:generate-token [your e-mail address]

Then clone the user-interface project:

git clone git@gitlab.com:flowberry1/user-interface.git

cd user-interface
./start-against-local.sh