kenaug74/Sylius
1
0
Fork 0
mirror of https://github.com/Sylius/Sylius.git synced 2026-07-14 09:02:12 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

Finished writing Sylius Cloud cookbook

Browse source
This commit is contained in:
Marcin Kukliński 2024-04-03 21:45:48 +02:00 • committed by Magdalena Sadowska
parent 4d55bf7c0d
commit 02f4fcc1c7
16 changed files with 745 additions and 328 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

0
docs/_images/cookbook/platform-sh-cloud/create-from-scratch-default-environment.png → docs/_images/cookbook/sylius-cloud/create-from-scratch-default-environment.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 65 KiB

After

Width:  |  Height:  |  Size: 65 KiB

0
docs/_images/cookbook/platform-sh-cloud/create-from-scratch.png → docs/_images/cookbook/sylius-cloud/create-from-scratch.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 60 KiB

After

Width:  |  Height:  |  Size: 60 KiB

31
docs/cookbook/index.rst
View file

@ -3,19 +3,6 @@ The Cookbook
The Sylius Cookbook is a collection of solution articles helping you with some specific, narrow problems.
<<<<<<< Updated upstream
=======
CLI
---
.. toctree::
:hidden:
cli/handle-multiple-channels-in-cli
.. include:: /cookbook/cli/map.rst.inc
>>>>>>> Stashed changes
Entities
--------
@ -196,16 +183,18 @@ API
.. include:: /cookbook/api/map.rst.inc
Sylius Cloud on Platform.sh
---
Sylius Cloud
------------
.. toctree::
:hidden:
platform-sh-cloud/introduction-to-sylius-cloud-on-platform-sh
platform-sh-cloud/basic-project-setup
platform-sh-cloud/sylius-plus
platform-sh-cloud/environment-configuration
platform-sh-cloud/cloud-management-basics
sylius-cloud/introduction-to-sylius-cloud
sylius-cloud/dictionary
sylius-cloud/basic-project-setup
sylius-cloud/sylius-plus
sylius-cloud/environment-configuration
sylius-cloud/cloud-management-basics
sylius-cloud/troubleshooting
.. include:: /cookbook/platform-sh-cloud/map.rst.inc
.. include:: /cookbook/sylius-cloud/map.rst.inc

142
docs/cookbook/platform-sh-cloud/basic-project-setup.rst
View file

@ -1,142 +0,0 @@
Basic project setup
===================
Sylius is a typical Symfony application, so all the steps below can be used for a clean Symfony application as well.
Prerequisites
-------------
To work with Sylius Cloud on Platform.sh you'll need the `platform` command on your computer. To install it, please run the script:
.. code-block:: bash
curl -fsSL https://raw.githubusercontent.com/platformsh/cli/main/installer.sh | bash
There are several methods of installing the `platform` application in your machine. To see them, please visit the `Platform.sh documentation <https://docs.platform.sh/administration/cli.html#1-install>`_
Pushing Sylius to Platform.sh
-----------------------------
Let's assume you're extending the Sylius-Standard in version including the Platform.sh configuration.
First step you need to do is to create a Platform.sh project. To do it, please log in to your Platform.sh account and click "Create a new project" button from the Platform.sh dashboard.
Note down the project ID and region as you'll need them later. For the convenience the environment name should be same as your main application branch. Let's say it's `main`.
The next thing you need to do is to connect your git remote with your Platform.sh project:
.. code-block:: bash
platform project:set-remote <PROJECT_ID>
git remote add platform <PROJECT_ID>>@git.<REGION>.platform.sh:<PROJECT_ID>.git
After this step all you need to do is to commit and push your code into the `platform` remote:
.. code-block:: bash
git add .
git commit -m "Initial Sylius Cloud on Platform.sh configuration"
git push platform main
This will trigger a deployment to Platform.sh. The Platform.sh CLI will automatically detect your Sylius application and set up the environment accordingly.
Once the deployment is complete, your Symfony application will be accessible via a unique URL provided by Platform.sh with format described below:
.. code-block:: bash
<ENVIRONMENT_NAME>-<PROJECT_ID>.<REGION>.platformsh.site
That's it! You've successfully pushed your Sylius application to Platform.sh. You can now continue to develop, test, and manage your application directly from the Platform.sh dashboard or CLI.
Database and other services configuration on Platform.sh
--------------------------------------------------------
In Platform.sh, there is a special `PLATFORM_RELATIONSHIPS` environment variable that contains connection information for services defined in the `.platform.app.yaml` file.
This variable is commonly used in Symfony applications like Sylius, particularly with Doctrine, to automatically configure database connections based on the services provided by Platform.sh.
In your `.platform.app.yaml` and `.platform/services.yaml` files you define services such as databases, caches, or search engines. These services are provisioned by Platform.sh and are accessible to your application as environment variables.
The `PLATFORM_RELATIONSHIPS` environment variable contains a JSON-encoded string representing the relationships between your application and the services provisioned by Platform.sh. Each service is represented as an array containing connection details such as host, port, username, password, and database name.
In Sylius you can configure database connections using the `PLATFORM_RELATIONSHIPS` variable. Instead of hardcoding connection parameters in the Symfony configuration files, you can dynamically retrieve them from the `PLATFORM_RELATIONSHIPS` variable at runtime.
Example Doctrine configuration:
.. code-block:: yaml
doctrine:
dbal:
driver: 'pdo_mysql'
host: '%env(resolve:PLATFORM_RELATIONSHIPS:mysql:host)%'
port: '%env(resolve:PLATFORM_RELATIONSHIPS:mysql:port)%'
dbname: '%env(resolve:PLATFORM_RELATIONSHIPS:mysql:database)%'
user: '%env(resolve:PLATFORM_RELATIONSHIPS:mysql:username)%'
password: '%env(resolve:PLATFORM_RELATIONSHIPS:mysql:password)%'
To summarize, by using the `PLATFORM_RELATIONSHIPS` environment variable with Doctrine in Symfony applications deployed on Platform.sh, you can ensure that database connections are automatically configured and managed based on the services provisioned by the platform, leading to more flexible and portable application deployments.
Setting up cron configuration
-----------------------------
Setting up cron jobs (scheduled tasks) in Sylius Cloud on Platform.sh involves defining them in the `.platform.app.yaml` file of your Sylius project.
Here's how you can set up cron jobs:
.. code-block:: yaml
hooks:
cron:
# Run the `php bin/console my:command` command every day at 2:00 AM.
- name: daily-cron
schedule: '0 2 * * *'
command: 'php bin/console my:command'
To fully integrate your Sylius application with Platform.sh infrastructure, you need to configure at least three cron commands:
.. code-block:: bash
bin/console sylius:cancel-unpaid-orders
bin/console sylius:promotion:generate-coupons
bin/console sylius:remove-expired-carts
So the hooks section may look like below:
.. code-block:: yaml
hooks:
cron:
- name: cancel-unpaid-orders
schedule: '0 2 * * *'
command: 'php bin/console sylius:cancel-unpaid-orders'
- name: generate-promotion-coupons
schedule: '0 2 * * *'
command: 'php bin/console sylius:promotion:generate-coupons'
- name: remove-expired-carts
schedule: '0 2 * * *'
command: 'php bin/console sylius:remove-expired-carts'
The frequency of running these commands depends on your business requirements.
Verify the cron jobs
--------------------
Once your changes are deployed, Platform.sh will automatically set up the cron jobs according to the schedule you defined.
You can verify that the cron jobs are set up correctly by accessing the environment's SSH console and checking the crontab:
.. code-block:: bash
platform ssh
crontab -l
Configuring Symfony Messenger workers
-------------------------------------
Running workers on Sylius Cloud on Platform.sh involves setting up background processes to handle tasks asynchronously, such as queue processing,
background jobs, or event-driven tasks. Workers are typically configured using the `.platform.app.yaml` file.
To fully integrate with Sylius application with Platform.sh, you'll need to configure the worker for catalog promotions:
.. code-block:: bash
bin/console messenger:consume main main_failed catalog_promotion_removal catalog_promotion_removal_failed
The full documentation regarding Platform.sh workers you can find in the `Platform.sh documentation <https://docs.platform.sh/create-apps/workers.html>`_
The workers section for Sylius project may look like the one below:
.. code-block:: yaml
workers:
catalog_promotions:
commands:
start: |
bin/console messenger:consume main main_failed catalog_promotion_removal catalog_promotion_removal_failed
The important information from `Platform.sh documentation<https://docs.platform.sh/create-apps/app-reference.html#workers>`_ is that crashed workers are automatically restarted.

13
docs/cookbook/platform-sh-cloud/cloud-management-basics.rst
View file

@ -1,13 +0,0 @@
Cloud management basics
=======================
Choosing an environment plan
----------------------------
Custom domain configuration
---------------------------
https://docs.platform.sh/domains/steps.html
SSH access
----------

25
docs/cookbook/platform-sh-cloud/environment-configuration.rst
View file

@ -1,25 +0,0 @@
PHP Configuration
=================
PHP-FPM configuration
---------------------
https://docs.platform.sh/languages/php/fpm.html
Enabling Opcache preloading option
----------------------------------
https://docs.platform.sh/languages/php/tuning.html
Configuring php.ini file
------------------------
https://docs.platform.sh/languages/php.html#customize-php-settings
SMTP configuration
------------------
https://docs.platform.sh/development/email.html
Environment variables configuration
-----------------------------------
XDebug configuration
--------------------
https://docs.platform.sh/languages/php/xdebug.html

116
docs/cookbook/platform-sh-cloud/introduction-to-sylius-cloud-on-platform-sh.rst
View file

@ -1,116 +0,0 @@
Introduction to Sylius Cloud on Platform.sh
===========================================
Sylius Cloud on Platform.sh is a way of efficient and scalable Sylius hosting. With Sylius Cloud you get the ability of
deploying and managing your Sylius platform with minimal DevOps knowledge. All you need to do is to configure your project
dependencies, push the application and maintain it.
What is Sylius Cloud
--------------------
Sylius Cloud is a solution based on Platform.sh - a modern PaaS (Platform-as-a-Service) which gives you ability of creating
and managing any kind of environment, starting from development, through stagings, pre-productions, up to production environment.
It's based on its own containers architecture, with gives you all that is good of performance, security and scalability at once.
Using Platform.sh as a base of Sylius Cloud adds a possibility of hosting your Sylius platform on one of the following cloud service providers:
* Amazon Web Services (AWS)
* Google Cloud Platform (GCP)
* Microsoft Azure
* DigitalOcean
With Sylius Cloud you're able to choose the service provider, server characteristics (number of CPUs, memory amount, disk size etc.)
with a clear information about costs. It's a good solution both for small, medium and huge web stores with a big traffic and number of orders.
Main Platform.sh concepts:
* Git-driven architecture - helps with setting up new environments with a simple pushing a new git branch to the specified remote. It makes you ability to create new environments fast.
* Infrastructure as a code - all you need to do is to write your application and a few Yaml files to create your environment. So simple and so powerful.
* Multi-services and multi-apps - it doesn't matter your application is monolith- or microservice-based architecture. It doesn't matter how much different external services you need (MySQL, PostgreSQL, ElasticSearch, Redis etc.) - it just works good in all cases.
Platform.sh configuration in Sylius
-----------------------------------
All the infrastructure configuration files are placed in `Sylius-Standard <https://github.com/Sylius/Sylius-Standard>`_ project. It means you'll get it when running the command:
.. code-block:: bash
composer create-project sylius/sylius-standard acme
The paths you should be interested in are:
* `.platform.app.yaml` - This file is used to define the configuration of the application itself. It specifies how the application should be built, what runtime to use, which commands to run on deployment, etc. It also includes information such as the type of application, language runtime, build and deploy hooks, and more.
* `.env.platform.dist` - The environment file automatically used by the application during the build process.
* `.platform/routes.yaml` - This file defines the routes and how traffic is routed to the application. It specifies the incoming URLs and how they should be directed to the appropriate services or applications. Routes can be configured to handle different paths, domains, or other conditions.
* `.platform/services.yaml` - This file is used to define additional services or dependencies required by the application. It allows defining various types of services such as databases, caches, search engines, etc., along with their configuration. Services defined in this file are automatically provisioned and integrated with the application environment.
Creating a new project and environment
--------------------------------------
Since Sylius Cloud is based on Platform.sh, every new environment needs to be created in the Platform.sh panel or by using the `platform` command.
But first before creating an environment you need to create the project. This can be done only in Platform.sh panel. When you're creating a new project,
to use the Sylius Cloud potential, please choose the "Create from scratch" option, as selected on the screenshot below:
.. image:: ../../_images/cookbook/platform-sh-cloud/create-from-scratch.png
:align: center
:scale: 50%
During creating a new project you'll automatically create a new environment, which is connected to your git branch (please read the information on screenshot below):
.. image:: ../../_images/cookbook/platform-sh-cloud/create-from-scratch-default-environment.png
:align: center
:scale: 50%
When you've created the project, you're ready to create new environments. Assuming you're a developer, it will be more convenient for you to use the `platform` command:
.. code-block:: bash
platform environment:create
This command will prompt you to specify various options for the new environment, such as its name, type, parent environment, and more. Follow the prompts to configure the new environment according to your requirements.
Once the environment is created, you can deploy your application to it using the following command:
.. code-block:: bash
git push platform <BRANCH_NAME>:<ENVIRONMENT_NAME>
Replace <branch_name> with the name of the Git branch you want to deploy, and <ENVIRONMENT_NAME> with the name of the environment you just created.
After the deployment is complete, you can access your new environment using its unique URL, which typically follows the format:
.. code-block:: bash
<ENVIRONMENT_NAME>-<PROJECT_ID>.<REGION>.platformsh.site
That's it! You've now created a new environment in your Platform.sh project and deployed your application to it. You can repeat these steps to create additional environments as needed for development, testing, or other purposes.
Developing application with Sylius Cloud on Platform.sh
-------------------------------------------------------
As described in previous section, you're able to create new environments by using the `platform` command. Working with multiple environments is a very good point of development. It gives you a lot of advantages, like:
* You're able to create an environment for all your features and test how they behave on the real infrastructure.
* Your team mates test the features independently of other developers. They're able to create their own environment and work there.
* When you're using Git Flow, you're able to test how your features integrate with other functionalities, i.e., with other microservices.
* You and your team mates don't need to be DevOps. They only need to know a few commands in git.
Using the `platform` command from Platform.sh offers also other positive aspects for developers and DevOps teams. It provides a streamlined and efficient way
to manage Platform.sh projects, environments, and deployments directly from the command line interface. With the `platform` command, users can easily create,
configure, and deploy applications, reducing manual intervention and saving time. Additionally, the command provides access to a wide range of Platform.sh
features, including environment management, scaling, backups, and monitoring, empowering teams to efficiently manage their application lifecycle from development
to production.
Overall, the platform command enhances productivity, simplifies workflows, and enables seamless collaboration across development teams.
You're ready to go live
-----------------------
The main advantage of Sylius Cloud on Platform.sh is to go live with your Sylius platform.
Going live with a project is a straightforward process that ensures seamless deployment and reliability. Once development and testing are complete,
deploying to production involves using Sylius Cloud's Git-based workflow to push changes to the main branch. Sylius Cloud automatically builds and deploys
the code to the production environment, ensuring zero downtime with its built-in rolling deployment strategy.
Sylius Cloud provides a comprehensive metrics dashboard where you can monitor various performance metrics of your applications and infrastructure in real-time.
The dashboard includes information such as CPU usage, memory usage, network traffic, response times, and more.
It also allows you to set up alerts based on predefined thresholds for different metrics. You can configure alerts to notify you via email, Slack,
or other communication channels when certain metrics exceed specified thresholds, helping you proactively identify and address performance issues.
You can also aggregate logs from all your application containers and services into a centralized logging system. You can view, search, and analyze
logs in real-time using the Platform.sh dashboard or export them to external logging services for further analysis and long-term storage.

8
docs/cookbook/platform-sh-cloud/map.rst.inc
View file

@ -1,8 +0,0 @@
* :doc:`/cookbook/platform-sh-cloud/introduction-to-sylius-cloud-on-platform-sh`
* :doc:`/cookbook/platform-sh-cloud/basic-project-setup`
* :doc:`/cookbook/platform-sh-cloud/sylius-plus`
* :doc:`/cookbook/platform-sh-cloud/environment-configuration`
* :doc:`/cookbook/platform-sh-cloud/cloud-management-basics`

163
docs/cookbook/sylius-cloud/basic-project-setup.rst Normal file
View file

@ -0,0 +1,163 @@
Basic project setup
===================
Sylius is a typical Symfony application, so all the steps below can be used for a clean Symfony application as well.
Prerequisites
-------------
To work with Sylius Cloud you'll need the `platform` (CLI) command on your computer. To install it, please run the script:
.. code-block:: bash
curl -fsSL https://raw.githubusercontent.com/platformsh/cli/main/installer.sh | bash
There are several methods of installing the `platform` application in your machine. To see them, please visit the `documentation <https://docs.platform.sh/administration/cli.html#1-install>`_
Pushing Sylius to Sylius Cloud
------------------------------
Let's assume you're extending the Sylius-Standard in version including the Sylius Cloud configuration.
First step you need to do is to create a Sylius Cloud project. To do it, please log in to your Sylius Cloud account and click "Create a new project" button from the dashboard.
You can also do it by running the CLI command:
.. code-block:: bash
platform project:create
When running the command, you'll be asked for a few information like project title, infrastructure region, default Git branch, pricing acceptance, etc.
For the convenience the environment name should be same as your main application branch. Let's say it's `main`.
After the project is created, you'll be able to access the information like:
- \- Project ID
- \- Production environment URL
- \- Git URL
If you create the project using Console, you'll need to switch to it with your CLI:
.. code-block:: bash
platform get <PROJECT_ID>
After this step all you need to do is to commit and push your code into the `platform` remote:
.. code-block:: bash
git add .
git commit -m "Initial Sylius Cloud configuration"
platform push --environment=<BRANCH_NAME>
This will trigger a build and deployment to Sylius Cloud. The CLI will automatically detect your Sylius application and set up the environment accordingly.
Once the deployment is complete, your Symfony application will be accessible via a unique URL provided by Sylius Cloud with format described below:
.. code-block:: bash
<ENVIRONMENT_NAME>-<PROJECT_ID>.<REGION>.platformsh.site
That's it! You've successfully pushed your Sylius application to Sylius Cloud. You can now continue to develop, test, and manage your application directly from the dashboard or the CLI.
Database and other services configuration on Sylius Cloud
---------------------------------------------------------
In Sylius Cloud, there is a special `PLATFORM_RELATIONSHIPS` environment variable that contains connection information for services defined in the `.platform.app.yaml` file.
This variable is commonly used in Symfony applications like Sylius, particularly with Doctrine, to automatically configure database connections based on the services provided by Sylius Cloud.
In your `.platform.app.yaml` and `.platform/services.yaml` files you define services such as databases, caches, or search engines. These services are provisioned by Sylius Cloud and are accessible to your application as environment variables.
The `PLATFORM_RELATIONSHIPS` environment variable contains a JSON-encoded string representing the relationships between your application and the services provisioned by Sylius Cloud. Each service is represented as an array containing connection details such as host, port, username, password, and database name.
In Sylius you can configure database connections using the `PLATFORM_RELATIONSHIPS` variable. Instead of hardcoding connection parameters in the Symfony configuration files, you can dynamically retrieve them from the `PLATFORM_RELATIONSHIPS` variable at runtime.
Example Doctrine configuration:
.. code-block:: yaml
doctrine:
dbal:
driver: 'pdo_mysql'
host: '%env(resolve:PLATFORM_RELATIONSHIPS:mysql:host)%'
port: '%env(resolve:PLATFORM_RELATIONSHIPS:mysql:port)%'
dbname: '%env(resolve:PLATFORM_RELATIONSHIPS:mysql:database)%'
user: '%env(resolve:PLATFORM_RELATIONSHIPS:mysql:username)%'
password: '%env(resolve:PLATFORM_RELATIONSHIPS:mysql:password)%'
To summarize, by using the `PLATFORM_RELATIONSHIPS` environment variable with Doctrine in Symfony applications deployed on Sylius Cloud, you can ensure that database connections are automatically configured and managed based on the services provisioned by the platform, leading to more flexible and portable application deployments.
Setting up cron configuration
-----------------------------
Setting up cron jobs (scheduled tasks) in Sylius Cloud involves defining them in the `.platform.app.yaml` file of your Sylius project.
Here's how you can set up cron jobs:
.. code-block:: yaml
crons:
# Run the `php bin/console my:command` command every day at 2:00 AM.
daily-cron:
spec: '0 2 * * *'
cmd: 'php bin/console my:command'
To fully integrate your Sylius application with Sylius Cloud infrastructure, you need to configure at least three cron commands:
.. code-block:: bash
bin/console sylius:cancel-unpaid-orders
bin/console sylius:promotion:generate-coupons
bin/console sylius:remove-expired-carts
So the crons section may look like below:
.. code-block:: yaml
crons:
cancel-unpaid-orders:
spec: "0 2 * * *"
cmd: "php bin/console sylius:cancel-unpaid-orders"
generate-promotion-coupons:
spec: "0 2 * * *"
cmd: "php bin/console sylius:promotion:generate-coupons"
remove-expired-carts:
spec: "0 2 * * *"
cmd: "php bin/console sylius:cancel-unpaid-orders"
The frequency of running these commands depends on your business requirements.
Verify the cron jobs
--------------------
Once your changes are deployed, Sylius Cloud will automatically set up the cron jobs according to the schedule you defined.
You can verify that the cron jobs are set up correctly by accessing the environment's SSH console and checking the crontab:
.. code-block:: bash
platform ssh
crontab -l
Configuring Symfony Messenger workers
-------------------------------------
Running workers on Sylius Cloud involves setting up background processes to handle tasks asynchronously, such as queue processing,
background jobs, or event-driven tasks. Workers are typically configured using the `.platform.app.yaml` file.
To fully integrate with Sylius application with Sylius Cloud, you'll need to configure the worker for catalog promotions:
.. code-block:: bash
bin/console messenger:consume main main_failed catalog_promotion_removal catalog_promotion_removal_failed
The full documentation regarding workers you can find in `the documentation <https://docs.platform.sh/create-apps/workers.html>`_
The workers section for Sylius project may look like the one below:
.. code-block:: yaml
workers:
catalog_promotions:
commands:
start: |
bin/console messenger:consume main main_failed catalog_promotion_removal catalog_promotion_removal_failed
The important information from `docs <https://docs.platform.sh/create-apps/app-reference.html#workers>`_ is that crashed workers are automatically restarted.

127
docs/cookbook/sylius-cloud/cloud-management-basics.rst Normal file
View file

@ -0,0 +1,127 @@
Cloud management basics
=======================
Once your environments are up, you may need some tools to manage them. Sylius Cloud offers a lot of environment commands which may help you in your application maintenance.
Please meet the most commonly used commands of the CLI.
SSH access
----------
On Sylius Cloud, connecting to an SSH session allows you to access your application's environment for administrative tasks, debugging, and troubleshooting.
The recommended method for connecting to SSH on Sylius Cloud is through the CLI, as on the example below:
.. code-block:: bash
platform ssh -e <ENVIRONMENT_ID>
Alternatively, you can access the SSH URL provided in the Sylius Cloud dashboard or environment information.
This URL typically follows the format ssh.<ENVIRONMENT_ID>.<PROJECT_ID>@ssh.<region>.platform.sh.
To authenticate with SSH on Sylius Cloud, you'll need to use SSH keys.
Ensure that you have SSH keys configured on your local machine and that your public SSH key is added to your Sylius Cloud account.
You can manage SSH keys through the Sylius Cloud Console or CLI.
Database access
---------------
Sylius Cloud CLI provides a command for interacting with the environment database directly from the command line.
You can use commands like platform db:sql to perform database operations on interactive database shell.
If you need to run already defined SQL query on the database, you can run the CLI command as follows:
.. code-block:: bash
platform db:sql "show tables"
If you with to import an SQL file into the database, you can run the command below:
.. code-block:: bash
platform sql < my_database_queries_file.sql
Dumping database
----------------
Sylius Cloud CLI provides a command for performing database dumping directly from the command line.
You can use it to create a dump of the specified environment database.
.. code-block:: bash
platform db:dump
If you need to specify the output filename and/or target directory, you can use the `--file` parameter:
.. code-block:: bash
platform db:dump --file=MyFileName.sql --directory=/home/MyUserName
You can also specify the tables you want to include or exclude from the export file:
.. code-block:: bash
platform db:dump --table=table1,table2,table3
The command above will create a database dump containing only the specified tables.
To exclude the tables from the dump file, you can use the `--exclude-table` option:
.. code-block:: bash
platform db:dump --exclude-table=table1,table2,table3
You also can dump only the schema of your database:
.. code-block:: bash
platform db:dump --table=table1,table2,table3 --schema-only
Backups
-------
Sylius Cloud provides commands in the CLI for preparing and restoring backups of your environment's database.
To prepare the backup you can use the command:
.. code-block:: bash
platform backup:create <ENVIRONMENT_ID>
This command creates a backup of the environment's database and stores it securely in Sylius Cloud backup system.
You can optionally specify additional options, such as `--no-wait`, to perform the backup asynchronously without waiting for it to complete.
If you wish to create backup without any downtime, you can use the `--live` command.
.. note::
Please keep in mind that running live backup may effect risky data inconsistency.
To restore a backup of your environment's database, use the command below:
.. code-block:: bash
platform backup:restore <ENVIRONMENT_ID> <BACKUP_ID>
This command restores the specified backup of the environment's database to its previous state.
You can obtain the backup ID from the Sylius Cloud dashboard or by listing available backups using the `platform backup:list` command.
Synchronizing environments
--------------------------
Sylius Cloud offers the environment synchronization command. It synchronizes the following components between the source and target environments:
- \- **Code**: Copies the codebase (Git repository) from the source environment to the target environment.
- \- **Configuration**: Applies the configuration settings (defined in the `.platform.app.yaml` file) from the source environment to the target environment.
- \- **Data**: Optionally synchronizes the database and files (if enabled) between the source and target environments.
To synchronize environments please use the command below:
.. code-block:: bash
platform environment:synchronize <SOURCE_ENVIRONMENT> <TARGET_ENVIRONMENT>
The synchronization command supports several options to customize the synchronization process, including:
- **\-\-code**: Synchronizes only the codebase between environments.
- **\-\-config**: Synchronizes only the configuration settings between environments.
- **\-\-data**: Synchronizes the database and files between environments (if applicable).
- **\-\-no-wait**: Performs the synchronization asynchronously without waiting for it to complete.
When you run the command without any options, the CLI will ask you whether you want to synchronize code, configuration or data between environments.

19
docs/cookbook/sylius-cloud/dictionary.rst Normal file
View file

@ -0,0 +1,19 @@
Sylius Cloud Dictionary
=======================
When diving into the Sylius Cloud, it's important to get familiar with some key terms. These terms help you navigate and understand how Sylius Cloud works.
- \- **Sylius Cloud Console** - a web-based interface that allows users to manage their projects, environments, applications, and services from a centralized dashboard. It provides a user-friendly and intuitive interface for performing various tasks related to application development, deployment, and management on the Sylius Cloud platform.
- \- **Sylius Cloud CLI** - the Command Line Interface (CLI) tool that allows users to interact with their Sylius Cloud projects, environments, applications, and services from the command line. It provides a set of commands and utilities that streamline common tasks related to application development, deployment, and management on the Sylius Cloud platform.
- \- **Project** - a container for all your environments, applications, and services. When you create a new project, you're essentially setting up a workspace where you can manage your development, staging, and production environments, along with the associated code repositories and services.
- \- **Environment** - a self-contained instance of your application that represents a specific stage in the software development lifecycle. Environments are used to separate different stages of development, testing, and production, allowing you to manage your application's codebase, configuration, and services in a controlled and isolated manner.
- \- **Build process** - the series of steps that are executed to prepare your application for deployment to a specific environment. These steps involve installing dependencies (Composer), warming-up application cache, building NodeJS assets, and performing any other tasks necessary to ensure that your application is ready to run in the target environment.
- \- **Deployment Process** - the process of replacing the existing application with the already built, updated version. The current application version is hosted until the whole deployment process exits without an error.
- \- **Relations** - the connections established between different services or components within your project. These connections enable communication and interaction between services, allowing them to work together seamlessly to support your application.

262
docs/cookbook/sylius-cloud/environment-configuration.rst Normal file
View file

@ -0,0 +1,262 @@
PHP Configuration
=================
Customizing PHP-related configurations on Sylius Cloud is pivotal for enhancing your Sylius platform performance and functionality.
Whether it's fine-tuning settings in php.ini, optimizing OPcache for caching efficiency, enabling preloading for faster application startup, or facilitating debugging with Xdebug,
Sylius Cloud empowers developers to tailor their PHP environment to meet specific project needs.
PHP-FPM configuration
---------------------
PHP-FPM helps improve your app’s performance by maintaining pools of workers that can process PHP requests. This is particularly useful when your app needs to handle a high number of simultaneous requests.
Sylius Cloud doesn't allow to manage all PHP-FPM configuration keys. By default, Sylius Cloud automatically sets a maximum number of PHP-FPM workers for your Sylius platform.
The number of workers is calculated based on three parameters:
- \- **The container memory**: the amount of memory you can allot for PHP processing depending on app size.
- \- **The request memory**: the amount of memory an average PHP request is expected to require.
- \- **The reserved memory**: the amount of memory you need to reserve for tasks that aren’t related to requests.
The value is calculated by the rule:
.. code-block:: text
`WORKERS_NUMBER = (CONTAINER_MEMORY + RESERVED_MEMORY) / REQUEST_MEMORY`.
You can setup the `request_memory` and `reserved_memory` by your own, in your `platform.app.yaml` file:
.. code-block:: yaml
runtime:
sizing_hints:
request_memory: 110
reserved_memory: 80
To determine what the optimal request memory is for your Sylius platform, you can refer to your PHP access logs:
.. code-block:: bash
platform log --lines 5000 php.access | awk '{print $6}' | sort -n | uniq -c
The command above will output you a structured value for last 5000 requests:
.. code-block:: text
2654 2048
431 4096
584 8192
889 10240
374 12288
68 46384
First column determines a number of requests, which had used the memory amount specified in second column.
Enabling Opcache preloading option
----------------------------------
Enabling Symfony preloading can help improve the performance of your application by reducing the time it takes to load classes and files on each request.
By following the steps below, you can easily configure preloading for your Sylius platform and take advantage of this optimization feature provided by Sylius Cloud.
To enable preloading, please:
1. Ensure that your Symfony application is using PHP version 7.4 or higher, as preloading is supported in these versions.
2. In your project's `.platform.app.yaml` file, add or update the PHP configuration section to include the preloading directive set to true. Here's an example:
.. code-block:: yaml
runtime:
extensions:
- opcache
web:
locations:
"/":
passthru: "/index.php"
php:
extensions:
- opcache
preloading: true
3. Optionally, you can customize the preload list for your Sylius application to include frequently used classes or files.
This optimization can improve preloading performance. You can do this in your Sylius application's configuration,
typically in the `config/packages/prod/opcache.yaml` file.
If this value is lower than the number of files in the Sylius platform, the cache becomes less effective because it starts thrashing.
4. Optionally, add or update the PHP configuration section in your project's `.platform.app.yaml` file to include the `opcache.max_accelerated_files` directive
with your desired value. For example:
.. code-block:: yaml
runtime:
extensions:
- opcache
web:
locations:
"/":
passthru: "/index.php"
php:
extensions:
- opcache
opcache:
max_accelerated_files: 10000
5. After updating your `.platform.app.yaml` file, commit your changes to your project's Git repository and push them to your Sylius Cloud environment.
Sylius Cloud will automatically detect the changes and deploy your Sylius platform with preloading enabled.
Configuring php.ini file
------------------------
By configuring PHP settings in `.platform.app.yaml`, you can customize the PHP runtime environment for your application on Sylius Cloud,
ensuring it meets your specific requirements and performance considerations.
To configure php.ini settings, please add or update the PHP configuration section in your project's `.platform.app.yaml` file.
You can specify settings under the php key, using the appropriate directives as needed.
For example, if you want to set `memory_limit` and `max_execution_time`, your configuration might look like this:
.. code-block:: yaml
web:
php:
memory_limit: 512M
max_execution_time: 60
You're also able to do it by running the CLI command, as an example below:
.. code-block:: bash
platform variable:create --level environment \
--prefix php --name memory_limit \
--value 256M --environment ENVIRONMENT_NAME \
--no-interaction
Optionally, you can also put the `php.ini` file in your Sylius platform root directory. Using this method isn’t recommended since it offers less flexibility and is more error-prone.
Consider using variables instead.
SMTP configuration
------------------
An SMTP configuration allows you to manage outgoing email communication from your environments.
You can turn on outgoing email for each environment separately. By default, outgoing email configuration is turned on for your production environment and disabled for other environments.
To turn it on for a specific environment, please use the CLI command:
.. code-block:: bash
platform environment:info --environment ENVIRONMENT_NAME enable_smtp true
Changing the setting will cause rebuilding the environment.
To configure your email delivery provider with Sylius application, please setup the `MAILER_DSN` environment variable.
Environment variables configuration
-----------------------------------
Environment variables allow you to have better control over the Sylius build process and runtime environment.
You can use them in your code to not to hardcode the sensitive environment configuration.
You can use them to define the values such as database credentials, API tokens, secret keys, SMTP configuration and others.
An example of environment variables definition you can find here:
.. code-block:: yaml
variables:
env:
A_SIMPLE_STRING_VALUE: "I'm simple string value"
AN_ARRAY_VALUE:
- 'value-1'
- 'value-2'
AN_OBJECT_VALUE:
"key1": "value1"
"key2": "value2"
my_variables:
AN_ARRAY_VALUE: ['value-1', 'value-2']
AN_OBJECT_VALUE:
key1: 'value1'
key2: 'value2'
You can also set your environment variables using the CLI:
.. code-block:: bash
platform variable:create --name env:foo --value bar
By using the environment variables you can define your own variables, or set up values for already defined variables used by the container:
.. code-block:: bash
platform variable:create --level environment --prefix php --name memory_limit --value 256M --environment ENVIRONMENT_NAME
A very useful option is to define whether variables value can be visible during build or deployment process logs:
.. code-block:: bash
platform variable:create --name env:a_sensitive_variable --value bar --visible-build=false --visible-runtime=false
Enabling PHP Extensions
-----------------------
Enabling PHP extensions on Sylius Cloud is a straightforward process.
You can do this by updating your `.platform.app.yaml` configuration file to include the required PHP extension. Here's how:
1. Determine which PHP extension your application needs. This could be extensions like pdo_mysql, gd, mbstring, or others.
2. Update `.platform.app.yaml` file. Under the runtime section, add the extensions key if it's not already present.
3. Add the name of the PHP extension you want to enable to the extensions list. For example:
.. code-block:: yaml
runtime:
extensions:
- pdo_mysql
- gd
Replace pdo_mysql and gd with the names of the extensions your application requires.
4. Save your changes to the `.platform.app.yaml` file, commit them to your Git repository, and push them to your environment.
5. After the changes have been deployed, you can verify that the PHP extension is enabled by accessing your application's environment through the CLI or web interface.
To see a complete list of the compiled PHP extensions, run the following CLI command:
.. code-block:: bash
platform ssh "php -m"
XDebug configuration
--------------------
Xdebug is a powerful PHP debugging tool that streamlines the development process by allowing developers to identify and fix issues in their code efficiently.
Here's a general overview of how you can configure it on Sylius Cloud:
1. In your project's `.platform.app.yaml` file, add a new section for configuring Xdebug. Here's an example configuration:
.. code-block:: bash
runtime:
extensions:
- xdebug
web:
php:
xdebug:
enabled: true
remote_enable: 1
remote_autostart: 1
remote_host: YOUR_HOST_IP
remote_port: 9000
2. Replace YOUR_HOST_IP with the IP address of your development machine. This configuration enables Xdebug, configures it to start automatically for each request, and sets up the remote debugging settings.
3. After updating your `.platform.app.yaml` file, commit your changes to your project's Git repository and push them to your environment. Sylius Cloud will automatically detect the changes and apply the new Xdebug configuration during deployment.
4. Finally, configure your IDE to listen for incoming Xdebug connections.
Set up a remote debugging session in your IDE and configure it to connect to the remote host (your development machine) on the specified port (usually 9000).
.. note::
Please keep in mind that enabling Xdebug may impact performance, so it's recommended to only enable it when needed, such as during development and testing phases.
Additionally, consider configuring Xdebug to only start for specific environments, such as development or staging, to avoid impacting production environments.

124
docs/cookbook/sylius-cloud/introduction-to-sylius-cloud.rst Normal file
View file

@ -0,0 +1,124 @@
Introduction to Sylius Cloud
===========================================
Sylius Cloud is a way of efficient and scalable Sylius hosting. With Sylius Cloud you get the ability of
deploying and managing your Sylius platform with minimal DevOps knowledge. All you need to do is to configure your project
dependencies, push the application and maintain it.
What is Sylius Cloud
--------------------
Sylius Cloud is a solution based on Platform.sh - a modern PaaS (Platform-as-a-Service) which gives you ability of creating
and managing any kind of environment, starting from development, through stagings, pre-productions, up to production environment.
It's based on its own containers architecture, with gives you all that is good of performance, security and scalability at once.
Using Platform.sh as a base of Sylius Cloud adds a possibility of hosting your Sylius platform on one of the following cloud service providers:
- \- Amazon Web Services (AWS)
- \- Google Cloud Platform (GCP)
- \- Microsoft Azure
- \- OVH
With Sylius Cloud you're able to choose the service provider, server characteristics (number of CPUs, memory amount, disk size etc.)
with a clear information about costs. It's a good solution both for small, medium and huge web stores with a big traffic and number of orders.
Main Sylius Cloud concepts:
- \- Git-driven architecture - helps with setting up new environments with a simple pushing a new git branch to the specified remote. It makes you ability to create new environments fast.
- \- Infrastructure as a code - all you need to do is to write your application and a few Yaml files to create your environment. So simple and so powerful.
- \- Multi-services and multi-apps - it doesn't matter your application is monolith- or microservice-based architecture. It doesn't matter how much different external services you need (MySQL, PostgreSQL, ElasticSearch, Redis etc.) - it just works good in all cases.
Sylius Cloud configuration in Sylius
------------------------------------
All the infrastructure configuration files are placed in `Sylius-Standard <https://github.com/Sylius/Sylius-Standard>`_ project. It means you'll get it when running the command:
.. code-block:: bash
composer create-project sylius/sylius-standard acme
The paths you should be interested in are:
- \- `.platform.app.yaml` - This file is used to define the configuration of the application itself. It specifies how the application should be built, what runtime to use, which commands to run on deployment, etc. It also includes information such as the type of application, language runtime, build and deploy hooks, and more.
- \- `.env.platform.dist` - The environment file automatically used by the application during the build process.
- \- `.platform/routes.yaml` - This file defines the routes and how traffic is routed to the application. It specifies the incoming URLs and how they should be directed to the appropriate services or applications. Routes can be configured to handle different paths, domains, or other conditions.
- \- `.platform/services.yaml` - This file is used to define additional services or dependencies required by the application. It allows defining various types of services such as databases, caches, search engines, etc., along with their configuration. Services defined in this file are automatically provisioned and integrated with the application environment.
Creating a new project and environment
--------------------------------------
Every new environment needs to be created in the Sylius Cloud Console or by using the CLI.
But first before creating an environment you need to create the project. When you're creating a new project from the Console,
to use the Sylius Cloud potential, please choose the "Create from scratch" option, as selected on the screenshot below:
.. image:: ../../_images/cookbook/sylius-cloud/create-from-scratch.png
:align: center
:scale: 50%
|
During creating a new project you'll automatically create a new environment, which is connected to your git branch (please read the information on screenshot below):
.. image:: ../../_images/cookbook/sylius-cloud/create-from-scratch-default-environment.png
:align: center
:scale: 50%
|
When you've created the project, you're ready to create new environments. Please note that your project already have the first (production) environment just after project is being created.
Regarding of creating new environment, we assume you're a developer, so it will be more convenient for you to use the CLI command:
.. code-block:: bash
platform environment:create
This command will prompt you to specify various options for the new environment, such as its name, type, parent environment, and more. Follow the prompts to configure the new environment according to your requirements.
Once the environment is created, you can deploy your application to it using the following command:
.. code-block:: bash
platform push --environment=<branch_name>
Replace <branch_name> with the name of the Git branch you want to deploy.
After the deployment is complete, you can access your new environment using its unique URL, which typically follows the format:
.. code-block:: bash
<ENVIRONMENT_NAME>-<PROJECT_ID>.<REGION>.platformsh.site
That's it! You've now created a new environment in your Sylius Cloud project and deployed your application to it. You can repeat these steps to create additional environments as needed for development, testing, or other purposes.
Developing application with Sylius Cloud
----------------------------------------
As described in previous section, you're able to create new environments by using the CLI command. Working with multiple environments is a very good point of development. It gives you a lot of advantages, like:
- \- You're able to create an environment for all your features and test how they behave on the real infrastructure.
- \- Your team mates test the features independently of other developers. They're able to create their own environment and work there.
- \- When you're using Git Flow, you're able to test how your features integrate with other functionalities, i.e., with other microservices.
- \- You and your team mates don't need to be DevOps. They only need to know a few commands in git.
Using the CLI command from offers also other positive aspects for developers and DevOps teams. It provides a streamlined and efficient way
to manage Sylius Cloud projects, environments, and deployments directly from the command line interface. With the CLI command, users can easily create,
configure, and deploy applications, reducing manual intervention and saving time. Additionally, the command provides access to a wide range of Sylius Cloud
features, including environment management, scaling, backups, and monitoring, empowering teams to efficiently manage their application lifecycle from development
to production.
Overall, the platform command enhances productivity, simplifies workflows, and enables seamless collaboration across development teams.
You're ready to go live
-----------------------
The main advantage of Sylius Cloud is to go live with your Sylius platform.
Going live with the project is a straightforward process that ensures seamless deployment and reliability. Once development and testing are complete,
deploying to production involves using Sylius Cloud's Git-based workflow to push changes to the main branch. Sylius Cloud automatically builds and deploys
the code to the production environment, ensuring zero downtime with its built-in rolling deployment strategy.
Sylius Cloud provides a comprehensive metrics dashboard where you can monitor various performance metrics of your applications and infrastructure in real-time.
The dashboard includes information such as CPU usage, memory usage, network traffic, response times, and more.
It also allows you to set up alerts based on predefined thresholds for different metrics. You can configure alerts to notify you via email, Slack,
or other communication channels when certain metrics exceed specified thresholds, helping you proactively identify and address performance issues.
You can also aggregate logs from all your application containers and services into a centralized logging system. You can view, search, and analyze
logs in real-time using the Sylius CLoud dashboard or export them to external logging services for further analysis and long-term storage.

10
docs/cookbook/sylius-cloud/map.rst.inc Normal file
View file

@ -0,0 +1,10 @@
* :doc:`/cookbook/sylius-cloud/introduction-to-sylius-cloud`
* :doc:`/cookbook/sylius-cloud/dictionary`
* :doc:`/cookbook/sylius-cloud/basic-project-setup`
* :doc:`/cookbook/sylius-cloud/sylius-plus`
* :doc:`/cookbook/sylius-cloud/environment-configuration`
* :doc:`/cookbook/sylius-cloud/cloud-management-basics`
* :doc:`/cookbook/sylius-cloud/troubleshooting`

8
docs/cookbook/platform-sh-cloud/sylius-plus.rst → docs/cookbook/sylius-cloud/sylius-plus.rst
View file

@ -11,6 +11,7 @@ How to install Sylius Plus modules?
Sylius Plus modules are the Sylius plugins (so the Symfony bundles), which need to be defined in your composer.json file as described below:
.. code-block:: json
{
"require": {
"sylius/customer-service-plugin": "^0.2.0",
@ -32,13 +33,14 @@ Sylius Plus modules are the Sylius plugins (so the Symfony bundles), which need
Since all Sylius Plus modules are private packages, you need to configure the private packagist repository. You'll receive the repository URL from our sales.
Enabling Sylius Plus token on Platform.sh
-----------------------------------------
Enabling Sylius Plus token on Sylius Cloud
------------------------------------------
Along with the repository URL you'll receive an authentication token, which is needed to be configured in your Platform.sh environment. It can't be hardcoded into `composer.json` file
Along with the repository URL you'll receive an authentication token, which is needed to be configured in your Sylius Cloud environment. It can't be hardcoded into `composer.json` file
as it is a very sensitive information. The best way is to configure it by creating an environment variable, which is automatically read by composer:
.. code-block:: bash
platform variable:create --level project --name env:COMPOSER_AUTH \
--json true --visible-runtime false --sensitive true --visible-build true \
--value '{"http-basic": {"repo.packagist.com": {"username": "token", "password": "<YOUR_TOKEN>"}}'

25
docs/cookbook/sylius-cloud/troubleshooting.rst Normal file
View file

@ -0,0 +1,25 @@
Troubleshooting
===============
Every tool sometimes crashes or has some common issues. In this section we'll help you in solving common problems you can meet using Sylius Cloud.
Connection timeout
------------------
We hope you won't, but sometimes using the CLI you can see the error message:
.. code-block:: text
cURL error 28: Operation timed out after 30000 milliseconds with 0 bytes received
This message may confuse a lot of people. But in short words it means the environment you're currently on (in context of CLI), has been removed.
It might be removed by the CLI or i.e. the Console.
Best would be to run the `platform project:list` command and then switch to a different project:
.. code-block:: bash
platform get <PROJECT_ID>
If the commands above also finish with timeout, please use Console to obtain any other project ID.
Then please locate the `.platform/local/project.yaml` file and paste the new project ID into the `id:` key.