CrafterCMS is a modern content management platform for building digital experience applications including:

• Single Page Applications (SPAs) using frameworks like React, Vue, and Angular
• Native mobile apps and headless applications (IOT, digital signage, wearables, etc.)
• HTML5 websites using Bootstrap or other HTML frameworks
• e-commerce front-ends
• OTT video experiences on AWS Elemental Media Services
• AR/VR applications using A-Frame

You can learn more about CrafterCMS here: https://craftercms.org.

Try CrafterCMS using a pre-built AMI (use the authoring AMI): https://aws.amazon.com/marketplace/seller-profile?id=6d75ffca-9630-44bd-90b4-ac0e99058995

Download a pre-built binary archive here: https://craftercms.com/download.

Read the docs here: https://craftercms.com/docs/

This repository is for developers interested in contributing to CrafterCMS, customizing their own release, or building the latest. It contains all CrafterCMS modules and helps you build the following:

1. Deployable CrafterCMS binaries
2. Docker images
3. Developer's environment so you can compile and contribute to CrafterCMS

WARNING: CrafterCMS source code development and building is only supported on Unix based systems. If you want to use CrafterCMS in Windows, use Docker or install Windows Subsystem for Linux (WSL) by following the instructions here then use the WSL 2 terminal for all the commands below.

Please make sure your system meets the prerequisites: https://craftercms.com/docs/current/by-role/system-admin/installation.html#requirements

Let's begin :)

If you're building deployable CrafterCMS binaries, we'll clone the tag where the tag is the release you want to build. For example, if we want to build CrafterCMS version 4.4.4, we'll check the CrafterCMS tags list to get the tag for the version we want, which is v4.4.4 for our example:

git clone --branch v4.4.4 https://github.com/craftersoftware/craftercms.git

OR

If you would like to contribute to CrafterCMS, to build a developer's environment, we'll need to clone the develop branch (default):

git clone https://github.com/craftersoftware/craftercms.git

For more information on CrafterCMS Git Workflow, please review CrafterCMS Git Workflow.

• download Download dependencies
• selfUpdate Update the parent project (craftercms)
• clean Clean modules
• build Build modules
• deploy Deploy modules
• upgrade Upgrade modules (same as selfUpdate, clean, build, deploy)
• start Start CrafterCMS
• stop Stop CrafterCMS
• status Report status on running environments if any
• bundle Create deployable binaries
• buildAuthoringTomcat Build an authoring Docker image
• buildDeliveryTomcat Build a delivery Docker image
• buildDeployer Build a deployer Docker image
• buildGitSshServer Build a Git SSH server Docker image
• buildGitHttpServer Build a Git HTTP server Docker image
• buildLogRotate Build a LogRotate Docker image
• buildMainImages Build the main Docker images
• buildAllImages Build all the Docker images
• deleteDockerArtifacts Delete all Docker artifacts (CrafterCMS and non-CrafterCMS, including containers, images, and volumes)

• overwriteChangedFiles: Update and overwrite the deployed environment (authoring or delivery) files (binaries, configuration, etc.), default true
• refreshEnv: Update the deployed environment (authoring or delivery) with any changes to the scripts, default false
• overwriteArtifact: Update and overwrite the downloaded artifacts (example: OpenSearch, Tomcat, ...) that's cached in the downloads folder by downloading it again, default false
• gitRemote: Git remote name to use in cloned modules, default origin
• gitBranch: Git branch to use when cloning modules, default develop (for develop branch)
• socialRequired: Include Social in the build, default false
• profileRequired: Include Profile in the build, default false
• startSearch or withSearch: start OpenSearch, default true
• startMongoDB: start MongoDB, default false unless Profile or Social are enabled. This is automatic.
• bundlesDir: Where to deposit binaries, default ./bundles
• downloadGrapes: Download Grapes ahead of time (useful when no public Internet is available), default true
• downloadDir: Where to store downloads, default ./downloads
• authoringEnvDir: Where to store the authoring environment, default ./crafter-authoring
• deliveryEnvDir: Where to store the delivery environment, default ./crafter-delivery
• currentPlatform: What platform to build to (linux or darwin), default is the build machine's OS
• currentArch: What arch to build to (aarch64 or x86_64), default is the build machine's arch
• pushDockerImages: Push the Docker images to DockerHub (if you have the right permissions), default false
• tagDockerImages: Tag the Docker images with the tag provided (if you have the right permissions), default is not to tag
• rootlessDockerImages: Docker images without using root at runtime, default false
• dockerTag: Tag used to build a Docker image, typically the version number, e.g. 5.0.0
• dockerAuthoringBundle: Use to point to an external authoring bundle from which to build the Docker images. This can be a remote URL, a local .tar.gz file path, or an expanded bundle path.
• dockerDeliveryBundle: Use to point to an external delivery bundle from which to build the Docker images. This can be a remote URL, a local .tar.gz file path, or an expanded bundle path.

To build deployable and distributable binaries of CrafterCMS, use the Gradle task bundle. This task will generate .tar.gz files ready to be deployed to any system.

Before using bundle task make sure that the environment has been created and deployed using gradle tasks build and deploy

Archives will be named crafter-cms-${environment}-VERSION.tar.gz and can be found in the bundles folder.

./gradlew build deploy bundle

To run CrafterCMS from the binary archive, unzip and follow the instructions in the binary archive's README.txt.

CrafterCMS is a decoupled CMS, and that means you have an authoring environment that caters to content creators, and a different environment, delivery, that handles the end-users that use the experience created by the former.

To build a binary archive for a specific environment:

    ./gradlew bundle -Penv=authoring

Archive will be named crafter-cms-authoring-${version}.tar.gz and can be found in the bundles folder.

For the delivery environment, simply substitute the env=authoring with env=delivery.

To download, build and generate a binary archive from a given tag or branch of the source code,

1. Clone the branch/tag of craftercms that you want to work with

    git clone -b <tag or branch> https://github.com/craftersoftware/craftercms.git

2. Download, build and bundle the tag/branch that you want to work with

    ./gradlew build deploy bundle

NOTE: When using a tag-based build, you're essentially cloning a point in time to build that specific version of CrafterCMS. That implies that you won't be able to update/nor push changes back.

CrafterCMS comprises a number of headless API-first (GraphQL, REST, in-process) modules that work together to provide the final solution. In this section, we'll start with the simple case of build everything/run everything, and then move on to building/hacking individual modules.

Build all CrafterCMS modules

    ./gradlew build deploy

Start CrafterCMS,

   ./gradlew start

You can now point your browser to http://localhost:8080/studio and start using CrafterCMS. To get started with your first CrafterCMS experience, you can follow this guide: Your First Templated Project or Your First Headless Project.

NOTE:

• The authoring environment runs on port 8080, a great place to start, while the delivery environment runs on port 9080.

Stop CrafterCMS,

    ./gradlew stop

You might have noticed that you essentially have two environments built and running: authoring and delivery. CrafterCMS is a decoupled CMS, and that means you have an authoring environment that caters to content creators, and a different environment, delivery, that handles the end-users that use the experience created by the former.

As a developer, you can use an authoring environment for most tasks without the need to run a delivery environment. It's important to note that delivery essentially runs the same software that's in authoring except Crafter Studio (the authoring tools). By default, this project will build both environments unless instructed otherwise. The authoring environment runs at http://localhost:8080/studio, whereas the delivery environment runs at http://localhost:9080/.

To build, start and stop one of the two environments is similar to building/starting/stopping All.

    ./gradlew build deploy -Penv=authoring
    ./gradlew start -Penv=authoring
    ./gradlew stop -Penv=authoring

    ./gradlew build deploy -Penv=delivery
    ./gradlew start -Penv=delivery
    ./gradlew stop -Penv=delivery

The mechanics for working with a single module are similar to working with all, with one exception: You can deploy a module to one or both environments (authoring/delivery).

CrafterCMS comprises the following modules (among others):

• engine
• studio
• profile
• social
• deployer

You'll find these projects under the root project directory and ready for you to contribute to in the folder {Project Root}/{module}.

Start by forking this repository. You can follow the GitHub instructions. The next step is to switch the origin URL to your fork; see these GitHub instructions. Then add an upstream remote pointing at the main craftersoftware/craftercms repo. Follow these steps to make it happen. You can now work in your local system, and build/deploy and ultimately push to your fork. We welcome code contributions, so please do send us pull-requests.

To update your local clone with the latest:

    ./gradlew selfUpdate

You can build or deploy a module by:

    ./gradlew studio:build
    ./gradlew studio:deploy -Penv=authoring

NOTE:

• If you don't specify the env parameter, it means all environments (where applicable).
• In the current version of CrafterCMS, some services run in the same Web container, and that implies the stopping/starting of one of these services will cause other services to stop/start as well.

For more detailed information and advanced topic, please visit the detailed documentation.

CrafterCMS has two environments, the Authoring Environment and the Delivery Environment.

The authoring environment provides all the content management services, enabling authoring, managing and publishing of all content. It provides a comprehensive set of user-friendly features for managing and optimizing your experiences.

The delivery environment provides content delivery services. It consumes content published from your authoring environment and provides developers with the foundation for quickly building high-performance, flexible experiences.

In this section we will be discussing the scripts for the authoring and delivery environments.

The CrafterCMS Authoring and Delivery scripts will help you on the basic startup and shutdown of the services needed to run a healthy Authoring environment and Delivery environment with the following scripts:

For more information on environment variables used by crafter.sh, see CrafterCMS Environment Variables

Let's look at an example on how to start an authoring environment using the scripts we discussed above. To start the authoring environment, go to your CrafterCMS install folder then run the following:

   cd crafter-authoring
   ./startup.sh

What the above does is go to your authoring environment folder, then run the startup script.

To stop the authoring environment:

   ./shutdown.sh

For more information about Apache Tomcat, and OpenSearch please refer to the following:

• Tomcat Script documentation
• OpenSearch documentation

As we have seen in the getting started section above, to run a gradle task, we run the following from the root of the project:

   ./gradlew command [-Penv={env}]

   ./gradlew module:task [-Penv={env}]

e.g.:

   ./gradlew engine:deploy -Penv=authoring

Here's a list of commands (Gradle tasks) available:

NOTE:

• If you don't specify the env parameter, it means all environments (where applicable).
• In the current version of CrafterCMS, some services run in the same Web container, and that implies the stopping/starting of one of these services will cause other services to stop/start as well.
• List the modules and the tasks to build multiple modules in the same command: ./gradlew engine:build studio:build
• Use -p module to run multiple tasks for a module: ./gradlew -p studio clean build deploy -Penv=authoring
• The clean command does not delete previously built environment folders crafter-authoring and crafter-delivery. To build a fresh copy of these two, backup your custom data and delete both folders manually.

Let's see some examples of running Gradle tasks here.

To build the authoring and delivery environments, run the following:

   ./gradlew build

The Gradle task above will:

1. Download the dependencies

2. Build all CrafterCMS modules from the source

   • crafter-authoring
   • crafter-delivery

To build a module (all module options for task build are listed in the table above), run the following (we'll build the module studio in the example below):

   ./gradlew studio:build

To build an environment, run the following (we'll build the authoring environment in the example below:

   ./gradlew build -Penv=authoring

To start an environment, run the following:

   ./gradlew start [-Penv={env}]

For an alternative to start an environment, run the following:

   cd crafter-{env}
   ./startup.sh

The options above will:

For the Authoring Environment:

• The above will start the authoring environment with the default port 8080

For the Delivery Environment:

• The above will start the delivery environment with the default port 9080

Here's an example starting a delivery environment:

   ./gradlew start -Penv=delivery

To stop an environment, run the following:

   ./gradlew stop [-Penv={env}]

For an alternative to stop an environment, run the following:

   cd crafter-{env}
   ./shutdown.sh

The Gradle task bundle will build deployable and distributable binaries of CrafterCMS for the authoring and/or delivery environments. This will generate tar files ready to be unarchived and run.

   ./gradlew bundle [-Penv={env}]

Binaries will be saved as crafter-cms-authoring-VERSION.tar.gz for the Authoring Environment and crafter-cms-delivery-VERSION.tar.gz for the Delivery Environment in the bundles folder

Using the common task property env lets you select what environment (authoring or delivery) will be generated.

Let's look at an example using the task property mentioned above:

    ./gradlew bundle -Penv=authoring

The command above will generate an authoring binary archive in the bundles folder named crafter-cms-authoring-VERSION.tar.gz.