CMS for SPAs (2 of 4): Save the Content Authors

In Part 1 of the series CMS for SPAs: Are Single Page Applications and Headless CMS a Slam Dunk?  we looked at the trend toward Single Page Applications (SPA) and Headless Content Management Systems (CMS) in general. SPA applications are becoming the de facto way to build web-based applications and sites. Headless CMS is a decoupled, API-first approach to content management that aligns neatly with SPA architecture. Further, the decoupled nature of the architecture makes content more reusable (multi-channel) and completely divorces development from the CMS allowing for greater freedom and agility for developers. While these can be seen as major wins, several developer and DevOps issues remain while others have been created. Further, most of the headless CMS solutions available today set content authors back nearly 20 years in terms of content editing and workflow tooling and practices.

In this installment, we’ll focus on the various ways content authors have been impacted by headless CMS and how Crafter CMS addresses these issues to provide authors with true headless CMS support for SPA applications.

Authors Forced into the Wayback Machine

Clumsy tools and processes for editing, reviewing and testing content offered by headless CMS platforms have content authors, the primary stakeholder of CMS platforms, wondering if they fell asleep and woke up back in the early 2000’s. Let’s take a look at some of the issues facing authors in the Headless CMS space.

Preview and In-Context Editing

Authors are accustomed to easy-to-use tools that enable them to visually locate, edit and publish content in websites or applications. Many headless CMS platforms provide no way for authors to preview their work prior to publishing it. Authors are forced to change content via content entry forms that are completely disconnected from the presentation.  In order to see what the content will look like on the website or in the application, they must publish the content. No author should be forced to work with slow and clumsy deployment iterations just to ensure their content fits and looks good on destination channels. That’s a major step backward.

Some CMS vendors and practitioners argue that by completely obscuring the presentation from the authors, content gets created in a fashion that is naturally more reusable. That’s not necessarily accurate. Content is more reusable when stored and transmitted in a fashion that is divorced from presentation — but that does not mean authors should be forced to ignore how their content will be presented on key channels. As the saying goes: “the medium is the message.” To most authors, the layout is just as important as the content itself. Authors need tools in their headless CMS that are on the level of the tooling they have become accustomed to with more traditional CMS platforms.

Delivering Editing and Preview tools for SPAs

Crafter CMS gives authors a full, interactive in-context preview and editing experience within SPAs. Authors have exactly the same tooling they have become accustomed to with traditional CMS.

Crafter’s preview capability can sit in front of any web-based application. The specific technology does not matter. Crafter’s preview and editing tools are front-end agnostic. One of the key reasons Crafter is able to do this is that Crafter CMS has always separated authoring and delivery into distinct but integrated components. We’ve been assuming a decoupled architecture for years.

Authors are the main users of any CMS and their needs must be properly addressed. A solid authoring experience with true in-context editing and preview is table-stakes for any headless CMS.

Personalization of Headless / API based Content

Another area that Headless CMS platforms have impacted authors is support for targeted/personalized content. Content authors need to be in control of the rules that drive the right content to the right people at the right place and time.

To support personalization your headless CMS must support the following two capabilities:

  • The ability to design, configure or code business rules behind the services.
  • The ability to preview content and functionality driven by personalization rules prior to publishing.

To date, most headless CMS platforms are simple repositories of content that are retrievable by API call. These systems offer no ability to create rules that can be executed based on the request parameter variations and characteristics of the requester.

Further, based on the previous section, we already know that most Headless CMS platforms don’t support pre-publishing preview of content — let alone the ability to preview content and experience as it would appear in different scenarios. There is little point in writing rules or variations of content without the means to properly test them prior to publishing.

Delivering Personalization for SPAs

Crafter CMS provides excellent support for targeted and personalized content even when content is delivered in a headless environment. Authors can configure scenarios and simple rules via the UI or leverage sophisticated rules built-in scripting languages by the development staff. Further, Crafter CMS provides rich preview tools that allow authors to impersonate different users and other types of content consumers within the authoring tools so that content and scenarios can be properly tested well before they are published.

The Need for Real Versioning and Branching

Most CMS platforms (traditional and headless) support some kind of basic versioning.  For the most part that support extends only to a single content item. Each item has its own history.  There is no way to look at the entire content collection at it existed at a specific point in time. That can be a major challenge for authors if they need to reference a previous campaign or support an audit.  The ability to maintain a version history is paramount and rudimentary versioning is typically not enough.

Another key feature that is missing from CMS platforms is the ability to support branches.  Branches allow us to work on different variants of the content at the same time. A branch not only allows concurrent work but it also enables us to sync up variants when it’s appropriate.  This extraordinarily important to authors who are supporting a re-branding or a major content overhaul. Most CMS systems can’t support that without content freezes and manual “double publishes”

Delivering Real Versioning and Branches

Crafter CMS’ repository is based on Git. Git provides authors using Crafter with a versioning system that is multi-file — meaning that an author can see the entire content collection at any moment in time in its history.  Git also provides support for branches which means that authors using Crafter can support difficult operational scenarios like re-brands without any content freezes or extra publishing.

Content freezes and Other Business Interruptions

New features, design refreshes, and integrations are a way of life for today’s customer-focused market. Agility and innovation at scale and speed are key to winning in this competitive landscape. Wherever you have innovation you will find developers and development process along with its procedures, tools, and environments. Businesses want innovation without disruption. Unfortunately with most CMS platforms, due to their architecture, business disruptions are exactly what content authors and other business users end up with. Outages and complicated deployment processes along with content freezes are realities for most innovative organizations use CMS.

When we look at the reason for the disruptions to the business activity we find that the development and testing process requires that we maintain independent testing environments and that we do code deployments. It’s during this maintenance activity that authors are often told to “hold off” or “stay out of the system.” Content freezes waste time and money and they hurt the business. SPAs and Headless CMS platforms do nothing to solve this problem.

In order to get content to lower environments like Dev, QA, and Test we have to take an export of Production. Authors need to stop working during exports. Imports on the lower environments are no fun either. Every environment needs to be painstakingly and individually updated. When coding is complete it has to be rolled out. Once again authors need to refrain from using the system. Complicated deployment procedures and models can take hours, days and in some cases even weeks. More valuable time and money are wasted.

Uninterrupted Business Activities with SPAs

Crafter CMS has an architecture that is different from other CMS platforms. Crafter is designed and implemented with repository technology specifically designed to handle these processes with minimal effort and friction. Crafter CMS leverages Git at its repository layer. In contrast to CMS platforms that rely on databases or JCR repositories that rely on exports and imports that require outages to sync data between environments, Crafter’s repository is meant to be distributed and as such it natively supports syncing between related stores. We call this push button process “Code Forward, Content Back”™ Crafter CMS allows developers along with their tools and process to live and work in harmony with content authors. This enables collaboration together without interruption and with much less friction so that a greater level of innovation and ongoing operations can all take place at the same time.

Conclusion

The net-net of it is simple. Regardless of any improvement in content reusability or ease of development, authors need to be able to do their jobs easily and efficiently without interruption. New tools and approaches need to move the ball forward, not back. Unfortunately for authors, headless CMS has lost major ground.

Some of these shortcomings can be overcome with time but all of the shortcomings we looked at here are architectural in nature. Architecture changes are the most difficult and time-consuming to make. You don’t have to wait for your current headless CMS to correct course. Crafter CMS is an open source headless CMS with the right architecture to take full advantage of the benefits of SPA applications provided to end users and developers while giving authors the tools, process and uninterrupted service they need to succeed.

What has your experience been working with SPAs and your CMS?

CMS for SPAs (1 of 4): Are Single Page Applications and Headless CMS a Slam Dunk?

From web-based applications like Gmail, Instagram, and Google Maps to websites like The New York Times and Facebook, real-world examples of Single Page Applications (SPA) are everywhere you look. Developers have been turning to SPA frameworks and architectures to create better, more usable, richer applications for their users.

Nearly every Content Management System (CMS) out there purports to support SPA frameworks and architectures. In this blog series, we’ll look at SPA use in the CMS space to learn more about what’s working, what’s not and what we can do about it. Let’s jump in.

SPAs are web-based applications built with rich UI frameworks that run client side and use partial page updates rather than full page refreshes to update data, content, and UI. SPAs have several advantages:

  • Great user experience: SPAs make the user experience more fluid with rich UI interactions that leverage asynchronous calls to the server for data and partial page refreshes.

  • Clean architecture: SPAs architecture promotes a clean separation of the frontend application and backend services and data. This approach makes development faster and more flexible.

  • Great frameworks: There are a lot of great frameworks that make developing SPAs faster and easier including React, Angular, Vue and others.

In the CMS space, SPA applications have been a win for developers but content authors have taken a major hit.


Developers have been keen to adopt SPA technology and CMS vendors have quickly responded with support for Headless CMS (also known as Content as a Service [CaaS]) support.

This shift has been highly promoted by CMS vendors because it has a number of advantages with respect to content management. Returning content as JSON or other presentation-less formats makes content more reusable within and across delivery channels. More importantly, by removing the consuming application from the CMS, the approach seems to solve one of the major challenges in the CMS space: development. It’s no secret that most developers have little interest in working within the toolsets and constraints of a CMS. Developers want control over their tools, frameworks, and process. CMS platforms are notoriously framework laden and don’t integrate well with DevOps tools and process.

The headless approach completely and neatly decouples development and content production workflows. On the surface, the headless approach appears to be a perfect evolutionary step for CMS. New delivery channels and integration opportunities show up all the time. In a customer experience driven market, anything that aids development and reduces time to market is seen as a winner.

However, the reality is that decoupling the CMS from the consuming application does not solve long-standing challenges such as refreshing content in lower environments — in fact, it complicates them. Worse, complete decoupling creates new problems. While software development and content production workflows are best divorced, their products: the code and content are not. There is a time/version specific relationship between the data model, the content and the code at any given moment. To illustrate the point: it’s often not possible to “point” an older version of an application at a newer version of the content and vice versa. It’s extremely difficult to troubleshoot or perform legal and regulatory audits without this capability. Yet, with the clear benefits of better products, a cleaner deployment architecture and faster, easier development in mind, the remaining issues are either unrecognized or a compromise many developers are willing to take. For developers, the SPA and headless approach have largely been a win.

The ironic and unfortunate “dirty little secret” in the CMS space of late is that the biggest losers of the headless CMS movement have been the content authors, CMS’s main stakeholder.

Today’s headless CMS options have the following drawbacks for authors:

  • There is no preview. Authors are used to in-context editing and preview. With headless, they are back to working in forms with no preview and are left to hope and a cumbersome process to ensure that the content will present properly.
  • There is no personalization. Marketers want to be able to target and personalize their messaging to the audience. Most headless CMS platforms don’t give them the capability to describe and execute targeting rules much less test and preview the various scenarios.
  • DevOps are still not supported: Despite investments in new technology, tools and process content authors see zero improvements in DevOps activities related to feature releases. Content freezes and outages are still commonplace during feature deployments with headless CMS.

It doesn’t have to be that way! With the right CMS architecture and platform content authors, developers and DevOps can work together on SPA based sites and applications at speed with the tools and processes they are accustomed to (like in-context editing) without stepping on each other’s toes.

A Better Approach to SPAs, CMS and DevOps

Crafter CMS is an open source CMS platform that takes a completely different approach to headless CMS, SPA development and DevOps. Crafter CMS has a very different architecture from traditional CMS platforms that are monolithic and rely on SQL databases and JCR repositories.

Crafter’s architecture is modular, flexible, and completely elastic with a repository and deployment design that is shared-nothing and based on Git. This architecture enables Crafter CMS the flexibility to support content authors, developers and DevOps to collaborate together to build and release new experiences with minimal friction while using the tools and workflows that work best for them.

Crafter CMS is an API first CMS that is:

  • UI agnostic and can support development and editing and preview for any UI framework
  • Capable of supporting rich, personalized headless CMS content
  • Git-based to support your development frameworks, tools, and process in a way that separates development and content production workflows without needing to separate the deployable (code and content) artifacts.

Conclusion

SPA applications combined with decoupled, headless CMS offer significant advantages in terms of end-user experience, development, and deployment. However, it’s clear that headless is not a silver bullet. Completely divorcing the CMS and the consuming application or site creates significant challenges for DevOps, support and other departments. More importantly, the SPA/headless pairing has left authors out in the cold by taking away the process and tools they have become accustomed to over the past decade.

These shortcomings can be addressed with a new breed of CMS architecture. What’s needed is a flexible headless CMS that support proper authoring tools and process regardless of front-end technology. Moreover, we need a CMS that embraces and integrates development tools and process rather than shunning them. That’s exactly what we’ve set out to do with Crafter CMS. Stay tuned for our next blogs in this series where we’ll dive deeper into these concerns and their solutions.

What has your experience been working with SPAs and your CMS?

Integrating Crafter CMS with BitBucket for Better DevOps

Content authoring and software development are both a major part of producing today’s digital experiences. Unfortunately, development support is not something traditional CMS platforms handle very well at scale. Crafter CMS, a 100% open source CMS platform that includes a Git-based repository designed to handle not only authoring but also DevOps seamlessly.

Many development teams use cloud hosted developer platforms like Bitbucket to assist with their development process.   Crafter’s Git based CMS supports developers working against remote repositories like Bitbucket, Gitlab, Github, and others.

By supporting this kind of architecture, Crafter provides a very simple way to flow code forward from a developer and her team all the way up through the CI/CD process to production.  We also support a very simple way for any developer or any environment to easily update itself with the latest content from production.  DevOps and CMS have never been easy — until now. Crafter CMS’s CODE FORWARD, CONTENT BACK™ process makes this process simple and allows you to leverage awesome platforms like Bitbucket to support your team with the tools they know and love.

In this article, I’ll show you how to create a new project in Bitbucket and then start a new project in Crafter CMS in a way that connects to Bitbucket as an upstream remote repository so that Bitbucket can be used to support your development process with your CMS related development! 

Create a New Project and Connect it to BitBucket

Step 1: Create a Project in Bitbucket

Figure 1: Create a project in Bitbucket 

  1. Create project
  2. Enter your project name
  3. Choose your security level
  4. Do not initialize the repository with a readme
  5. Click create site

Once your repository is created you will see a screen similar to the one below.  You want to make note of the Git URL for the site.  You will need this URL in the next step.

Figure 2: New Project in Bitbucket 

Step 2: Create Your Project In Crafter Studio

Next, you want to log in to Crafter Studio as the admin user. The admin user has the rights to create new projects (called sites.) Click Create Site.

Figure 3: Create site via Crafter Studio

Clicking Create Site will present you with the Create Site dialog. This dialog changes depending on what you choose. Below is an example of the dialog filled out in a way that creates your project locally, set the Bitbucket repository as its upstream remote and pushes the initial project contents to the upstream repository.

Let’s walk through each part of the dialog:

Figure 4: Create Site Dialog in Crafter Studio, populating a bare upstream Git repository.

  1. The first thing you need to do is give your site an ID. The ID itself doesn’t matter in a sense. It doesn’t need to match anything per se, technically speaking the only requirement is that it’s unique. That said, it’s a best practice to provide an ID that is meaningful/recognizable to the team. If your website is called Sweet.com a good ID might be “sweetdotcom”
  2. Next, because you plan to connect this project to an upstream repository you want to click the plus (+) on “Link to upstream remote Git repository” This will open a number of new fields.
  3. In the “Remote Git Repository Name” field you want to provide a repository name that makes sense. It’s common to use “origin” or “upstream.”
  4. In the “Remote Git Repository URL” field you must provide the link to the Git repository discussed in Step #1:  https://russdanner@bitbucket.org/russdanner/mysweetdotcom.git
  5. Provide your credentials in Git Remote Repository Username and Password
  6. Choose the option: “Create site based on blueprint then push to  remote bare repository.” This means that Crafter Studio will create a new site based on the blueprint you choose, link the remote repository as an upstream and then once the blueprint is installed in the local Repositories it will be pushed automatically to the upstream remote.
  7. Choose your blueprint. There are several out of the box blueprints provided by default. Choose one of these or one of your own. For our example, we’ll choose Editorial which is the simple Article style website/project template.
  8. Click Create. Crafter CMS will create the local repositories, Solr core and internal data structures required to support the project and install the blueprint. Once complete it will connect to the upstream and push the contents of the Sandbox repository to the remote.

Figure 5: Site is created and the contents of the sandbox are automatically pushed to the upstream repository.

Step 3: Check Bitbucket to Make Sure Your Site is There

Go back to your Bitbucket project and refresh the screen.  You will see the contents of your CMS project in the repository.

Your project is there!

Pushing and Pulling from the Remote Repository

Crafter Studio helps you manage and interact with your remote repositories via the user interface and via API.  Using Crafter Studio’s remote repositories console, you can add any remotes to the project you like and sync with them via pull and push operations at any time.

Now you are ready to set up your entire development process and CI/CD automation.

To learn more about how this is configured check out these blogs:

Creating a Project in Crafter CMS Based on an Existing Bitbucket Project

Let’s consider for a moment that you’re a new developer joining the team. The topology above is already set up and you just want to get a local environment up and going. Simple. Follow these instructions.

  1. Install Crafter Studio locally (Source build or Binaries bundle)
  2. Login as Admin
  3. Click Create Site
  4. Fill out the Create Site Form as in a similar fashion described in Step 2, except this time you chose the option to create your site based on an existing upstream repository. This can be your team’s branch or your own fork. The exact workflow is up to you.

 

Conclusion

Platforms like Bitbucket that support agile development and CI/CD are helping bring best practices to the enterprise with easy to use tools that make implementing these activities simple.

Crafter CMS’s Git-based repository and DevOps integration make it simple to build CMS and content related projects while adhering to DevOps best practices and leveraging today’s best development platforms.

“Code Forward, Content Back” is a trademark of Crafter Software Corporation

Integrating Crafter CMS with GitHub for Better DevOps

Content authoring and software development are both a major part of producing today’s digital experiences. Unfortunately, development support is not something traditional CMS platforms handle very well at scale. Crafter CMS, a 100% open source CMS platform that includes a Git-based repository designed to handle not only authoring but also DevOps seamlessly.

Many development teams use cloud hosted developer platforms like Github to assist with their development process.   Crafter’s Git based CMS supports developers working against remote repositories like Github, Gitlab, Bitbucket, and others.

By supporting this kind of architecture, Crafter provides a very simple way to flow code forward from a developer and her team all the way up through the CI/CD process to production.  We also support a very simple way for any developer or any environment to easily update itself with the latest content from production.  DevOps and CMS have never been easy — until now. Crafter CMS’s CODE FORWARD, CONTENT BACK™ process makes this process simple and allows you to leverage awesome platforms like Github to support your team with the tools they know and love.

In this article, I’ll show you how to create a new project in Github and then start a new project in Crafter CMS in a way that connects to Github as an upstream remote repository so that Github can be used to support your development process with your CMS related development! 

Create a New Project and Connect it to Github

Step 1: Create a Project in Github

Figure 1: Create a project in Github 

  1. Select Blank Project to create a bare project
  2. Enter your project name
  3. Provide a project description
  4. Choose your security level
  5. Do not initialize the repository with a readme
  6. Click create site

Once your repository is created you will see a screen similar to the one below.  You want to make note of the Git URL for the site.  You will need this URL in the next step.

Figure 2: New Project in Github 

Step 2: Create Your Project In Crafter Studio

Next, you want to log in to Crafter Studio as the admin user. The admin user has the rights to create new projects (called sites.) Click Create Site.

Figure 3: Create site via Crafter Studio

Clicking Create Site will present you with the Create Site dialog. This dialog changes depending on what you choose. Below is an example of the dialog filled out in a way that creates your project locally, set the Github repository as its upstream remote and pushes the initial project contents to the upstream repository.

Let’s walk through each part of the dialog:

Figure 4: Create Site Dialog in Crafter Studio, populating a bare upstream Git repository.

  1. The first thing you need to do is give your site an ID. The ID itself doesn’t matter in a sense. It doesn’t need to match anything per se, technically speaking the only requirement is that it’s unique. That said, it’s a best practice to provide an ID that is meaningful/recognizable to the team. If your website is called Sweet.com a good ID might be “sweetdotcom”
  2. Next, because you plan to connect this project to an upstream repository you want to click the plus (+) on “Link to upstream remote Git repository” This will open a number of new fields.
  3. In the “Remote Git Repository Name” field you want to provide a repository name that makes sense. It’s common to use “origin” or “upstream.”
  4. In the “Remote Git Repository URL” field you must provide the link to the Git repository discussed in Step #1: https://github.com/russdanner/mysweetdotcom.git
  5. Provide your credentials in Git Remote Repository Username and Password
  6. Choose the option: “Create site based on blueprint then push to  remote bare repository.” This means that Crafter Studio will create a new site based on the blueprint you choose, link the remote repository as an upstream and then once the blueprint is installed in the local Repositories it will be pushed automatically to the upstream remote.
  7. Choose your blueprint. There are several out of the box blueprints provided by default. Choose one of these or one of your own. For our example, we’ll choose Editorial which is the simple Article style website/project template.
  8. Click Create. Crafter CMS will create the local repositories, Solr core and internal data structures required to support the project and install the blueprint. Once complete it will connect to the upstream and push the contents of the Sandbox repository to the remote.

Figure 5: Site is created and the contents of the sandbox are automatically pushed to the upstream repository.

Step 3: Check GitHub to Make Sure Your Site is There

Go back to your Github project and refresh the screen.  You will see the contents of your CMS project in the repository.

Your project is there!

Pushing and Pulling from the Remote Repository

Crafter Studio helps you manage and interact with your remote repositories via the user interface and via API.  Using Crafter Studio’s remote repositories console, you can add any remotes to the project you like and sync with them via pull and push operations at any time.

 

 

 

Now you are ready to set up your entire development process and CI/CD automation.

To learn more about how this is configured check out these blogs:

Creating a Project in Crafter CMS Based on an Existing GitHub Project

Let’s consider for a moment that you’re a new developer joining the team. The topology above is already set up and you just want to get a local environment up and going. Simple. Follow these instructions.

  1. Install Crafter Studio locally (Source build or Binaries bundle)
  2. Login as Admin
  3. Click Create Site
  4. Fill out the Create Site Form as in a similar fashion described in Step 2, except this time you chose the option to create your site based on an existing upstream repository. This can be your team’s branch or your own fork. The exact workflow is up to you.

 

Conclusion

Platforms like GitHub that support agile development and CI/CD are helping bring best practices to the enterprise with easy to use tools that make implementing these activities simple.

Crafter CMS’s Git-based repository and DevOps integration make it simple to build CMS and content related projects while adhering to DevOps best practices and leveraging today’s best development platforms.

“Code Forward, Content Back” is a trademark of Crafter Software Corporation

Integrate Crafter CMS with Jenkins to Automate DevOps: Code Forward, Content Back Process

Great DevOps helps us build better software products faster. One of the key elements of DevOps is automation within the development process across lower development environments.  Jenkins, Bamboo, Travis and many others platforms like them are used by DevOps teams to help automate the process of Continous Integration and Continous Delivery (CI/CD). To a large degree, real support for CI/CD and agile development is something that is woefully missing in Content Management, a core component of digital experience platforms.  The toolset and the architecture of today’s content management platforms make it difficult, sometimes near impossible to support let alone automate. How easy is it for your team to take content from the Production CMS and update content in lower environments like Dev, QA?  How easy is it to roll out new features?  Often times this process is not only laborious for the DevOps team, it also halts the content authoring process.    Crafter CMS’s, an open source CMS Git-based repository and Java/Spring and Groovy-backed stack are a game changer in this regard.  Further, Crafter integrates directly into to your CI/CD process.  In this article, using Jenkins as our example we’ll demonstrate how you can connect your production CMS to your developer workflow to facilitate Code Forward, Content Back(TM) workflow.
You can read more about this process in detail here:

Although our example is based on Jenkins, the scripts and flow used in this blog are applicable to nearly any automation

Understanding Where Code Forward, Content Back Automation Fits

The fact is that every step of your DevOps process is open to automation.  In this section, we’ll cover the common points of integration, specifically:

  • The point in the process where you want to move content from your production CMS “back” to lower environments to support development and testing.
  • The point where you want to promote code “forward” from the development process to the production CMS so it can be published.

Both of these points in the process are illustrated and addressed in the diagram below by the double-headed arrow labeled Code Forward, Content back.   With respect to the CMS, Code Forward, Content Back is the most important aspect of the DevOps automation.

Crafter CMS’s Git-based repository is the foundation of the automation.  Our automation running in Jenkins is going to leverage API’s within the authoring environment (Crafter Studio) to sync code and content with the development process.  APIs will also be used to publish code synced to authoring to the Production delivery infrastructure.

Implementing Code Forward, Content Back Sync

Now that we’ve established what integration we’re addressing here is, let’s focus on configuring it.  Take a look at the diagram below, this elaborates the previous diagram showing how the sync occurs.

Note that both the Production authoring and the Development “environment” has a repository.  In authoring, this is a local Git repository.  In development, this is most often a centrally hosted Git repository that supports workflow and review (like Bitbucket, Gitlab, Github, and others.)   You can think of the repository under authoring as the Content Repository and the repository supporting developers as the Code Repository.  These names (Content Repository, Code Repository) are simply labels to help describe their purpose and assist us in addressing them in the context of this article.

To facilitate this flow, the Content Repository under authoring/Crafter Studio declares the Code Repository as a remote. The primary way of “syncing” work between Git repositories is through pull and push operations.  Before you can push your work to a remote, you must first pull merge the updates (if any) from the remote.  Once done, you can push your changes to the remote.

Automating the Pull / Push of Code and Content

To help automate the process described above Crafter Studio, the authoring and repository component of Crafter CMS supports a set of APIs.  You can find a full listing of Crafter Studio APIs for Crafter 3.0 here: http://docs.craftercms.org/en/3.0/developers/projects/studio/index.html

These APIs are easily invoked by a script.   You can use the following example script in your own implementation:

codeforward-contentback-sync.sh

#!/usr/bin/env bash
studioUsername=$1
studioPassword=$2
studioserver=$3
project=$4
remote=$5
branch=$6

echo "Authenticating with authoring"
rm session.txt
curl -d '{ "username":"'$studioUsername'", "password":"'$studioPassword'" }' --cookie-jar session.txt --cookie "XSRF-TOKEN=A_VALUE" --header "X-XSRF-TOKEN:A_VALUE" --header "Content-Type: application/json"  -X POST $studioserver/studio/api/1/services/api/1/security/login.json

echo "Pull from remote (get code waiting to come to sandbox)"
curl -d '{ "site_id" :"'$project'", "remote_name":"'$remote'", "remote_branch":"'$branch'" }' --cookie session.txt --cookie "XSRF-TOKEN=A_VALUE"  --header "Content-Type: application/json" --header "X-XSRF-TOKEN:A_VALUE" -X POST $studioserver/studio/api/1/services/api/1/repo/pull-from-remote.json

echo "Push to remote (send content waiting to go to development)"
curl -d '{ "site_id" :"'$project'", "remote_name":"'$remote'", "remote_branch":"'$branch'" }' --cookie session.txt --cookie "XSRF-TOKEN=A_VALUE"  --header "Content-Type: application/json" --header "X-XSRF-TOKEN:A_VALUE" -X POST $studioserver/studio/api/1/services/api/1/repo/push-to-remote.json

Use of the script:

codeforward-contentback-sync.sh [USERNAME] [PASSWORD] [AUTHOR_SERVER_AND_PORT]  [SITE_ID] [REMOTE_NAME] [BRANCH_NAME]

USER_NAME is the Studio user (application account)
PASSWORD is the Studio user password (application account)
AUTHOR_SERVER_AND_PORT the protocol server name and port of Studio
SITE_ID the ID of the site
REMOTE_NAME the name of the upstream (typically origin)
BRANCH_NAME the name of the branch (typically master)

Example:
codeforward-contentback-sync.sh devops mydevopspw http://localhost myprojectID origin master

The script is quite simple.  It authenticates to Crafter Studio, performs a pull from the Remote Code Repository and then if there are no conflicts, performs a push.  These two operations move code updates forward to the production Sandbox (not yet live) and content back to the development process.  Only approved code that’s been moved to the “master” branch with the intention to release is moved forward.

Calling the Script in Jenkins

The first step is to create a project.  Give the project a clear name and select the Freestyle project then click OK to continue.

There is no Source Code Management (SCM) aspect of the project.  The most typical use case for Content back workflow is a scheduled event: Every hour, day, week etc.

 

The next step is to define build triggers.  Since you are calling APIs here and content back is most likely based on some schedule you define you want to indicate that there is no Source Code Management (SCM) aspect of the project.

Select “Build Periodically” and define your schedule.  Schedule definitions user standard Cron/Quartz configuration.

Finally, you must define that you want Jenkins to call your script:

Once you have done these steps you are ready to go.  Manually invoke this build any time you want directly through the Jenkins console.  I recommend testing it to make sure your parameters and schedule are correct.

Publishing Code That’s Been Sync’d to Sandbox

When you run the code forward, content back process code in the remote code repository is moved to the production authoring sandbox (content repository.)  This code is now staged for publishing.  It is not yet live.  Crafter Studio must publish the code, making it available to your delivery servers.  This in-and-of-itself is awesome: global, elastic deployment at the touch of a button.

So how is it done?  Crafter Studio provides an API that allows you to publish commit IDs.  You can provide a single commit ID or you can provide a list.  It’s typical as part of your release process to “Squash” all of the commits in a given release into a single commit ID.  This allows you to address all of the work as a single ID/moniker which makes it very easy to move, publish and roll back without missing anything.

These APIs are easily invoked by a script.   You can use the following example script in your own implementation:

publish-code.sh

#!/usr/bin/env bash
studioUsername=$1
studioPassword=$2
xsrf=AUTOMATED
studioserver=$3
project=$4
env="Live"
commit=$5

echo "Authenticating with authoring"
rm session.txt
curl -d '{ "username":"'$studioUsername'", "password":"'$studioPassword'" }' --cookie-jar session.txt --cookie "XSRF-TOKEN=A_VALUE" --header "X-XSRF-TOKEN:A_VALUE" --header "Content-Type: application/json"  -X POST $studioserver/studio/api/1/services/api/1/security/login.json

echo "Publishing Commit $commit"
curl -d '{ "site_id" :"'$project'", "environment":"'$env'", "commit_ids": ["'$commit'"] }' --cookie session.txt --cookie "XSRF-TOKEN=A_VALUE"  --header "Content-Type: application/json" --header "X-XSRF-TOKEN:A_VALUE" -X POST $studioserver/studio/api/1/services/api/1/publish/commits.json

Use of the script:

publish-code.sh [USERNAME] [PASSWORD] [AUTHOR_SERVER_AND_PORT]  [SITE_ID] [COMMIT_ID] 

USER_NAME is the Studio user (application account)
PASSWORD is the Studio user password (application account)
AUTHOR_SERVER_AND_PORT the protocol server name and port of Studio
SITE_ID the ID of the site
COMMIT_ID the squashed commit ID of the items coming from the release branch

Example:
publish-code.sh devops mydevopspw http://localhost myprojectID 378d0fc4c495b66de9820bd9af6387a1dcf636b8

The script is quite simple.  It authenticates to Crafter Studio and invokes a publish for the provided commit.  This op

Calling the Script in Jenkins

See configuration of sync script above.  The steps are exactly the same with the following differences:

  1. You will call the publish-code script instead of the codeforward-contentback script.
  2. You will ask the user for a parameter  value COMMIT_ID via the UI on each invocation and pass that to the command line as the COMMIT_ID parameter value

 

 

That’s it!  You can now publish your code releases via commits to your entire delivery infrastructure regardless of its size or distribution.

Conclusion

CMS platforms are notorious for refusing to play nice with CI/CD and agile development practices and process, automation and tools like Jenkins, Bamboo, Travis and others.  Databases and JCR repositories are one component of several fundamental, architectural limitations that make supporting CI/CD difficult for CMS platforms. Crafter is an open source, dynamic CMS with a unique Git based repository specifically designed to fit neatly in to your development practices and bring your authoring and development teams together in a way never before possible to improve and increase the rate and volume of innovation!

Integrating Crafter CMS with GitLab for Better DevOps

Content authoring and software development are both a major part of producing today’s digital experiences. Unfortunately, development support is not something traditional CMS platforms handle very well at scale. Crafter CMS, a 100% open source CMS platform that includes a Git-based repository designed to handle not only authoring but also DevOps seamlessly.

Many development teams use cloud hosted developer platforms like GitLab to assist with their development process.   Crafter’s Git based CMS supports developers working against remote repositories like GitLab, Github, Bitbucket, and others.

By supporting this kind of architecture, Crafter provides a very simple way to flow code forward from a developer and her team all the way up through the CI/CD process to production.  We also support a very simple way for any developer or any environment to easily update itself with the latest content from production.  DevOps and CMS have never been easy — until now. Crafter CMS’s CODE FORWARD, CONTENT BACK™ process makes this process simple and allows you to leverage awesome platforms like GitLab to support your team with the tools they know and love.

In this article, I’ll show you how to create a new project in GitLab and then start a new project in Crafter CMS in a way that connects to GitLab as an upstream remote repository so that GitLab can be used to support your development process with your CMS related development! 

Create a New Project and Connect it to GitLab

Step 1: Create a Project in GitLab

Figure 1: Create a project in GitLab 

  1. Select Blank Project to create a bare project
  2. Enter your project name
  3. Provide a project description
  4. Choose your security level
  5. Click create site

Once your repository is created you will see a screen similar to the one below.  You want to make note of the Git URL for the site.  You will need this URL in the next step.

Figure 2: New Project in GitLab 

Step 2: Create Your Project In Crafter Studio

Next, you want to log in to Crafter Studio as the admin user. The admin user has the rights to create new projects (called sites.) Click Create Site.

Figure 3: Create site via Crafter Studio

Clicking Create Site will present you with the Create Site dialog. This dialog changes depending on what you choose. Below is an example of the dialog filled out in a way that creates your project locally, set the Github repository as its upstream remote and pushes the initial project contents to the upstream repository.

Let’s walk through each part of the dialog:

Figure 4: Create Site Dialog in Crafter Studio, populating a bare upstream Git repository.

  1. The first thing you need to do is give your site an ID. The ID itself doesn’t matter in a sense. It doesn’t need to match anything per se, technically speaking the only requirement is that it’s unique. That said, it’s a best practice to provide an ID that is meaningful/recognizable to the team. If your website is called Sweet.com a good ID might be “sweetdotcom”
  2. Next, because you plan to connect this project to an upstream repository you want to click the plus (+) on “Link to upstream remote Git repository” This will open a number of new fields.
  3. In the “Remote Git Repository Name” field you want to provide a repository name that makes sense. It’s common to use “origin” or “upstream.”
  4. In the “Remote Git Repository URL” field you must provide the link to the Git repository discussed in Step #1: https://gitlab.com/russdanner/sweet-dotcom.git
  5. Provide your credentials in Git Remote Repository Username and Password
  6. Choose the option: “Create site based on blueprint then push to  remote bare repository.” This means that Crafter Studio will create a new site based on the blueprint you choose, link the remote repository as an upstream and then once the blueprint is installed in the local Repositories it will be pushed automatically to the upstream remote.
  7. Choose your blueprint. There are several out of the box blueprints provided by default. Choose one of these or one of your own. For our example, we’ll choose Editorial which is the simple Article style website/project template.
  8. Click Create. Crafter CMS will create the local repositories, Solr core and internal data structures required to support the project and install the blueprint. Once complete it will connect to the upstream and push the contents of the Sandbox repository to the remote.

Figure 5: Site is created and the contents of the sandbox are automatically pushed to the upstream repository.

Step 3: Check GitLab to Make Sure Your Site is There

Go back to your GitLab project and refresh the screen.  You will see the contents of your CMS project in the repository.

Your project is there!  Now you are ready to set up your entire development process and CI/CD automation.  To learn more about how this is configured check out these blogs:

Creating a Project in Crafter CMS Based on an Existing GitLab Project

Let’s consider for a moment that you’re a new developer joining the team. The topology above is already set up and you just want to get a local environment up and going. Simple. Follow these instructions.

  1. Install Crafter Studio locally (Source build or Binaries bundle)
  2. Login as Admin
  3. Click Create Site
  4. Fill out the Create Site Form as in a similar fashion described in Step 2, except this time you chose the option to create your site based on an existing upstream repository. This can be your team’s branch or your own fork. The exact workflow is up to you.

Conclusion

Platforms like GitLab that support agile development and CI/CD are helping bring best practices to the enterprise with easy to use tools that make implementing these activities simple.

Crafter CMS’s Git-based repository and DevOps integration make it simple to build CMS and content related projects while adhering to DevOps best practices and leveraging today’s best development platforms.

“Code Forward, Content Back” is a trademark of Crafter Software Corporation

Using Crafter CMS. Github and Two-Factor Authentication

Crafter’s Git based CMS supports developers working against remote repositories like Github, Gitlab, Bitbucket, and others. Many organizations that use Github enforce a two-factor authentication for developers.  This article shows you how to create a site in Crafter when you have two-factor authentication in Github configured.

Step 1: Configure an Access Token in Github

If you are reading this article, it’s very likely you already have two-factor authentication configured and are using it with Github.  If you’re interested in setting it up you can learn more about that here:
https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/ 

The first step in getting Crafter Studio to work with Github when two-factor authentication is enabled is to create a personal access token.  Follow the instructions shown here to create and acquire your token:   https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/

Step 2: Create a Site based on a Remote Repository

  1. If Crafter CMS is not installed: Install it locally (Source build or Binaries bundle)
  2. Login as Admin user

Next, you want to log in to Crafter Studio as the admin user. The admin user has the rights to create new projects (called sites.) Click Create Site.

Figure 1: Create site via Crafter Studio

Clicking Create Site will present you with the Create Site dialog. This dialog changes depending on what you choose. Below is an example of the dialog filled out in a way that creates your project locally based on an upstream repository that becomes it’s remote.

Let’s walk through each part of the dialog:

Figure 2: Set up a project based on existing remote Git repository via Crafter Studio

  1. The first thing you need to do is give your site an ID. The ID itself doesn’t matter in a sense. It doesn’t need to match anything per se, technically speaking the only requirement is that it’s unique. That said, it’s a best practice to provide an ID that is meaningful/recognizable to the team. If your website is called FreshFlowers.com a good ID might be “freshflowerscom”
  2. Next, because you plan to connect this project to an upstream repository you want to click the plus (+) on “Link to upstream remote Git repository” This will open a number of new fields.
  3. In the “Remote Git Repository Name” field you want to provide a repository name that makes sense. It’s common to use “origin” or “upstream.”
  4. In the “Remote Git Repository URL” field you must provide the link to the Git repository discussed in Step #1: https://github.com/russdanner/devworkflowexample.git

  5. Provide your credentials in Git Remote Repository Username and Password
    USE THE PERSONAL ACCESS TOKEN
  6. Choose the option: “Create site based on remote git repository.” This means that Crafter Studio will create a new site by cloning the upstream repository locally and setting the upstream repository as a remote.
  7. Click Create. Crafter CMS will create the local repositories, Solr core and internal data structures required to support the project and pull in the project from the remote.

 

Content Management Meets DevOps (Part 2 of 2) How a Git-based CMS Supports Continuous Integration and Delivery

As we learned in Part 1 of this series: Content Authoring and Publishing; development and content authoring are both a major part of producing today’s digital experiences. Unfortunately, development support is not something traditional CMS platforms handle very well at scale. Crafter CMS, a 100% open source project not only supports authors but DevOps as well.

In this article, we’re going to expand on the authoring workflow and publishing mechanics we looked at in the last article and explain how Crafter CMS seamlessly supports DevOps tools and process.

Development Requires Environments

The CMS where authors work is typically considered a production system. That’s not to say that the edits they make are immediately live. Typically CMS platforms support a concept of a “draft” type workflow with the ability to publish approved content and make it “Live”.

Crafter CMS is no exception here. As we described in our last article in this series, Authors work in a decoupled authoring environment and content is published from authoring to delivery on approval.

In the authoring environment, content can be edited and previewed via our web-based authoring tool called Crafter Studio. Edits are saved in a Git-based repository called “Sandbox”. On approval, edits are moved to a repository called “Published.” Crafter Studio handles all of the mechanics of making editing and publishing safe and simple for authors. Authors simply click edit and make changes, perform reviews and publish work via the UI. In the background, Crafter Studio will lock content, perform commits and take any other actions necessary to perform the low-level repository tasks necessary.

The authoring environment is akin to a work and test area for the authors. Relative to the live site or app the content authors are deploying content to, the Crafter Studio (and the Sandbox repository) where they edit, preview and approve content is what we would call a lower environment. Work is promoted from the lower environment (authoring) to the live environment (delivery.)
Developers almost always work in lower environments. No real developer modifies the code in production. Experience shows that making changes in production leads to outages and hinders future upgrades. Interestingly, many headless CMS platforms making their way to the market today require developers managing content types to work directly in production! While the scope of development in these systems is limited, the end results are the same.

In Crafter CMS, because we decouple authoring from delivery, it is possible for developers to work directly with the production system via authoring. Changes can be made and tested in the authoring environment before being pushed live.

Figure 1: Production environment.  Showing DevOps as part of the production workflow.  DevOps do not want to touch production directly and should not have to.  Unfortunately, most CMS platforms force them to do so.

That said, developers do not want to work with CMS tools! They want to work with their own Integrated Development environments (IDE) and other tools. They want to work locally on their own machines where they have control and can debug. They want the ability to collaborate with their teammates on feature branches. They want to be able to work in parallel with other development teams without fear of stepping on each other or interfering with content authoring activities and they want to be able to easily move their work through the various environments of their certification and testing process out to production. Developer environments and process are complex.

To illustrated this I have included a diagram below of a typical developer process and set of environments which must be followed in order to get new functionality to production.

Figure 2: Typical DevOps workflow.  Today’s modern app development DevOps workflows include parallel development efforts on the same project and extend from the developer’s local environment and team sandbox all the way to production.

Traditional CMS Systems and Environments, Code Artifacts and Process Don’t Mix Well

It is difficult at best to support this kind of process with traditional CMS architecture. Server-side code is typically managed in a source code repository while CMS related code artifacts like templates, Javascript and CSS (that should be managed in a source code management) want to live in the CMS. Server-side code typically requires heavy packing and deployment systems like JARs, WARs and OSGi bundles. It takes a lot of effort on the part of the developer to get an environment setup locally so that they can develop and it’s equally difficult to get a specific set of code into one of the often many environments. Worse, content is always stored in a JCR repository or SQL database and it’s a huge burden to get the latest production content to a lower testing environment. The whole process of “code forward, content back” with traditional CMS is a nightmare for DevOps. Still worse, in some environments, going to production means interruptions in content authoring ability for content authors while their environment is updated with the latest code. These outages can last hours to days or in some cases even longer.

These conditions are unacceptable.  This is no way to support innovation at a time when the amount and speed of innovation an organization can sustain is a major key to competitive advantage.

Crafter CMS Provides the Solution

Crafter’s Git-based dynamic CMS tackles all of these challenges head-on with a set of technologies that incorporate lightweight development, integration with developer tools and process and elastic scalability that provides the ability to serve any front-end technology via API or markup with fully dynamic content.

First: Crafter CMS supports a fully featured, Spring-enabled, Groovy-based scripting layer. This is a subject for a whole blog of its own — but without getting too in-depth, it’s huge. You can create classes on your own in Groovy. You can leverage classes in the classpath. You can create your own beans based on Groovy or Java classes, you can inject existing beans and services. It’s a rich, robust powerful environment full of services for you to build on at the speed of scripting in the same languages and frameworks that you are used to.
Second: Crafter CMS sits on top of Git. Git is traditionally speaking, a source code version control system. That means that all of your code can live in the same version control system as the business content, together. It’s versioned together and it can be packaged and deployed together. Crafter CMS makes the world of CMS simple for content authors and developer native for DevOps.
Third: Because Crafter is Git-based you can natively support your ideal DevOps process for Continuous Integration and Delivery (CI/CD).

 

Let’s jump in and take a look at how it works.
Below is what you might think of as the archetype of a developer workflow that’s integrated with the production authoring environment. In this diagram, you will find a mechanism for both a “code forward” activity in which code can be moved through a development process through to production as well as a “content back” activity in which production content, including in-process content, can be brought back to lower development environments! including local development machines.

Figure 3: Archetypal DevOps workflow that describes in general how content flows back to the development process and code flows forward through the certification process to production.

The above diagram has a lot going on. Let’s break it down and explain things a step at a time.

Step 1: Create an Upstream Repository

In order to facilitate a developer workflow, you want to establish an upstream repository for your Sandbox in your production authoring environment. Any Git repository will work. It’s typical to use a Git repository that has a UI/Workflow atop of it such as Github, Bitbucket, Gitlab and other similar systems. The upstream repository is the root of the developer workflow.

Figure 4: A Git repository with support for “developer/team workflow” such as Github, GitLab or Bitbucket is configured as a remote upstream repository of the Production Authoring Sandbox repository.  This is the primary point of contact between the authoring process and the development and code release process come together.  

Step 2: Use Automation to Sync Sandbox with the Upstream

Note that the repository is what the Git community refers to as an “upstream” remote repository. That means in a sense the Production Sandbox becomes subordinate to it from a Git log perspective. This upstream repository is where content and development work will be merged before making its way to the production Sandbox and ultimately to the Published repository and the delivery nodes themselves. Also, note that nothing changes about the publishing and deployment configuration and topology of the Production environment.

You will want to keep the upstream repository up to date with authoring. The best way to accomplish this is to use a DevOps automation platform such as Jenkins or Bamboo to orchestrate a push to the upstream on a schedule. Keeping the upstream repository up to date with the authoring Sandbox repository provides downstream development and testing repositories with the latest content and helps to avoid conflicts when it’s time to promote from the upstream repository to the authoring Sandbox repository.

Figure 5: Content flows from Production Authoring Sandbox to the Developer repository via automated Git Push

Step 3: Use the Upstream Repository to Support Development and Testing Environments and Workflow

From this upstream repository, you will feed all lower environments and branch for each of your development efforts. From the upstream repository, you can support any development process and supply content to any development or testing environment. Lower environments may consist of Authoring and Delivery, or just Authoring, or just Delivery. It depends on the needs. For example, Development often contains both Authoring and Delivery, while QA tends to focus only on Delivery. Simple “Git pull” mechanics are used to move code and content from the upstream repository, typically from a branch.

Figure 6: Development branches and forks can be created to meet your specific workflow needs.  Lower environments use these repositories and branches as their upstream.

Step 4: Merge Code Updates Into the Upstream Master and Pull them to the Production Authoring Sandbox Repository

When you are ready to move code from a development branch to the authoring Sandbox you will first merge the work into the master of the upstream repository. You can do merge all of your commits or you can merge them into a single commit by using the Git rebase command. By Squashing all of the commits into a single commit you make it easier to move the workaround as a single unit. Merges are typically done via pull requests on repositories that support development workflow.
Once the merge operation is complete in the upstream repository your automation will carry that work to the production authoring Sandbox.

Figure 7:  Use “Pull Requests” and other Git workflow mechanics to promote code through the process.  When it’s ready to go live merge it to the “Master” of the Developer Repository.  At this point, it will flow via automation to the Production Authoring Sandbox.

Step 5: Use Crafter Studio’s Publish Commits API to Publish Code to Delivery

Once your development work is in the Production Sandbox you will want to publish it. To do this Crafter Studio provides a REST API that will trigger the publishing on one or more commits. Simply call Crafter Studio’s Publish Commits REST API (/api/1/services/api/1/publish/commits.json) via the DevOps automation platform passing the required parameters including the commit IDs to be published and Crafter Studio will move the work to the Published repository from which it will be replicated to your delivery nodes.

Figure 8: Move code from Sandbox to Published with a simple API call. 

Step 5: Build Tons of Amazing Things

Now that you have the basic mechanics of Crafter’s native Git-based distributed repository and development workflow you are ready to support any amount of parallel development you want with the kind of tools and process rigor you are used to. Because Crafter’s Git-based repository is distributed, authors and developers, even developers working locally are all working out of what is essentially the same repository.

The workflow enables the team to collaborate and work simultaneously without ever interrupting or stepping on each other’s toes. It’s time to start innovating!

How do I set up this workflow?

For the purpose of simplicity, we’ll assume you’ve got Crafter Studio up and running and you are about to create a new project.

Step 1: Create your upstream

Create an empty repository in your upstream (GitHub, Bitbucket etc.) The specific steps depend on the repository you are using. The key here is that you want to create an empty or what’s sometimes called a “bare” repository.

Figure 9: Create a bare repository in your developer Git. In this example, we’re using Github.

On Github, once created you will see the following screen. Here you will note the repository URL (https://github.com/russdanner/devworkflowexample.git) which you will need for the next step. Also, if you’re trying to create an upstream for an existing project (out of scope for this blog), you’ll find the instructions below in the “push an existing repository from the command line” section.

Figure 10: Bare repository created.  

Step 2: Create Your Project In Crafter Studio

Next, you want to log in to Crafter Studio as the admin user. The admin user has the rights to create new projects (called sites.) Click Create Site.

Figure 11: Create site via Crafter Studio

Clicking Create Site will present you with the Create Site dialog. This dialog changes depending on what you choose. Below is an example of the dialog filled out in a way that creates your project locally, set the Github repository as its upstream remote and pushes the initial project contents to the upstream repository.

Let’s walk through each part of the dialog:

Figure 12: Create Site Dialog in Crafter Studio, populating a bare upstream Git repository.

  1. The first thing you need to do is give your site an ID. The ID itself doesn’t matter in a sense. It doesn’t need to match anything per se, technically speaking the only requirement is that it’s unique. That said, it’s a best practice to provide an ID that is meaningful/recognizable to the team. If your website is called FreshFlowers.com a good ID might be “freshflowerscom”
  2. Next, because you plan to connect this project to an upstream repository you want to click the plus (+) on “Link to upstream remote Git repository” This will open a number of new fields.
  3. In the “Remote Git Repository Name” field you want to provide a repository name that makes sense. It’s common to use “origin” or “upstream.”
  4. In the “Remote Git Repository URL” field you must provide the link to the Git repository discussed in Step #1: https://github.com/russdanner/devworkflowexample.git
  5. Provide your credentials in Git Remote Repository Username and Password
  6. Choose the option: “Create site based on blueprint push to a remote bare repository.” This means that Crafter Studio will create a new site based on the blueprint you choose, link the remote repository as an upstream and then once the blueprint is installed in the local Repositories it will be pushed automatically to the upstream remote.
  7. Choose your blueprint. There are several out of the box blueprints provided by default. Choose one of these or one of your own. For our example, we’ll choose Empty which is the “Hello World” of blueprints.
  8. Click Create. Crafter CMS will create the local repositories, Solr core and internal data structures required to support the project and install the blueprint. Once complete it will connect to the upstream and push the contents of the Sandbox repository to the remote.

Figure 13: Site is created and the contents of the sandbox are automatically pushed to the upstream repository.

Step 3: Set up Your Delivery Nodes

Now that your project is created you can set up the rest of your production environment by initializing your delivery nodes to receive deployments from authoring. Remember these delivery nodes will pull from Crafter Studio’s repositories, not the upstream remote repository.

When you add a new delivery node a simple command line script is run on that node that configures it to replicate and process content from the “Published” repository from authoring.

  • Instructions for creating a site can be found here.
  • Instructions for initializing a delivery node can be found here.

Step 4: Set up your Developer Workflow and Lower Environments

Now that your upstream repository is initialized in GitHub you can set up any developer workflow you want. It’s typical to consider Master to be in-sync with the Production Authoring Sandbox. Given that, you don’t want to work in Master. Create branches to isolate development work from work that’s ready to move to Production Authoring. Below is an example topology that shows multiple environments and developer workflow that include feature branches, developer forms, and local developer clones.

Figure 14: Full DevOps “Code Forward, Content Back” workflow for CI/CD with Crafter CMS leveraging Git mechanics and DevOps automation.

I Am a Developer, I Want to Work Locally Against The Upstream

Let’s consider for a moment that your a new developer joining the team. The topology above is already set up and you just want to get a local environment up and going. Simple. Follow these instructions.

  1. Install Crafter Studio locally (Source build or Binaries bundle)
  2. Login as Admin
  3. Click Create Site
  4. Fill out the Create Site Form as in a similar fashion described in Step 2, except this time you chose the option to create your site based on an existing upstream repository. This can be your team’s branch or your own fork. The exact workflow is up to you.

Figure 15: Set up a project based on existing remote Git repository via Crafter Studio

Conclusion

Today’s digital marketplace is constantly evolving. Companies are always iterating on existing functionality with improvements and deeper integration or introducing new functionality and channels for their employees, partners, and customers. Crafter CMS provides the right technology and integrates seamlessly with your DevOps processes to enable you to achieve a high, sustainable continuous rate of constant, iterative development, integration and delivery (CI/CD.)

Digital experience teams finally have a toolset that allows authors to work continuously without being interrupted by developers.

Developers have a means for easily moving code forward through environments and pulling content back from production to lower environments.

Further, with Crafter’s distributed repository development shops can run as much parallel development as they want and developers are able to leverage the workflow and local tools they are accustomed to.

“Code Forward, Content Back” is a trademark of Crafter Software Corporation

Content Management Meets DevOps (Part 1 of 2) How a Git-based CMS Improves Content Authoring and Publishing

Traditional CMS platforms based on SQL and JCR repositories have begun to show major signs of weakness in keeping up with today’s demands for a high rate of innovation and rapid scalable deployment on modern elastic architectures. This is nowhere more evident than the move towards headless CMS. Many CMS platforms today push headless, or what some call Content as a Service (CaaS), as the one-stop-shop solution to the struggles most CMS platforms have in providing support for scalability, multi-channel, and development integration. It’s not. Headless capability is important but it has its own limitations.

Crafter CMS, an open source Git-based dynamic CMS tackles all of these challenges head-on with a set of technologies and that incorporate lightweight development, integration with developer tools and process, and elastic scalability for content delivery that provides the ability to serve any front-end technology via API or markup with fully dynamic content.

In this two-part series, we’ll explain the basic mechanics that support content authoring, publishing and developer workflow and demonstrate how these mechanics combined with Crafter’s architecture and developer stack set a new standard for what a CMS can provide in today’s competitive digital marketplace.

Content Management and Deployment Mechanics

In this section we’ll explore the mechanics of how (non-technical) content authors work with the CMS and how their changes, once reviewed and approved, are deployed from their authoring tools to a live content delivery system.

Crafter CMS is decoupled, composed of several microservices where content authoring and content delivery services are separated into their own distinct, subsystems. This model has many advantages related to security, scalability and delivery flexibility. In a decoupled architecture, content is published from authoring to delivery as shown in the diagram below. The delivery system may be any number of independent digital channels – enterprise website, mobile app, social, augmented reality, digital kiosk or signage, e-commerce front end, microsite, etc.

Crafter CMS supports authoring via Crafter Studio that sits on top of a headless Git-based repository and publishing system. Content authors don’t need to know anything about Git. They simply work with Crafter Studio, a web-based application. Crafter Studio provides beautiful content entry forms, in-context editing with multi-channel preview, drag-and-drop layout, component placement, image cropping, and more. While content authors are performing their work, Crafter is managing all of the Git mechanics, managing locking, creating a time-machine like, Git-based version history and audit trail for them behind the scenes, all accessible to them via the Studio UI.

 

Figure 1: Crafter CMS microservices applied to decoupled architecture

Crafter’s publish mechanism deploys content from the Authoring system to the Delivery system. Content logically flows from the authoring environment to the delivery environment. The mechanism for this, given the underlying Git repo, is a “pull” type interaction. Meaning the actual network conversation is initiated from the delivery infrastructure to the authoring infrastructure, as shown in Figure 2.

Each delivery node has a Deployer agent that coordinates deployment activities on the node for each site that is being delivered on that node.

  • Delivery nodes can initiate deployment pulls either on a scheduled interval (a “duty cycle”), on-demand via an API call, or both.
  • The Deployer performs a number of activities beyond receiving and updating content on the delivery node. A list of post-commit processors is run. These can be used to execute updates on search indexes, clear caches and perform other such operations.
  • The Delivery node maintains a clone of the Authoring Git-based repository.
  • The Crafter Deployer takes care of managing the synchronization of the delivery node’s clone authoring repository from the authoring environment.
  • Git-mechanics ensure content sync is 100% accurate.

Figure 2: Crafter’s Dynamic CMS Publishing via Git

Technically speaking, Authoring does not require knowledge of the Delivery nodes. This makes the architecture more elastic, globally scalable and even enables Crafter to support disconnected and intermittent content delivery.

  • Elastically add new nodes or revive dormant nodes and they will sync to the latest without any additional wiring.
  • Create region-based depots to avoid transferring data more than once over long distances for global deployments.
  • Airplanes, cruise ships, drilling/mining locations and other remote disconnected deployments can operate with their latest pull of content, and sync up with Authoring when connectivity is available.

Figure 3: Elastic Delivery

In Crafter CMS, only approved content is published to the delivery environment. Crafter manages this by using 2 repositories for each project. One called a “Sandbox” which contains work-in-progress and the other called “Published” which represents approved, published work and complete content history.

  • Authors use the Crafter Studio UI to review and approve content via workflow.
  • Crafter Studio takes care of moving approved work between Sandbox and Published repositories.
  • Delivery nodes monitor the published repository for updates.


Figure 4: Authors work in Sandbox. Delivery nodes pull from Published.

Benefits

Crafter’s Git-based publishing model provides your authoring team with a highly reliable, highly accurate publishing mechanism that is elastically scalable, globally distributable and supports multi-channel.  Crafter CMS’s architecture enables your team to reliably deliver your dynamic content on any channel, wherever and whenever it is needed.

Further, As we’ll see in in Part 2, this architecture enables content authors to work side-by-side with DevOps, while they continually introduce new features and functionality without any disruption to the authors.

How do I set up this workflow?

The underlying Git repositories and related workflow for Authoring require no setup at all. When you create a project in Crafter Studio it automatically creates the local “Sandbox” and “Published” repositories. When you add a new “Delivery” node a simple command line script is run on that node that configures the node’s deployer to replicate and process content from the “Published” repository from authoring.

  • Instructions for creating a site via Crafter Studio can be found here.
  • Instructions for initializing a delivery node can be found here.

Conclusion

Content authors are non-technical users who need powerful but easy-to-use tools to help create, maintain and manage their digital experiences. Crafter Studio provides these users with a web-based application that makes it easy for content authors to achieve their goals. Under the hood, Crafter Studio leverages a powerful Git-based repository and deployment engine that provides authors with next-generation versioning and auditing mechanics as well as robust, elastic and distributed deployment.

Today’s digital marketplace is constantly evolving. Companies are always iterating on existing functionality with improvements and deeper integration or introducing new functionality and channels for their audiences. For today’s most innovative and competitive organizations, ongoing development and the move to DevOps is a fact of life. The companies that have the greatest success are those that have the right technology and processes through which they are able to achieve a high, sustainable continuous rate of constant, iterative development, integration and delivery, i.e., Continuous Integration and Delivery (CI/CD).

In the second half of this blog series, we will take a deep dive into how Crafter CMS seamlessly integrates with your CI/CD processes to enable your entire team of developers and content authors to innovate collaboratively without interfering with each other’s workstream.

 

Working with Crafter Studio’s API

Crafter CMS is a decoupled CMS composed multiple microservices where content authoring and content delivery capabilities and services are separated into their own distinct, subsystems.

Organizations often want to interact with the content authoring and management system via APIs. In this article, we’ll show the basics of interacting with this API by example:

  • Authenticate
  • Get a list of projects under management
  • Write content to a project

To keep things really basic, we’ll use CURL, a ubiquitous Linux command tool as our client.

You can find the full Crafter Studio API for Crafter CMS version 3.0 here
http://docs.craftercms.org/en/3.0/developers/projects/studio/api/index.html

Step 1: Authenticate

We’ll use the authenticate API
http://docs.craftercms.org/en/3.0/developers/projects/studio/api/security/login.html

curl -d '{"username":"admin","password":"admin"}' --cookie "XSRF-TOKEN=A_VALUE" --header "X-XSRF-TOKEN:A_VALUE" --header "Content-Type: application/json" -v -X POST http://localhost:8080/studio/api/1/services/api/1/security/login.json

The first thing you’ll note is that we’re going to perform a POST, passing the username and password as a JSON object.  In a production environment, you will want to use HTTPS.

The next thing you will notice, we are passing a cookie “XSRF-TOKEN” and a header “X-XSRF-TOKEN”.  The value passed for these are arbitrary.  They must match and they must be passed in all future PUT and POST API calls.  These are used to protect against certain cross-browser scripting attacks.  If you are using Studio APIs as part of a web client you want to make sure these values randomly generated.

When you issue the curl command you will get back a response:
 * Trying ::1...
 * Trying 127.0.0.1...
 * Connected to localhost (127.0.0.1) port 8080 (#0)
 > POST /studio/api/1/services/api/1/security/login.json HTTP/1.1
 > Host: localhost:8080
 > User-Agent: curl/7.43.0
 > Accept: */*
 > Cookie: XSRF-TOKEN=A_VALUE
 > X-XSRF-TOKEN:A_VALUE
 > Content-Type: application/json
 > Content-Length: 39
 >
 * upload completely sent off: 39 out of 39 bytes
 < HTTP/1.1 200
 < Cache-Control: no-cache, no-store, max-age=0, must-revalidate
 < Pragma: no-cache
 < Expires: 0
 < Set-Cookie: JSESSIONID=2E114725C82F3EE44ADC04B578A3BE8F; Path=/studio; HttpOnly
 < Content-Type: application/json;charset=UTF-8
 < Content-Language: en-US
 < Transfer-Encoding: chunked
 < Date: Mon, 22 Jan 2018 21:32:48 GMT
 <
 * Connection #0 to host localhost left intact
 {"username":"admin","first_name":"admin","last_name":"admin","email":"evaladmin@example.com"}

Note the response returned is a successful 200 status code and the response contains JSON with details for the authenticated user.

Also found as part of the request is the JSESSION cookie.  You will need this value for all future requests.

Step 2: Get a list of sites the user is authorized to work with

http://docs.craftercms.org/en/3.0/developers/projects/studio/api/site/get-sites-per-user.html

curl --cookie "XSRF-TOKEN=A_VALUE;JSESSIONID=2E114725C82F3EE44ADC04B578A3BE8F" -H "X-XSRF-TOKEN:A_VALUE"  -X GET http://localhost:8080/studio/api/1/services/api/1/site/get-per-user.json?username=admin
Note the CURL command contains your session ID and XSRF tokens.
When you issue the CURL you will get a response that contains sites your user has access to:
{"sites":[{"id":9,"siteId":"ar","name":"ar","description":"","status":null,"liveUrl":null,"lastCommitId":"951004363449cc83209f307b1e9f110dab37fed7","publishingEnabled":1,"publishingStatusMessage":"idle|Idle","lastVerifiedGitlogCommitId":null},{"id":5,"siteId":"diiot","name":"diiot","description":"","status":null,"liveUrl":null,"lastCommitId":"92d543eaa164b1ebfbdd6ce538ae028d4d6421b7","publishingEnabled":0,"publishingStatusMessage":"idle|Idle","lastVerifiedGitlogCommitId":"92d543eaa164b1ebfbdd6ce538ae028d4d6421b7"},{"id":10,"siteId":"editorialcom","name":"editorialcom","description":"","status":null,"liveUrl":null,"lastCommitId":"503d922f226e8ab821073e23ef5a229f907212a0","publishingEnabled":1,"publishingStatusMessage":"","lastVerifiedGitlogCommitId":"503d922f226e8ab821073e23ef5a229f907212a0"},{"id":3,"siteId":"flow","name":"flow","description":"","status":null,"liveUrl":null,"lastCommitId":"21923775c3a1fc778a364d47884b9ee2bb4928a5","publishingEnabled":1,"publishingStatusMessage":"idle|Idle","lastVerifiedGitlogCommitId":"21923775c3a1fc778a364d47884b9ee2bb4928a5"},{"id":8,"siteId":"vr","name":"vr","description":"","status":null,"liveUrl":null,"lastCommitId":"c67fd9dd25d1aa59ff13e3fda2a4387be50dfc69","publishingEnabled":1,"publishingStatusMessage":"idle|Idle","lastVerifiedGitlogCommitId":null}],"total":6}

The response above contains a number of projects.  In the next call I want to write a content object to one of the projects (editorial.com.) To do this I need the site ID.  I get this from the response above: editorialcom

Step 3: Write content to the Editorial com Project

http://docs.craftercms.org/en/3.0/developers/projects/studio/api/content/write-content.html

curl -d "<page><content-type>/page/category-landing</content-type><display-template>/templates/web/pages/category-landing.ftl</display-template><merge-strategy>inherit-levels</merge-strategy><file-name>index.xml</file-name><folder-name>test3</folder-name><internal-name>test3</internal-name><disabled >false</disabled></page>" --cookie "XSRF-TOKEN=A_VALUE;JSESSIONID=2E114725C82F3EE44ADC04B578A3BE8F" -H "X-XSRF-TOKEN:A_VALUE"  -X POST "http://localhost:8080/studio/api/1/services/api/1/content/write-content.json?site=editorialcom&phase=onSave&path=/site/website/test3/index.xml&fileName=index.xml&user=admin&contentType=/page/category-landing&unlock=true"

In the call above note:

  • We are passing in content as the POST body.  The content is in XML format.  In Crafter content objects are stored as simple XML documents.
  • We are passing the Session ID and the XSRF tokens
  • We are passing a number of parameters that tell Crafter CMS where and how to store the content in the repository

Conclusion

In this article we covered the basic mechanics of connecting to and interacting with Crafter Studio, the authoring services of Crafter CMS.  We’ve avoided the nitty gritty details of each API call in favor of the macro mechanics.  You now have the basic skills and capability to interact with any Crafter Studio API found here: http://docs.craftercms.org/en/3.0/developers/projects/studio/api/index.html.  Get out there and integrate!