Documentation

• 1: Overview
• 1.1: Project Roadmap
• 2: Getting Started
• 2.1: MacOS
• 2.2: Usage
• 3: Local PHP
• 3.1: Homebrew
• 3.2: phpbrew
• 4: Developers Guide
• 4.1: Contribution Guidelines
• 4.1.1: Contribute to Documentation
• 4.1.2: Contribue to Magento CLI

1 - Overview

This project provides a globally-installed cli tool for managing magento locally. This includes serving it locally (magento serve), and helpers to install magento. As well as convienences to other tools, such as magento sql to access mysql-cli, and to install composer and n98-magerun2. This tool also passes through commands to the bin/magento tool in the working directory, allowing it to serve as a one-stop magento shop.

Rationale

Docker is typically the preferred method for running Magento locally. It’s great because it lets you containerize all the services required to run Magento, and even run them concurrently using a reverse proxy like traefik with goodies like tls and all that.

On Linux, docker works exceptionally well with near-native performance. On other platforms, however, it’s typical for docker to run within a VM which significantly impacts performance. On these platforms, there’s typically a lot of performance lost through volume mounting (the Magento codebase is hundreds of megs of small text files). This can be relieved somewhat with mutagen, a file syncing service that copies files back and forth between your local and the container - causing a delay in updates and frustration when things don’t reflect on the frontend. Further still, when the docker service containers aren’t compiled for your system arch (M1/ARM7/x64) the performance losses mounts.

Considering other popular languages and frameworks, like this hugo documentation site as an example, it’s written in golang and when you want to serve the blog locally, you run hugo serve which spawns a web server and provides a url. pwa-studio works the same way with webpack, it’s a popular convention. Let’s provide the same convention, and support using php’s built-in web server as a way to serve Magento. We can still provide docker-backed services, even a php-fpm service (with mutagen, if you insist) to round things out. But this project differentiates from others because it has first-class support for pre-compiled php binaries. These are provided by brew and phpbrew by the way, easy to install, you can still run multiple php versions concurrently, and they are substantially faster than running it in a multi-arch docker container.

1.1 - Project Roadmap

• Using system-provided php runtime for executing magento
  • currently uses php -S provided by phpbrew or homebrew
  • supports concurrency with different versions through environment variables
• using dockerized php runtime for executing magento
  • should provide a default local setup with all-docker
• dockerized backend services
  • currently elasticsearch and databases
  • variablized, can use any version or image of services
  • ability to add other services through yaml
  • expected to add mailhog, ampq, redis, and friends
• magento-cli runs as a global cli app
  • all yaml configurations packaged with executable
  • magento serve kicks off dev instance with zero configuration
• Documentation
  • hugo-based documentation site hosted on github.io
• Available on Popular Package Managers
  • brew (macos, linux)
  • chocolatey (windows)?
• Build Targets
  • macos (arm/intel)
  • linux (arm/intel)
  • windows (intel)
  • chromeos/crostini (intel and probably arm)

2 - Getting Started

Prerequisites

Magento CLI is designed to work wtih docker and docker-compose, and requires a locally installed verison of php to use the built-in php server. If you are running php locally, you will also need to provide tools like composer.

Installation

Binaries are compiled with every release, you can grab it from the releases page, and use it as-is. These files are fit to be ran directly, from $PATH, or even committed i.e. /path/to/iac-repo/bin/magento-cli and invoked with cd /path/to/iac-repo/ && bin/magento-cli.

Homebrew

Installing with brew is the preferred way to install for most use-cases. Homebrew installs the tool globally, and is updated with every release.

    brew tap blueacorninc/magento-cli
    brew install magento-cli

Compiling From Source

If you prefer to compile from source, the Makefile can be used:

    git clone git@github.com:blueacorninc/magento-cli.git 
    cd magento-cli
    make install # runs `go build .` and copies to /usr/local/bin

Running Source Locally

    cd example/
    composer install
    go run .. serve

Try it out!

Once installed, you can test out the tool against any project!

cd example
composer install # lets install the php deps
magento install # runs setup:install and creates config.php and env.php

magento serve # That's it!

2.1 - MacOS

Requires php, docker and docker-compose.

Install docker and docker-compose using the Docker Installation Guide.

Review the Homebrew Installation Article for more information on how to confgiure PHP using this tool.

2.2 - Usage

.magento-cli directories

A project repostiory can override the default configuration by storing replacement services or tasks yaml directories in .magento-cli. For example, let’s say you would like to change the database docker composition, you canc create .magento-cli/services/database.yaml and this file will be interpreted when you run magento serve instead of the version sourced by magento-cli.

3 - Local PHP

Currently, this project expects you to bring your own version of PHP so it can be ran natively. This section will cover how to run PHP like this. Don’t worry, dockerizing php to make all this optional is on the roadmap!

3.1 - Homebrew

Installing with brew is the preferred way to install for most use-cases. Homebrew installs the tool globally, and is updated with every release.

Environment Variables

Exporting the following will peg you to a specific version of php for your instance, using homebrew. This is a makeshift approach that requires direnv or the like, in the future the tool will abstract this away for you.

export MAGECLI_PHP_VERSION=8.1.6
export MAGECLI_PHP_BIN=/opt/homebrew/Cellar/php/$MAGECLI_PHP_VERSION/bin/
export PATH=$MAGECLI_PHP_BIN:$PATH%

Installation

Installing PHP with brew is easy, just trigger:

brew install php@8.1

If you run brew link php@8.1 this will set it as the system-wide default. This seems like it should be fine, but keep in mind tools like magento-cloud require PHP 7.4 at the time of this writing so having the system-wide as that version is usually simpler. See the environment variables section to set this per-directory.

3.2 - phpbrew

Enviroment Variables

This is stubbed out but hasn’t been defined yet, homebrew is the best way to use this tool at this point.

export MAGECLI_PHP_VERSION=8.1.6
export MAGECLI_PHP_BIN=/opt/phpbre/--fixme--/$MAGECLI_PHP_VERSION/bin/
export PATH=$MAGECLI_PHP_BIN:$PATH%

Installation

Installing with phpbrew will also supported. This will compile php with any kind of modules or flags you need. Please review the official Installation Documentation to set this up, but we will summerize below.

# install
curl -L -O https://github.com/phpbrew/phpbrew/releases/latest/download/phpbrew.phar
chmod +x phpbrew.phar

# Move the file to some directory within your $PATH
sudo mv phpbrew.phar /usr/local/bin/phpbrew

phpbrew init

echo "[[ -e ~/.phpbrew/bashrc ]] && source ~/.phpbrew/bashrc" >> ~/.bashrc

phpbrew install 8.1.6 +pdo +mysql

4 - Developers Guide

4.1 - Contribution Guidelines

4.1.1 - Contribute to Documentation

Contributing to Docs

We use Hugo to format and generate our website, the Docsy theme for styling and site structure, and Github Actions to manage the deployment of the site. Hugo is an open-source static site generator that provides us with templates, content organisation in a standard directory structure, and a website generation engine. You write the pages in Markdown (or HTML if you want), and Hugo wraps them up into a website.

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

Updating a single page

If you’ve just spotted something you’d like to change while using the docs, Docsy has a shortcut for you:

1. Click Edit this page in the top right hand corner of the page.
2. If you don’t already have an up to date fork of the project repo, you are prompted to get one - click Fork this repository and propose changes or Update your Fork to get an up to date version of the project to edit. The appropriate page in your fork is displayed in edit mode.
3. Follow the rest of the Quick start with Netlify process above to make, preview, and propose your changes.

Creating an issue

If you’ve found a problem in the docs, but you’re not sure how to fix it yourself, please create an issue in the Goldydocs repo. You can also create an issue about a specific page by clicking the Create Issue button in the top right hand corner of the page.

Useful resources

• Docsy user guide: All about Docsy, including how it manages navigation, look and feel, and multi-language support.
• Hugo documentation: Comprehensive reference for Hugo.
• Github Hello World!: A basic introduction to GitHub concepts and workflow.

4.1.2 - Contribue to Magento CLI

Contributing to Magento CLI

We love pull requests!

Fork, then clone the repo:

    git clone git@github.com:your-username/magento-cli.git

Set up your machine:

    cd magento-cli
    make build

Make sure the existing tests pass:

    make test

While creating new commands, don’t forget to create a _test.go file.

Make your changes, Add tests for your change, Make the tests pass:

    make test

Make your change. Add tests for your change. Make the tests pass:

    make test

Push to your fork and submit a pull request.

At this point you’re waiting on us. We like to at least comment on pull requests within three business days (and, typically, one business day). We may suggest some changes or improvements or alternatives.

Some things that will increase the chance that your pull request is accepted:

• Write tests.
• Write a good commit message.