C1 CMS Versions supported

This package requires CMS version 6.3 or newer (Build: 6.3.0.0).

Pre-Installation Steps

The CM / CM setup with Cloud Publisher occurs in 3 places:

• GitHub (or Azure DevOps)
• CM node: C1 CMS running anywhere locally or remotely
• CD node(s): Azure Web Apps

We recommend that you start with the setup on GitHub / Azure DevOps, continue with it in C1 CMS and finally, on Azure.

On GitHub (or Azure DevOps), you are supposed to:

1. Create a repository
2. Allow Cloud Publisher to access the repository in one of the ways described below

Creating a repository

On GitHub (or  Azure DevOps), you need to create an empty repository.

Please follow the standard procedure for creating repositories on GitHub (or Azure DevOps).

You do not need to create a branch. Cloud Publisher will create a branch in this repository where the C1 website and changes will be pushed to and where the Azure Web App will deploy it from.

Authorizing Cloud Publisher to the repository

To allow Cloud Publisher to push changes to the repository, you need to grant it access there.

You can do it in one of the following ways:

• Using the username and password (only for accounts in Azure DevOps)
• Using an access token issued for a GitHub or Azure DevOps account
• Via SSH using public/private keys and associated certificates (only for CM nodes run on Windows earlier than Windows 10)

For security reasons we recommend either access tokend (or public/private keys (SSH) on earlier Windows versions) for authorization.

Authorization using the username/password

The simplest but least secure way is to generate and use the Git credentials for an Azure DevOps account, on whose behalf Cloud Publisher will push files to the repository.

1. Open the repository you are going to use in Azure DevOps
2. Click "Clone"
3. Make sure "HTTPS" is selected
4. Click "Generate Git Credentials"
5. Securely copy or make note of the username and password that appear.
   

Make sure the account in use has write access to the repository.

Authorization using an access token

You can make use of a personal access token (PAT) you have to generate in your GitHub / Azure DevOps account.

Please follow the standard procedure to generate a PAT on GitHub / Azure DevOps and make note of it once done.

Example of the token: f07926c1d297f53c8189148d5c770d4d10f8044e4

Installation steps

1. Log into the CMS Console as an administrator.
2. Go to the "System" perspective.
3. Open the folders “Packages” | “Available Packages” | " Orckestra.Azure".
4. Select " Orckestra.Azure.CloudPublisher" and click “Install”.
5. Complete the wizard.

Post-Installation Steps in C1 CMS

After you have Cloud Publisher installed, go ahead to:

1. configure Cloud Publisher,
2. configure C1 CMS for Cloud Publisher
3. and then do the first “push”.

Configuring Cloud Publisher

When configuring Cloud Publisher, you normally specify:

• an URL to the repository (in a format that may differ based on the authentication method chosen)
• a branch
• information required for authentication, one of the following:
  • the username/password
  • the access token
  • the paths to public key and private key files (only on the CM node run on Windows versions earlier than Windows 10)

The configuration is located at ~/Composite/InstalledPackages/Orckestra.Azure.CloudPublisher/web.config and you can access it from the “System” perspective in the C1 Console.

• Cloud Publisher’s configuration file
• Public and private key files (if used)

You can also choose to replace specific files with their versions to be used on Azure, for example, use a version of web.config on the CD different from that on CM.

If something goes wrong, you can always reset Cloud Publisher and try again.

Configuring with the username and password

1. Log in to the C1 Console as an administrator
2. From the “System” perspective, below “/” expand Composite > InstalledPackages > Orckestra.Azure.CloudPublisher
3. Edit web.config
4. Set the parameters following the example below

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <add key="Orckestra.Azure.CloudPublisher.GitRemoteUrl" value="https://github.com/MyAccount/C1LiveWebsite.git" />
    <add key="Orckestra.Azure.CloudPublisher.GitUsername" value="MyAccount" />
    <add key="Orckestra.Azure.CloudPublisher.GitPassword" value="MySuperSecretPassword123^&*" />
    <add key="Orckestra.Azure.CloudPublisher.GitBranch" value="published-website" />      
  </appSettings>
</configuration>

Where:

• GitRemoteUrl: is the URL to the repository; in the example above:
  • MyAccount: is the name of your account (it will be different in your case)
  • C1LiveWebsite: is the name of the repository (it will be different in your case)
• GitUsername: is the name of your account; in the example above it is “MyAccount” (it will be different in your case)
• GitPassword: is the password to your account; in the example above it is “MySuperSecretPassword123^&*” (it will be different in your case)
• GitBranch: is the name of a branch; in the example above it is “published-website” (it will be different in your case)

Configuring with the access token

1. Log in to the C1 Console as an administrator
2. From the “System” perspective, below “/” expand Composite > InstalledPackages > Orckestra.Azure.CloudPublisher
3. Edit web.config
4. Set the parameters following the example below

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <add key="Orckestra.Azure.CloudPublisher.GitRemoteUrl" value="https://github.com/MyAccount/C1LiveWebsite.git" />
    <add key="Orckestra.Azure.CloudPublisher.GitUsername" value="f07926c1d297f53c8189148d5c770d4d10f8044e4" />
    <add key="Orckestra.Azure.CloudPublisher.GitBranch" value="published-website" />      
  </appSettings>
</configuration>

Where:

• GitRemoteUrl: is the URL to the repository; in the example above:
  • MyAccount: is the name of your account (it will be different in your case)
  • C1LiveWebsite: is the name of the repository (it will be different in your case)
• GitUsername: is the access token; in the example above it is f07926c1d297f53c8189148d5c770d4d10f8044e4 (it will be different in your case)
• GitBranch: is the name of a branch; in the example above it is “published-website” (it will be different in your case)

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <add key="Orckestra.Azure.CloudPublisher.GitRemoteUrl" value="git@github.com:MyAccount/C1LiveWebsite.git" />
    <add key="Orckestra.Azure.CloudPublisher.PublicKeyPath" value="~/App_Data/sshkeys/mykey.pub" />
    <add key="Orckestra.Azure.CloudPublisher.PrivateKeyPath" value="~/App_Data/sshkeys/mykey" />
    <add key="Orckestra.Azure.CloudPublisher.GitBranch" value="live-website" />
  </appSettings>
</configuration>

Configuring C1 CMS for Cloud Publisher

There are a few other steps you may want to consider doing before publishing the website to the repository. They include some security settings and handle some limitations.

Preventing specific files from being published

By default, Cloud Publisher places its configuration file and the folder that may contain key files in .gitignore, which prevents these from being uploaded to the repository when changes are pushed.

Sample:

App_Data/sshkeys/
Composite/InstalledPackages/Orckestra.Azure.CloudPublisher/web.config

You can find .gitignore in the root directory of the website: ~/.gitignore

As the configuration file and key files may contain sensitive information (a password, a token), make sure to keep it in .gitignore.

Likewise, you can add other files and folders to .gitignore.

Replacing files when delivered on Azure

The deployment script supports replacement of files (for example, “web.config”) with their versions provided the latter follow specific formats in their naming (for example, “web.Prod.config”) and a corresponding environment parameter is set on Azure (for example, “prd”).

(The script comes with Cloud Publisher and is run on Azure when the website is deployed from GitHub/VSTS to an Azure Web App. It is available on the CM node at ~/.deploy/ local-website-deployment.ps1.)

Each parameter maps to a specific suffix added to the file name. The file with this name will be used instead of its counterpart with the same name but without the suffix.

Here is the list of parameters and their corresponding file suffixes as specified in the script:

"dev" { ("*.Debug.*") }
"qa" { ("*.Test.*", "*.Debug.*") }
"int" { ("*.Test.*", "*.Debug.*") }
"stg" { ("*.Release.*", "*.Prod.*") }
"prd" { ("*.Prod.*") }
"prd-cm" { ("*.Prod.*") }
"prd-cd" { ("*.Prod.*") }

For example, if the deployment environment parameter on the Azure Web App is set to “dev”, then files with the “Debug” suffixes will replace their counterparts without the suffix during the deployment: web.Debug.config > web.config

Limiting access to the C1 Console on CD nodes

The CM/CD setup with continuous deployment suggests that you will make changes on the CM node and publish those to CD nodes.

It makes sense to deny access to the C1 Console on the CD nodes.

To do so, use the C1 feature to limit access to the C1 Console by creating an “environment-aware” configuration file to be deployed on the CD nodes instead of the original one:

1. Go to ~/App_Data/Composite/Configuration.
2. Make a copy of the file C1ConsoleAccess.xml.
3. To the original file name, append the suffix that maps to the deployment environment you are going to use on CD nodes, for example, C1ConsoleAccess.Prod.xml (that maps to the “prd” or “prd-cd”environment).
4. Edit this file copy (C1ConsoleAccess.Prod.xml).
5. Change the “C1ConsoleAccess” parameter to “false”: <C1ConsoleAccess enabled="false">
6. Save the file.

When the website will be deployed from the repository to an Azure Web App, the original C1ConsoleAccess.xml (with “C1ConsoleAccess” set to “true”) will be replaced with C1ConsoleAccess.Prod.xml (with “C1ConsoleAccess” set to “false”).

Publishing the website to the repository (the first push)

Before you set up the deployment on Azure, make sure to do the first push of the CM website to the repository. As the entire website gets published during the first push, this might take up to a few minutes depending on your connection. The following pushes are normally instant as only changes get published.

To publish the website to the repository:

1. Log in to the C1 Console as an administrator
2. From the “Content” perspective, select “Cloud Publisher” and click “Open Publisher”
3. Click “Publish to Cloud”.

Post-Installation Steps on Azure (CD Nodes)

To finalize the setup with Cloud Publisher, you need to create an Azure Web App, configure a few parameters in its Application Settings and set it up for continuous deployment from GitHub.

Creating an Azure Web App

To create a new Web App on Azure:

1. Log in to the Azure Portal
2. Create an App Service of the type “Web App”.
3. Specify the name and resource group of your choice
4. Make sure to select one of the paid service plans.

Once the Web App has been created, go on to configure it.

Configuring the Azure Web App

The configuration of the Azure Web App as a CD node includes:

• Setting a few parameters in its Application Settings
• Setting up the source of the continuous deployment

Application Settings

For the Web App configuration:

1. In the Azure Portal, open the Web App.
2. On the “Application Settings” tab, enable the “Always On” setting.
3. Below “Application settings”, add the following settings.
4. Save the settings

Deployment Setup

Finally, set the Web App to get continuous deployment from a GitHub or Azure DevOps repository where you push changes from your CM node.

1. In the Azure Portal, open the Web App.
2. Below “Deployment” on the “Deployment Options” tab, choose “GitHub” or "Azure DevOps" as the deployment source.
3. Choose the account authorized to access the repository and organization.
4. Choose the repository and the branch – those used by Cloud Publisher to push changes to from the CM node.
5. Follow other steps of the wizard to complete the setup.

Once the deployment setup is finished, the deployment will start automatically. And the website will be available in a few moments as a Web App.

Custom Domains

You can configure custom hostnames to your Web Apps via the Azure Portal: App Services / <Your Web App> / Settings / Custom Domains. Please follow the standard procedure for configuring custom hostnames for Azure Web Apps.

To avoid unnecessary downtime with your live website, you may want to look into making use of TXT record to make Azure accept your hostname binding. Please see the section “Migrating a live custom hostname without any downtime” at “Custom hostname at App Service”.

Logging and Maintenance

There are two places where you can monitor the work of the setup and look for errors if any:

• C1 CMS as a CM node
• The Azure Web App as a CD node

Logging and diagnostics in C1 CMS

Cloud Publisher can catch and present configuration and publication errors and exceptions quite verbosely in its view.

Configuration errors will appear when you:

1. Open Cloud Publisher in the C1 Console
2. Publish changes to the cloud

Apart from this internal Cloud Publisher diagnostics feature, you can also check C1 CMS’s Server Log.

Please see “Logging” for more information about working with logs in C1 CMS.

Resetting Cloud Publisher

If something goes wrong, for example, when opening Cloud Publisher in the C1 Console or during the first push, you can reset Cloud Publisher and try the failed operation again.

To reset Cloud Publisher:

1. Close any tab with Cloud Publisher open in the C1 Console.
2. Delete the “.git” folder in the root directory of the website.
3. Point Cloud Publisher to an empty branch or a non-existing branch via its configuration.

Note: The “.git” folder is hidden by default. You may want to unhide it before Step 2.

For Step 3, you can either clear the branch on GitHub, or edit the Cloud Publisher configuration and change the “GitBranch” parameter to a non-existing branch.

Logging and diagnostics in Azure Web Apps

Azure Web Apps come with its own logging, diagnostics and development tooling via the Kudu portal.

To see the deployment logs for your Web App:

1. Launch the Kudu console: Your Web App / Developer tools / Advanced Tools / Go
2. Open the debug console of your choice: CMD or PowerShell
3. Navigate to /site/deployments. One or more hexadecimal named folders will exist here.
4. Open the one with the latest time stamp.
5. Edit the file log.log

The Kudu portal also gives access to event logs, IIS logs, the file system on the server etc.

Resetting the deployment source

If you want to reset or change the deployment source in your Web App:

1. Open the deployment options: Your Web App / Deployment / Deployment Options
2. Click “Disconnect” and confirm your choice (“Yes”)

This will remove the current deployment source form the Web App and you will be able to redo the deployment setup.

C1 Publication Scheduler Setup

By default, workflows to publish/unpublish data are ignored in Git.
To enable an internal C1 publication scheduler, replace the following line in the file ".gitignore"

/App_Data/Composite/ApplicationState/

App_Data/Composite/ApplicationState/*
!App_Data/Composite/ApplicationState/SerializedWorkflows/

Version info

Current version

1.0.7

Package ID

0ef8c56d-6774-4ca7-b0fa-cf9a44c86f86