Mage-OS Composer Repository Generator

Background

This project was started not with the primary goal to go into production, but rather to explore and learn how to build Magento Open Source releases.
It has evolved to be used in production. However, the intention is to create additional implementations, for example in Rust https://github.com/mage-os/package-splitter.

Generated composer repositories

The generator is used to generate the following composer repositories:

• https://mirror.mage-os.org
• https://upstream-nightly.mage-os.org
• https://repo.mage-os.org

It can also be used to generate custom mirrors and releases based on Mage-OS.

Versions generated for mirrors

When generating a mirror composer repository, all packages required to install Magento Open Source 2.3.7-p3 and newer will be created. This might change in the future.

Usage

This project provides a docker image to generate a composer package repository.

Mount the directory to contain the generated files into /build while executing the image.
Usually this will be the DOCUMENT_ROOT of the host serving the composer repo, for example --volume /var/www/html:/build.

Specifying the build target(s)

This project can generate different types of composer repositories. At the time of writing, the supported build targets are

--target=mirror (default)

By default, a Magento Open Source mirror repository is generated.

--target=upstream-nightly

This generates a release of the current development versions of Magento Open Source. This is known as an "upstream nightly" build.

--target=mageos-nightly

This generates a release of the current development versions of Mage-OS. This is known as a "nightly" build.

--target=release

This build target requires a number of additional arguments:

• --mageosRelease=x.x.x The release version, for example 1.0.0
• --mageosVendor=mage-os The composer vendor name for the release. Defaults to mage-os
• --upstreamRelease=2.4.6-p1 The corresponding Magento Open Source release.

Caching git repositories

Caching git repos is optional. Without caching, every git repository will be cloned each time the repo is generated. This ensures the latest versions will be used to generate the packages.
However, cloning large repositories like Magento Open Source takes some time, so it can be beneficial to cache the cloned repository.

A local directory can be mounted at /generate-repo/repositories in order to cache the cloned GitHub repos.
Be aware that existing git repositories currently will not be updated on subsequent runs. This is mainly useful during development when executing the container image multiple times consecutively. If you want to update a cached git repo before packages are generated, either delete the cache dir, or run git fetch --tags manually before executing the image.

Example: --volume "${HOME}/repo-cache:/generate-repo/repositories"

Mounting a composer dir

A ~/.composer directory can be mounted, too, which will allow satis to benefit from existing caches. This doesn't make a big difference though.
Example: --volume "${COMPOSER_HOME:-$HOME/.composer}:/composer"

Example with docker

To generate the repository in the directory ~/html, run the following command, replacing https://mirror.mage-os.org with the URL of your mirror:

docker run --rm --init -it --user $(id -u):$(id -g) \
  --volume "$(pwd)/html:/build" \
  --volume "${COMPOSER_HOME:-$HOME/.composer}:/composer" \
  magece/mageos-repo-js:latest  --target=mirror --mirror-base-url=https://mirror.mage-os.org

podman

If you prefer to execute the container with podman, you should not specify the --user argument, as the in-container root user will automatically map to the current system user. To generate the repository in ~/html using podman, run the following command, replacing https://mirror.mage-os.org with the URL of your mirror:

podman run --rm --init -it \
  --volume "$(pwd)/html:/build:z"  \
  --volume "${COMPOSER_HOME:-$HOME/.composer}:/composer:z" \
  magece/mageos-repo-js:latest --mirror-base-url=https://mirror.mage-os.org

Manual generation

It is possible to generate the composer repositories without a container.
This process can be useful for automation, for example the mage-os composer repositories are built in this way via GitHub actions.

For this, you'll need nodejs 16, php8-0 (or 7.4), yarn, git and composer.

Also, the github.com/mage-os/php-dependency-list phar executable is expected to be in the PATH.

curl -L https://github.com/mage-os/php-dependency-list/raw/main/php-classes.phar -o /usr/local/bin/php-classes.phar
chmod +x /usr/local/bin/php-classes.phar

Check the corresponding workflows in .github/workflows for details on how to run the generation.

Generating custom releases based on Mage-OS

Currently, the manual generation approach needs to be used to create custom releases.
Two things are required:

• Specify a custom vendor name using the --mageosVendor=extreme-commerce option
• Provide custom meta-package dependency templates in resource/composer-templates/{vendor-name}/
  See the existing ones in resource/composer-templates/mage-os for examples.
  In future it will be possible to specify the composer-templates path with a command line argument.

Building the docker image

docker build -t magece/mirror-repo-js .

Copyright 2022 Vinai Kopp, Mage-OS

Distributed under the terms of the 3-Clause BSD Licence. See the LICENSE file for more details.