This brief guide will help you get familiarized with developing in dotCMS, set up your development environment, and get started with essential tasks on day one.
1. Supported Coding Methods
dotCMS provides multiple different ways to develop code and extend your sites. It is helpful to understand the different ways you can code in and extend dotCMS when planning your site development. Below you’ll find quick access links to documentation for each development type.
Development Type | Code Language(s) | Execution Location |
|---|---|---|
HTML, CSS, JavaScript (with SDK support for several JavaScript frameworks) | Client (app or browser) | |
Velocity | Server | |
External Application Development (Headless/CaaS) | REST API | Server |
Java | Server | |
Two or more of the above | Mixed |
You may combine any or all of these methods however you wish to provide the level of control, performance, and security required for your application.
However it's important to note that when mixing client-side and server-side code, the server-side code always runs first, and then the client-side code runs. You can not pass the results of client-side code to server-side code (e.g. you can not pass the results of JavaScript code to Velocity). If you need to pass the results of client-side code to the dotCMS server, it is recommended to do so through a mechanism which directly queries the dotCMS server, such as a Scripted Custom Endpoint, or a REST API call to process Velocity code.
2. Installing & Running dotCMS
The easiest way to quickly setup and install a dotCMS starter site is by using the standard dotCMS Docker images.
Note: Before installing dotCMS, it’s best to review the system requirements.
A. Install Docker
Download and install Docker (or Docker Desktop) if not already installed.
Ensure that you have Docker Compose installed.
To test, Open a terminal and run
docker composeIf Docker Compose is not present, or if you would like more information on the messages you receive, please see the Docker Compose documentation.
B. Install your dotCMS Environment
Option 1: Install the dotCMS Developer Instance (Recommended)
The dotCMS Developer Instance is a docker image specifically created for dotCMS developers. It contains all the services that are required to run dotCMS — including Postgres 16 and Opensearch 1.x.
All dotCMS, db and es index data is stored in the /data directory, which can be mapped in if you want your environment to persist.
Use the below to run a clean dotCMS dev environment.
Note: All data and assets will be stored in the directory ./data
docker run --rm \
-p 8443:8443 \
-v $PWD/data:/data \
dotcms/dotcms-dev:nightlyLogin using the admin password found in the log output.
Note: You can can login via https on port 8443 — there is a certificate if you are running locally using https://local.dotcms.site:8443/dotAdmin
Option 2: Install a Current Release Image
You can also install dotCMS using a current release image, which can optionally include the demo site data.
Visit Current Releases to Download the Docker Compose YAML
Select a recent version from the dropdown.
Choose whether you'd prefer a clean (i.e., empty) starter or one bundled with a copy of the dotCMS Demo Site.
Click the blue button to download the file to your chosen working directory.
In your terminal, navigate to the folder containing the file and use:
docker compose upNext, let’s log in to the dotCMS Admin Portal to take a look around the back end.
Navigate to http://localhost:8082 in your browser.
Use the default credentials to log in, but make sure to change them once logged in!
Username: admin@dotcms.comPassword: admin
Note: If you set the login credentials within the Docker YAML file, you will use those credentials instead
3. Setting Up Your Environment: CI/CD Tools
Now that you have dotCMS up and running, and you’re logged into the Admin Portal, let’s discuss a few helpful tools you may want to set up next, depending on your needs.
dotCMS offers a number of tools to facilitate automation and rapid development at various scopes for CI/CD
A. dotCMS CLI (recommended)
dotCMS CLI, or dotCLI for short, is a standalone tool for interacting with a dotCMS instance through a command shell, allowing a wide array of automated operations and behaviors.
For convenience, we've also created a dotCMS CLI cheat sheet, which you can download in PDF format.
Supported Platforms
dotCLI works natively on MacOS and Linux systems.
To operate on Windows, use Windows Subsystem for Linux (WSL). Once WSL is operational, be sure to install npm within WSL:
sudo apt-get update
sudo apt install npmNote: Attempting to use an instance of npm installed in Windows outside of WSL may cause errors on dotCLI installation.
Installation
The simplest and most recommended way to get the dotCLI is from its npm package:
npm install -g @dotcms/dotcli
After this, you can immediately begin calling dotCLI commands.
B. Workflows
Workflows allow enormous customizability of behavior when performing operations on content. They can be defined at will and assigned freely to any Content Type, capable of serving as the backbone of a continuous delivery environment.
Use this link to read more about Workflows and how they work.
C. WebDAV
dotCMS is capable of file-system management via Web-based Distributed Authoring and Versioning, or WebDAV, which has long been a simple way to perform operations on file assets.
While support for WebDAV is deprecated in current editions — with the dotCLI strongly recommended where available — it remains a valid option for CI/CD.
4. Setting Up Your Environment: APIs & Access Tokens
When using dotCMS APIs, we recommend that you use API tokens to authenticate your API calls. It is possible to generate an API token programatically, using the API or through the UI.
A. Creating API Access Tokens through the UI
From the UI, tokens can be generated from the User manager portlet.
Navigate to Settings > Users
In the User manager, select the user for whom to create the token
Note: all API accesses by the token will use the permissions of the user for which it was created. This can be done on your own user account, or a front-end or back-end account created expressly for this purpose.
Select the API Access Tokens tab
Click Request a New Token
Enter a descriptive title, an expiration date and a network (CIDR notation) from which the token can be used, and click OK
B. Creating API Access Tokens with the API
You can also create an API Token via API. The following curl commands demonstrate how to use JSON Web Tokens (JWT) to authenticate REST API calls.
Note: Always use SSL/HTTPS.
Requesting the Token
The following curl command accesses the /api/v1/authentication/api-token REST API endpoint to request a token based on the supplied user name and password
curl -H "Content-Type:application/json" -X POST -d
'{ "user":"admin@dotcms.com", "password":"admin", "expirationDays": 10 }'
https://demo.dotcms.com/api/v1/authentication/api-tokenThe call returns a JSON result containing the token
Providing the Token with Subsequent Requests
The following curl command supplies the previously retrieved token to authenticate a call to a different REST API endpoint (/api/v1/users/current)
curl -H "Authorization:Bearer ##TOKEN##\
-X GET https://demo.dotcms.com/api/v1/users/currentC. API Playground
The API Playground is a tool that allows users to browse, explore, and try out dotCMS's REST APIs. Powered by Swagger, the API Playground exposes all API endpoints, and provides a convenient testbed to perform queries.
You can access the API Playground using two methods
Once logged into your dotCMS environment, you can access the API playground by navigating to Dev Tools > API Playground
On the Documentation site at the following link: https://docs.dotcms.com/docs/latest/all-rest-apis
5. JavaScript SDK
The JavaScript SDK consists of two types of library:
The dotCMS client library
@dotcms/client interacts securely with the dotCMS instance API.
Rendering libraries
Contain components and utilities to render the content and interact with the Universal Visual Editor
@dotcms/react supports sites and applications built using ReactJS.
@dotcms/angular covers the Angular framework.
6. Plugins
Plugins in dotCMS are powerful and can modify the dotCMS platform and even underlying OS when needed.
Benefits of OSGi Plugins
Can be deployed and hot-swapped at runtime without needing an application server restart/reload.
Are easy to develop and deploy on a running dotCMS system.
Provide methods to easily implement new functionality in dotCMS via understandable extension points.
Provide a separate class loading environment in which you can deploy different versions of common libraries used by dotCMS.
Can interact with dotCMS's classloader to override any class inside dotCMS.
Can be Push Published between environments.
Are stored as plain OSGi bundles.
Important Notes Regarding Plugins
Plugins, even those developed by dotCMS, live outside of the core system and are not supported by dotCMS without an additional OSGi support engagement.
By definition, plugins override dotCMS code.
All plugins run the risk of breaking existing dotCMS functionality.
Click here to learn more about using Plugins with dotCMS.
7. Further Learning and Troubleshooting
dotCMS Documentation: https://dotcms.com/docs
dotCMS Video Training: https://dotcms.com/courses/
dotCMS Guided Tour: https://docs.dotcms.com/docs/latest/guided-tour
dotCMS User Group: https://community.dotcms.com/
You're now set up and ready to build with dotCMS! 🚀