symfony · javiereguiluz · Nov 18, 2021 · Oct 5, 2021
diff --git a/setup/flex.rst b/setup/flex.rst
@@ -133,7 +133,7 @@ manual steps:

 #. Move the public assets, such as images or compiled CSS/JS files, from
   ``src/AppBundle/Resources/public/`` to ``public/`` (e.g. ``public/images/``).
-   
+
 #. Remove ``src/AppBundle/``.

 #. Move the source of the assets (e.g. the SCSS files) to ``assets/`` and use
@@ -189,6 +189,11 @@ If you customize these paths, some files copied from a recipe still may contain
 references to the original path. In other words: you may need to update some things
 manually after a recipe is installed.

+Learn more
+----------
+
+* :doc:`/setup/flex_private_recipes`
+
 .. _`default services.yaml file`: https://github.com/symfony/recipes/blob/master/symfony/framework-bundle/4.4/config/services.yaml
 .. _`shown in this example`: https://github.com/symfony/skeleton/blob/8e33fe617629f283a12bbe0a6578bd6e6af417af/composer.json#L24-L33
 .. _`shown in this example of the skeleton-project`: https://github.com/symfony/skeleton/blob/8e33fe617629f283a12bbe0a6578bd6e6af417af/composer.json#L44-L46

diff --git a/setup/flex_private_recipes.rst b/setup/flex_private_recipes.rst
@@ -0,0 +1,226 @@
+How To Configure and Use Flex Private Recipe Repositories
+=========================================================
+
+Since the `release of version 1.16`_ of ``symfony/flex``, you can build your own private
+flex recipe repositories, and seamlessly integrate them into the ``composer`` package
+installation and maintenance process.
+
+This is particularly useful when you have private bundles or packages that must perform their own
+installation tasks, in a similar fashion that Symfony and other open-source bundles and packages handle their
+own installation tasks via ``symfony/flex``.
+
+To do this, in broad strokes, you:
+
+* Create a private GitHub repository;
+* Create your private recipes;
+* Create an index to the recipes;
+* Store your recipes in the private repository;
+* Grant ``composer`` access to the private repository;
+* Configure your project's ``composer.json`` file; and
+* Install the recipes in your project.
+
+Create a Private GitHub Repository
+----------------------------------
+
+Log in to your GitHub.com account, click your account icon in the top-right corner, and select
+**Your Repositories**. Then click the **New** button, fill in the **repository name**, select the
+**Private** radio button, and click the **Create Repository** button.
+
+Create Your Private Recipes
+---------------------------
+
+A ``symfony/flex`` recipe is a standard JSON file that has the following structure:
+
+.. code-block:: json
+
+    {
+        "manifests": {
+            "myorg/package-name": {
+                "manifest": {
+                },
+                "ref": "7405f3af1312d1f9121afed4dddef636c6c7ff00"
+            }
+        }
+    }
+
+If your package is a private Symfony bundle, you will have the following in the recipe:
+
+.. code-block:: json
+
+    {
+        "manifests": {
+            "myorg/private-bundle": {
+                "manifest": {
+                    "bundles": {
+                        "Myorg\\PrivateBundle\\MyorgPrivateBundle": [
+                            "all"
+                        ]
+                    }
+                },
+                "ref": "7405f3af1312d1f9121afed4dddef636c6c7ff00"
+            }
+        }
+    }
+
+Replace ``myorg`` and ``private-bundle`` with your own private bundle details.
+
+The ``"ref"`` entry is just a random 40-character string, which is used by ``composer`` to determine if
+your recipe was modified. Every time that you make changes to your recipe, you also need to
+generate a new ``"ref"`` value.
+
+.. tip::
+
+    Use the following PHP script to generate a random ``"ref"`` value.
+
+    .. code-block::
+
+        $bytes = random_bytes(20);
+        var_dump(bin2hex($bytes));
+
+The ``"all"`` entry tells ``symfony/flex`` to create an entry in your project's ``bundles.php`` file
+for all environments. To load your bundle only for the ``dev`` environment, replace ``"all"`` with ``"dev"``.
+
+The name of your recipe JSON file must conform to the following convention:
+
+    ``myorg.private-bundle.1.0.json``
+
+where ``1.0`` is the version number of your bundle.
+
+Replace ``myorg`` and ``private-bundle`` with your own private bundle or package details.
+
+You will probably also want ``symfony/flex`` to create configuration files for your bundle or package in the
+project's ``/config/packages`` directory. To do that, change the recipe JSON file as follows:
+
+.. code-block:: json
+
+    {
+        "manifests": {
+            "myorg/private-bundle": {
+                "manifest": {
+                    "bundles": {
+                        "Myorg\\PrivateBundle\\MyorgPrivateBundle": [
+                            "all"
+                        ]
+                    },
+                    "copy-from-recipe": {
+                        "config/": "%CONFIG_DIR%"
+                    }
+                },
+                "files": {
+                    "config/packages/myorg_private.yaml": {
+                        "contents": [
+                            "myorg_private:",
+                            "    encode: true",
+                            ""
+                        ],
+                        "executable": false
+                    }
+                },
+                "ref": "7405f3af1312d1f9121afed4dddef636c6c7ff00"
+            }
+        }
+    }
+
+For more examples of what you can include in a recipe file, browse the live `Symfony recipe files`_.
+
+Create an Index to the Recipes
+------------------------------
+
+The next step is to create an ``index.json`` file, which will contain entries for all your
+private recipes, and other general configuration information.
+
+The ``index.json`` file has the following format:
+
+.. code-block:: json
+
+    {
+        "recipes": {
+            "myorg/private-bundle": [
+                "1.0"
+            ]
+        },
+        "branch": "master",
+        "is_contrib": true,
+        "_links": {
+            "repository": "github.com/your-github-account-name/your-recipes-repository",
+            "origin_template": "{package}:{version}@github.com/your-github-account-name/your-recipes-repository:master",
+            "recipe_template": "https://api.github.com/repos/your-github-account-name/your-recipes-repository/contents/{package_dotted}.{version}.json"
+        }
+    }
+
+Create an entry in ``"recipes"`` for each of your bundle recipes.
+
+Replace ``your-github-account-name`` and ``your-recipes-repository`` with your own details.
+
+Store Your Recipes in the Private Repository
+--------------------------------------------
+
+Upload the recipe ``.json`` file(s) and the ``index.json`` file into the root directory of your
+private GitHub repository.
+
+Grant ``composer`` Access to the Private Repository
+-------------------------------------------------
+
+In your GitHub account, click your account icon in the top-right corner, select
+``Settings`` and ``Developer Settings``. Then select ``Personal Access Tokens``.
+
+Generate a new access token with ``Full control of private repositories`` privileges.
+
+Copy the access token value, switch to the terminal of your local computer, and execute
+the following command:
+
+.. code-block:: terminal
+
+    composer config --global --auth github-oauth.github.com [token]
+
+Replace ``[token]`` with the value of your GitHub personal access token.
+
+Configure Your Project's ``composer.json`` File
+---------------------------------------------
+
+Add the following to your project's ``composer.json`` file:
+
+.. code-block:: json
+
+    {
+        "extra": {
+            "symfony": {
+                "endpoint": [
+                    "https://api.github.com/repos/your-github-account-name/your-recipes-repository/contents/index.json",
+                    "flex://defaults"
+                ]
+            }
+        }
+    }
+
+Replace ``your-github-account-name`` and ``your-recipes-repository`` with your own details.
+
+.. tip::
+
+    The ``extra.symfony`` key will most probably already exist in your ``composer.json``. Simply
+    add the ``"endpoint"`` key to the existing ``extra.symfony`` entry.
+
+.. tip::
+
+    The ``endpoint`` URL **must** point to ``https://api.github.com/repos`` and **not* to
+    ``https://www.github.com``. The latter will not work.
+
+Install the Recipes in Your Project
+-----------------------------------
+
+If your private bundles / packages have not yet been installed in your project, run the following command:
+
+.. code-block:: terminal
+
+    composer update
+
+If the private bundles / packages have already been installed and you just want to install the new
+private recipes, run the following command:
+
+.. code-block:: terminal
+
+    composer recipes
+
+.. _`release of version 1.16`: https://github.com/symfony/cli
+.. _`Symfony recipe files`: https://github.com/symfony/recipes/tree/flex/main
+