Tutorial: Build your own package

Goal

The goal of this tutorial is to create a new package that you can deploy to a new store by following Tutorial: Deploying a ready package.

Prerequisites

  1. You have to be a registered partner of Elastycloud
  2. You need to have an account and be able to sign in to Console
  3. You need to be a Magento developer with prior Magento experience
  4. You need to have the following tools installed and knowledge how they work
    • git
    • composer
  5. You need a Bitbucket account, and rights to create new repositories
  6. You need to get a personal Composer Access Key

Tutorial

Before we begin, choose a “package key” that will identify the package you are creating, we will be using this throughout.

  1. Sign in to Console
  2. In the Packages ‣ Package list ‣ Add new package
  3. Fill in the desired details according to Package details, use the package key you chose above as Identifier key.
  4. Create a new git repository in your Bitbucket account according to Create Bitbucket repository
  5. Get project skeleton and push to your repository according to Prepare and push repository
  6. Add and push a git tag according to Tag and trigger a build
  7. In the Packages menu, go to Package versions and observe the status of your build. Once it is built successfully you can deploy it to production

Package details

A Package can be seen as the connection between a deployment and the source-code in your repository.

Identifier Key
A globally unique key to identify your package. You reference this in your elastycloud.yaml
Git repo name
The “Full name” of your repository in bitbucket. You can find this in the URL of your repository. So if you go to https://bitbucket.org/[Git repo name]/, you should see your repository.
Package type
Defines the type of the package. Use Package if this is used for many customers, Project for customer specific repos. This is only to keep your packages organized and has no real impact.
Preferred Stable Version
This is used to auto-select a version to install when none is specifically chosen. See how to write version constraints

Create Bitbucket repository

Sign in to Bitbucket and create a new repository.

Add a Bitbucket webhook in that repository (Bitbucket -> [repo] -> Settings -> Webhooks -> Add webhook) with title “Elastycloud” and URL https://webhook.elastycloud.io/git/bitbucket/magento. Check Enable request history collection and leave rest as default.

This will trigger a build on every push.

Note

Make sure the Bitbucket user ElastycloudCICD has READ access to your repository.

Prepare and push repository

To get a template for your repository you can use our skeleton-repository.

Open a terminal to a local folder where you want to create the repository and run the following command:

composer create-project elastycloud/skeleton-magento [PACKAGE-KEY-HERE] --repository="https://composer.elastycloud.io/"

Replace [PACKAGE-KEY-HERE] with the key you chose before.

Note

You will be asked for a username and password, see Creating a Composer Access Key

A folder named as your package key will be created with a basic structure inside.

In the magento/ folder is a composer.json-file that has a requirement for the meta-package elastycloud/package_magento-base. This is how all cloud related modules will be included in your project.

Set up a git repository inside the folder that was created, add & commit all files within and push it to your Bitbucket repository.

Repository structure

To initiate the project run composer install in the magento folder, this will fetch all needed magento modules.

Once you have installed the project these files below should be checked in to git:

  • magento/app/etc/config.php
  • magento/composer.json
  • magento/composer.lock
  • elastycloud.yaml
  • .gitignore

All other files is optional.

Tag and trigger a build

Once you are done with your code it is time to trigger a build. You do this by tagging it with a SemVer tag, for example 0.0.0-alpha.1, and then pushing that tag.

git tag 0.0.0-alpha.1
git push --tags

All aspects of SemVer can be used in the version tag, EXCEPT the build number, since this is added by the builder.