dotCMS Developer Instance

This dotCMS developer image is a docker image specifically created for dotCMS development. It contains all the services that are required to run dotCMS - including Postgres 16 and Opensearch 1.x. It also includes a 90 day Developer License, which enables dotCMS Enterprise functionality that is required to run dotCMS with UVE.

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. One important feature of this image is that it can be used to CLONE an existing dotCMS instance.

TL;DR

Cut and paste this below to run an clean dotCMS dev environment. All data and assets will be stored in the directory ./data

docker run --rm \
-p 8443:8443 \
-v $PWD/data:/data \
 dotcms/dotcms-dev:nightly

After this, you will find the admin password in the log output. 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

LTS Images

We have built development images for the last 2 LTS versions. Keep in mind that if you start up with a newer or latest image, you cannot downgrade your data to an older LTS version as the data formats are not guarenteed to be backward compatable. Instead, you should move your ./data directory and start fresh. From an older version, you can alway upgrade to a newer version or the latest version.

24.04

docker run --rm \
-p 8443:8443 \
-v $PWD/data:/data \
dotcms/dotcms-dev:24.04_lts

23.10

docker run --rm \
-p 8443:8443 \
-v $PWD/data:/data \
dotcms/dotcms-dev:23.10_lts

Cloning an Environment

If you specify a source environment and a valid means to authenticate, the image will attempt to pull the assets and db from the source environment.

Note: The source environment you want to clone has to be running a dotCMS version equal to or less than your development image.

To do this, you start the image up and pass it a DOTCMS_SOURCE_ENVIRONMENT and either an DOTCMS_API_TOKEN or DOTCMS_USERNAME_PASSWORD (format: admin@dotcms.com:admin). On startup, the image will try to reach out and download the database and assets from the specified dotCMS instance, load the db and assets and start dotCMS in debug mode. Once the server starts, if you have loaded from a dump, you might to run a full reindex before the content is shown, depending on your dotCMS version.

Clone with an API Token

This pulls down the assets and a SQL dump that is then imported into the new dotCMS instance. You will need to login with the same credentials that are used in the target environment.

export TOK=XXXXXXX_YOUR_DOTCMS_TOKEN.eXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

docker run --rm \
-p 8443:8443 \
-v $PWD/data:/data \
-e DOTCMS_SOURCE_ENVIRONMENT=https://demo.dotcms.com \
-e DOTCMS_API_TOKEN=$TOK \
 dotcms/dotcms-dev:nightly

Clone with UserID/Password

This pulls down the assets and a SQL dump that is then imported into the new dotCMS instance. You will need to login with the same credentials that are used in the target environment.

docker run --rm \
-p 8443:8443 \
-v $PWD/data:/data \
-e DOTCMS_SOURCE_ENVIRONMENT=https://demo.dotcms.com \
-e DOTCMS_USERNAME_PASSWORD="admin@dotcms.com:admin" \
 dotcms/dotcms-dev:nightly

Clone using a starter.zip

This asks the source server to generate a starter.zip, which can be time-consuming to generate AND to import initially.

docker run --rm \
-p 8443:8443 \
-v $PWD/data:/data \
-e DOTCMS_SOURCE_ENVIRONMENT=https://demo.dotcms.com \
-e DOTCMS_USERNAME_PASSWORD="admin@dotcms.com:admin" \
-e DOTCMS_CLONE_TYPE=starter \
dotcms/dotcms-dev:nightly

DEV DEBUG - with Postgres port exposed.

In this case dotCMS java waits to start up until a debugger is connected to it on port 8000.

docker run --rm  \
--pull always \
-p 8443:8443 \
-p 5432:5432 \
-p 8000:8000 \
-v $PWD/data:/data \
-e DOTCMS_DEBUG=true \
 dotcms/dotcms-dev:nightly

Config Env Switches

This image takes all the normal dotCMS docker environmental variable config switches - keep in mind that the DB and ES come pre-wired, so no need to change those. This image also takes the following env variables:

• DOTCMS_SOURCE_ENVIRONMENT : the url for the environment you wish to clone, e.g. https://demo.dotcms.com .
• DOTCMS_CLONE_TYPE : either dump or starter, defaults to dump. Set this to dump to take a database dump and asset backup (recommended for large sites). Set this to starter to force the target environment to generate a starter to download (slower).
• DOTCMS_API_TOKEN : A valid dotCMS API Token from an admin user in the source environment.
• DOTCMS_USERNAME_PASSWORD : The username:password for an admin user in the source environment.
• DOTCMS_DEBUG : Run dotCMS in debug mode and listen for a remote debugger on port 8000, defaults to false.
• ALL_ASSETS : Controls whether old versions of assets are included in the download, defaults to false, which means only the current live and working versions of assets will be downloaded.

If you need to map in a custom certificate, you can do this by creating a .pem file of your certificate, private key and ca-chain. The password for the .pem should be set to dotcms and should map the generated pem file to /srv/dotserver/tomcat/conf/local.dotcms.site.pem in order to override the default certificate.

Troubleshooting the Download

Due to a bug in docker, downloading large environments can time out. To get around this, you can download the assets and db yourself (outside of docker) to seed your installation and add them to the data volume you map into the image. dotCMS will look for /data/assets.zip and/or /data/dotcms_db.sql.gz to import before running the normal starter import routine.

Downloading your assets and db outside of Docker

dotCMS offers two admin only endpoints to download your data and assets

• /api/v1/maintenance/_downloadAssets
• /api/v1/maintenance/_downloadDb

When downloading assets, you can specify ?oldAssets=false, and dotCMS will only include the assets for live and working versions of your content, thus hopefully generating a MUCH smaller download

Example wget to download assets

wget --header="$AUTH_HEADER" \
-t 1 -O assets.zip  \
$DOTCMS_SOURCE_ENVIRONMENT/api/v1/maintenance/_downloadAssets

Example wget to download your DB

wget --header="$AUTH_HEADER" \
-t 1 -O dotcms_db.sql.gz \
$DOTCMS_SOURCE_ENVIRONMENT/api/v1/maintenance/_downloadDb 

Example wget to download a new starter.zip

wget --header="$AUTH_HEADER" \
-t 1 -O starter.zip \
$DOTCMS_SOURCE_ENVIRONMENT/api/v1/maintenance/_downloadStarterWithAssets

Starting from a clean slate

Your development instance can be deleted and reset by deleting the ./data directory that is mapped in.

Building this Image

By default, this image is built from this directory https://github.com/dotCMS/core/tree/main/docker/dev-env and uses the dotcms/dotcms:latest tagged version of dotCMS. You can specify another dotCMS version you want use for your dev instance by passing the build-arg DOTCMS_DOCKER_TAG to indicate which dotCMS image tag to use to build, e.g. --build-arg DOTCMS_DOCKER_TAG=latest or --build-arg DOTCMS_DOCKER_TAG=23.07

docker build --pull \
--build-arg DOTCMS_DOCKER_TAG=testing  \
-t dotcms/dotcms-dev .

or

docker buildx build \
--build-arg DOTCMS_DOCKER_TAG=latest \
--platform linux/amd64,linux/arm64 \
--pull \
-t dotcms/dotcms-dev:testing .

Included Database and Elasticsearch

This image runs the following servers internally.

Opensearch 1.3.11

Running https on

• https on port 9200
• basic auth (admin/admin)
• data stored in /data/opensearch

Postgres 16 with pg_vector

Running on port 5432 and using the dotCMS defaults:

• db: dotcms
• user: dotcmsdbuser
• pass: password
• data stored in /data/postgres

If you wish to connect to these instances remotely, you will need to expose their ports in docker when you run the image, e.g.