Quick Start Guide

This section describes how to quickly install Crafter CMS and start crafting your experiences.

Here are the steps to start using Crafter CMS for development or evaluation:


Windows support is now via Docker. If you are on a Windows operating system, please follow the guide here to start using Crafter CMS.

Installing and Verifying Prerequisites

Install Java

Download and install Java JDK 1.8 (either Oracle or OpenJDK).

Verify Java Version

Ensure that you are running Java 1.8. To check, run the following command at the command prompt and make sure that the version displayed is Java 1.8:

java -version

The command above should output something like this:

java version "1.8.0_91"

Verify JAVA_HOME environment variable is set correctly

Make sure that you have a JAVA_HOME environment variable that points to the root of the JDK install directory. To check the value set for JAVA_HOME, enter the following command at the command prompt:

env | grep JAVA_HOME

How to set the JAVA_HOME environment variable

To set JAVA_HOME on a Unix/Linux System

  • Korn and bash shells:

    export JAVA_HOME=jdk-install-dir
    export PATH=$JAVA_HOME/bin:$PATH
  • Bourne shell:

    export JAVA_HOME
    export PATH
  • C shell:

    setenv JAVA_HOME jdk-install-dir
    setenv PATH $JAVA_HOME/bin:$PATH
    export PATH=$JAVA_HOME/bin:$PATH

OS X extra prerequisite

For OS X users, the latest openssl formula needs to be installed via homebrew:

brew install openssl

Linux prerequisite

  1. For Linux users, some of the scripts uses lsof. Please note that some Linux distributions does not come with lsof pre-installed and so, may need to be installed.

    To install lsof for Debian-based Linux distros: apt-get install lsof

    To install lsof for RedHat-based Linux distros: yum install lsof

  2. The library libncurses5 is required for running the restore script. You may get the following error when running the restore script without the libncurses5 library installed:

    error while loading shared libraries: libncurses.so.5: cannot open shared object file: No such file or directory

    To install the library libncurses5, use the following commands:

    On Debian-based Linux distros: sudo apt-get install libncurses5-dev libncursesw5-dev

    On RHEL, CentOS: sudo yum install ncurses-devel

    On Fedora 22 and newer version: sudo dnf install ncurses-devel

Installing Crafter CMS from the Archive Download

To install Crafter CMS using the archive download:

  • Download the Crafter CMS install archive file from http://craftercms.org/downloads

    Select crafter-cms-authoring.tar.gz. The .tar.gz file will install a fully functional Crafter Studio instance and a Crafter Engine in Preview Mode. Out of the box, the Studio instance uses a local directory as the repository and a Derby database, which allows a quick and easy set up for local development.

  • Extract the contents in any directory.

Starting Crafter CMS Using the Startup Script

  1. Start the Crafter CMS Server using the startup script

    To start Crafter CMS:

    From the command line, navigate to the {Crafter-CMS-unzip-directory}/crafter/bin/ directory, and execute the startup script:



    It takes a few seconds for Crafter CMS to startup and takes longer to startup the very first time you startup Crafter CMS.

    To stop Crafter CMS:

    From the command line, navigate to the {Crafter-CMS-unzip-directory}/crafter/bin/ directory, and execute the shutdown script:


Open Crafter Studio

In your browser, go to

  • Login with the following:

    • username: admin
    • password: admin

After logging in, you should be redirected to the Sites screen, and you’re now ready to create your first website!

Installing Crafter CMS From Archive Built By the Gradle Environment Builder

To create the archives(*.tar.gz) for installing Crafter CMS, the following must be installed in your system:

  • Java 8
  • Git 2.x+
  • Maven 3.3.x+
  1. Clone the Crafter CMS repo from GitHub

    git clone https://github.com/craftercms/craftercms.git
  2. Build a deployable bundle using the Gradle Environment Builder to generate the archives crafter-cms-authoring.tar.gz inside the bundle folder

    ./gradlew init build deploy bundle
  3. Unpack the file (crafter-cms-authoring.tar.gz) into any directory. You may now follow the instructions listed above Start the Crafter CMS Server using the startup script to start using Crafter CMS

For more details on using the Gradle environment builder, please review: https://github.com/craftercms/craftercms/blob/master/README.md

Running Crafter CMS in a Docker Container

To run Crafter CMS in a Docker container using Docker Compose, make sure the following are installed in your local system:

For Windows and Mac, we recommend you give Docker Desktop at least 8GB of RAM and 4 CPUs. To do this, go to Docker Desktop’s Settings > Advanced, and then change the resource limits.

Docker Desktop Advanced Settings
  1. Clone the Crafter CMS Docker Compose repo from GitHub

    git clone https://github.com/craftercms/docker-compose.git

  2. Go into the authoring folder, then start the container

    cd authoring
    docker-compose up

You may now follow the instructions listed above: Open Crafter Studio to start using Crafter CMS.

For more information on Crafter CMS Docker Compose, please see: https://github.com/craftercms/docker-compose.