Exporting and importing custom themes and site configuration

You can use the portal commands in the toolkit CLI to replicate changes from one Developer Portal instance to another. You might want to use these commands to copy your themes or a configuration change, from a staging environment to a production environment.

Before you begin

To complete this scenario, you must have a staging Developer Portal and a production Developer Portal enabled. You must have administrator access, and the permission settings:manage, to both to complete this scenario. The tutorial Creating the Portal explains how to enable the portal if you have not already done so.

About this scenario

In this scenario, on your staging Developer Portal, you create a theme and make some configuration changes. Then, you use the toolkit CLI to replicate the changes on your production Developer Portal.

This scenario takes you through the following steps:
  1. Create a custom theme on the staging Developer Portal.
  2. Add a field to an application content type to change the site-config on the staging Developer Portal.
  3. Use the cli to export the custom themes and site-config on the staging Developer Portal.
  4. Use the cli to import the custom themes and site-config on the production Developer Portal.

Create a custom theme on the staging Developer Portal

  1. Log in to your staging Developer Portal as an administrator.
  2. If the administrator dashboard isn’t displayed, click Manage to display it.
  3. Click Appearance > Generate sub-theme. The Generate sub-theme window is displayed.
  4. Enter a Sub-theme name, and select CSS for the Sub-theme type. (If you prefer, you can select SCSS, but this extension to CSS is for advanced theme developers, and isn’t covered by this scenario.)
    Generate subtheme window.
  5. Select the Default template to base your sub-theme on. You can create a sub-theme based on a color template. However, for this scenario you use the default connect_theme template.
  6. Click Generate.
  7. Download the generated sub-theme to a location of your choice, and extract all the files from the .zip file.

On your computer, navigate to the files that you extracted. Find the overrides.css file in here banka_theme/banka_theme/css/overrides.css. You can now customize the overrides.css file.

  1. Open the overrides.css file in your chosen editor.
  2. Customize your sub-theme by entering the following elements into the overrides.css file: 
    /* Body of the home page */
body.path-frontpage.contexthome {
  color: #152935;
  background-color: #d1f0f7;
}

/* Header of the home page */
.navbar {
  background-color: #a0a0a0;
}

/* Footer of the home page */
footer.footer {
background-color: #dee0e2;
}

footer.footer ul.nav > li > a {
color: #454A4C;
}
    Copy the given code block into your css file
  3. Save the overrides.css file.

You can now install and enable your customized theme.

  1. After you finish updating the overrides.css file, compress all the theme files back into the .zip sub-theme file that you downloaded originally.
  2. In the Developer Portal, click Appearance > Install new theme. The Install new theme window is displayed.
  3. In Upload a module or theme archive to install click Browse, and navigate to your newly updated compressed theme file.
  4. Click Install to install the theme onto your site.
  5. Click Enable newly added themes, and find your new theme in the list of Disabled themes. Click Enable and set as default to set your new custom sub-theme as the default theme for your site.
  6. Return to the Developer Portal home page by clicking Back to site. You can now see your custom theme.
    The home page with the updated theme

Add a field to an application content type to change the site-config on the staging Developer Portal

  1. Log in to your staging Developer Portal as an administrator.
  2. If the administrator dashboard isn’t displayed, click Manage to display it.
  3. Click Structure > Content types > Application > Manage fields.
  4. Click + Add field.
  5. In Add a new field, select Text (plain, long). Enter Company name as the label title.

    A screen shot of the add field page

  6. Click Save and continue.
  7. Leave the Allowed number of values set to 1 and click Save field settings.
  8. Click Save field settings. You can now see your new field.

    New field now showing in list

Use the toolkit CLI to export the custom themes and site-config on the staging Developer Portal

  1. Log in to the management server. 
    apic login --server management_server --realm realm --username org_username --password org_password
    For example,
    apic login -s api.stagingexample.com --realm provider/default-idp-2 --username ibm --password Qwerty123£

    For more information about variable options, see Logging in to a management server.

  2. Export your custom themes.
    The custom-theme:create-export command creates an export task against the portal of the specified catalog and org. The command then polls the status of the task until it has FINISHED and the artifacts are streamed back.
    Note: The command continues to poll until the maximum polling time of 15 minutes is reached. At which point you can use the commands custom-theme:get-export-status and custom-theme:get-export to get the status and potentially an artifact.
    apic --mode portaladmin custom-theme:create-export --catalog name/id --org name/id --server management_server
    • The theme .tgz is saved to the directory in which you ran the command.
    • The saved .tgz has the format custom_theme_createExport-20200217134637.tgz.
    • You can save your exports into your change control management system.
    For example,
    apic --mode portaladmin custom-theme:create-export --catalog dev --org ibm --server api.stagingexample.com
  3. Export your site config.

    The site-config:create-export command creates an export task against the portal of the specified catalog and org, the command then polls the status of the task until it has FINISHED and the artifacts are streamed back.

    apic --mode portaladmin site-config:create-export --catalog name/id --org name/id --server management_server
    • The site config .tgz is saved to the directory in which you ran the command.
    • The saved .tgz has the format site_config_createExport-20200217134637.tgz.
    • You can save your exports into your change control management system.
    For example,
    apic --mode portaladmin site-config:create-export --catalog dev --org ibm --server api.stagingexample.com

Use the toolkit CLI to import the custom themes and site-config on the production Developer Portal

  1. Log in to the management server. 
    apic login --server management_server --realm realm --username org_username --password org_password
    For example,
    apic login -s api.productionexample.com --realm provider/default-idp-2 --username ibm --password Qwerty123£

    For more information about variable options, see Logging in to a management server.

  2. Import your custom themes.
    The custom-theme:create-import command uses the supplied .tgz file to import the custom themes into the portal of the specified catalog and org. The command then polls the status of the task until the task has either FINISHED successfully, or failed because of an error.
    Note: The command continues to poll until the maximum polling time of 15 minutes is reached. At which point you can use the command custom-theme:get-import-status to get the status of the import.
    apic --mode portaladmin custom-theme:create-import --catalog name/id --org name/id --server management_server /PATH/TO/THEME/TGZ
    For example,
    apic --mode portaladmin custom-theme:create-import --catalog prod --org ibm --server api.productionexample.com C:/users/example/desktop/custom_theme_createExport-20200217134637.tgz
  3. Import your site config.

    The site-config:create-import command uses the supplied .tgz file to import the site config into the portal of the specified catalog and org. The command then polls the status of the task until the task has either FINISHED successfully, or failed because of an error.

    apic --mode portaladmin site-config:create-import --catalog name/id --org name/id --server management_server /PATH/TO/CONFIG/TGZ
    For example,
    apic --mode portaladmin site-config:create-import --catalog prod --org ibm --server api.productionexample.com C:/users/example/desktop/site_config_createExport-20200217134637.tgz

What you did in this scenario

In this scenario, you created a theme and changed the configuration on your staging Developer Portal. Then, you used the toolkit CLI to replicate the changes on to your production Developer Portal.

You can now see the changes that you made on your production Developer Portal.