Sylius cloud cookbook

docs/cookbook/index.rst

@@ -184,3 +184,18 @@ API
 
 .. include:: /cookbook/api/map.rst.inc
 
+Sylius Cloud
+------------
+
+.. toctree::
+    :hidden:
+
+    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/sylius-cloud/map.rst.inc

docs/cookbook/sylius-cloud/basic-project-setup.rst

@@ -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.

docs/cookbook/sylius-cloud/cloud-management-basics.rst

@@ -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.

docs/cookbook/sylius-cloud/dictionary.rst

@@ -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.
+