Tutorial¶
Overview¶
MetaDeploy makes it possible to publish a CumulusCI flow as an installer so that it can be repeated by any user who brings their own org.
A single instance of MetaDeploy can host installers for multiple Products and multiple Versions of each Product. For each version, multiple Plans can be configured. Each Plan represents a separate series of Steps that will be run in sequence to complete the installation.
Publishing an installer¶
Setting up a new product in MetaDeploy requires access to the Django
admin UI. Once the product has been set up, new versions can be
published by running a command using the cci
CLI. This guide assumes
you are already familiar with CumulusCI and have it set up for your
project.
1. Add a Product Category¶
Start by logging into the MetaDeploy admin UI.
Each Product must be assigned to a Product Category. If there aren’t any Product Categories yet, click the Add link for Product Categories, enter a Title, and save.
2. Add a Product¶
Click on the Add link for Products. At minimum, enter a product category, Repo URL, and Title. It’s important that the Repo URL matches the one in your project’s cumulusci.yml file, because it’s how CumulusCI will find the right product in MetaDeploy.
Check the “Is Listed” box if you want the product to be shown in the MetaDeploy product listing. Leave it unchecked if you want the product to only be accessed by its URL.
Short Description will be shown on the card in the product listing. Description will be shown on the right side of the product’s main page. If you enter a Click Through Agreement text, users will be prompted to agree to it before running installation plans for this product. Users will be shown the Error Message in a modal dialog if there’s an error during installation.
2. Add a Product Slug¶
In order to be accessible by a URL, a Product must have a Product Slug. Click the Add link for Product Slugs. Enter a slug (which will be used in the URL) and select the corresponding product.
If a product has multiple slugs, older active slugs will redirect to the most recent active slug. This is useful if a product changes names.
3. Configure a plan in cumulusci.yml¶
Add a plans
section to your cumulusci.yml file like this:
plans:
install:
slug: install
title: Install
tier: primary
steps:
1:
flow: install_prod
This sets us up to publish the install_prod
flow to a Plan that will
be the primary (default) Plan for the Product and available with
/install
in the URL (from the slug).
4. Connect CumulusCI to MetaDeploy¶
This is a one-time setup task. In the MetaDeploy admin UI, go to the Tokens object (under Auth Tokens) and create one for your user.
In your terminal, run cci service connect metadeploy
. Enter the base
API url
(e.g. https://metadeploy_domain/admin/rest
and the token you
just created.
5. Publish the plan¶
Each time you’re ready to publish the Plans for a new version of your Product, run:
cci task run metadeploy_publish -o tag TAG -o dry_run True
substituting TAG with the name of the tag you want to publish. The
dry_run
flag will make it print out the steps that will be sent to
MetaDeploy without actually doing so. Once you’ve reviewed them, you
can run the same command for real:
cci task run metadeploy_publish -o tag TAG
This task will create a Version (unless it already exists), a Plan, a series of Steps for that Plan, and a Plan Slug (unless it already exists).
By default, all plans defined in cumulusci.yml will be published.
Specify the plan
option to publish one specific Plan:
cci task run metadeploy_publish -o tag TAG -o plan install
6. Test the installer¶
Run the installer to make sure it works as expected!