Setup instructions for Docker + dotCMS on Windows

[Rob]

I'm attempting to get a local install of dotCMS on my Windows machine via Docker. I have found bits of information how to do this on the dotCMS site and in web searches but still isn't working for me. I'm hopeful there are some detailed instructions that could get me all the way up and running.

[Jameson Mauro]

[I accidentally clicked Reply to Author instead of All, so I'm resending for general consumption. Apologies to Rob for the spam!]

Hey Rob,

Our quick start guide is in need of an update, and I'll be working on that in the near future. For now, the quickest way to get started, once you've got Docker Desktop installed, is to open up the command prompt ("cmd" from Start) and paste in one of the two commands on our download page, reproduced below.

• For the Demo version, with the complete demo site visible at https://demo.dotcms.com/, you'll need this command:
      curl -o docker-compose.yml https://dotcms.com/run/demo && docker-compose up
• For a completely clean install with no pre-populated content, it'd be this version:
      curl -o docker-compose.yml https://dotcms.com/run/clean && docker-compose up

(Note: Windows 10 & 11 both come with the curl command built in; if you're using Win 7 or 8, you'll need to install it from https://curl.se/.)

The process of spinning up the containers will take a few minutes, but by the time you see a line along the lines of "INFO  reindex.ReindexThread - --- ReindexThread Paused (every 3600000 millis)" in the midst of "caffine.CaffineCache" messages, you've hit the end of the line. At that point, visit http://localhost:8080/dotAdmin to log in with username ad...@dotcms.com and password admin. (Or, you could just visit http://localhost:8080/ on its own, which will show either a copy of the Demo site if you used the demo YAML, or a 404 error in the case of the Clean one.)

To close out of the command line session gracefully, you can mash Ctrl+C until you're back to the prompt. From that point on, you can reactivate dotCMS straight from Docker Desktop by hitting the little "play" button next to the container you just built; no further CLI commands required.

If you've previously tried the above, but have run into errors, there's good news: In the last couple hours, we've updated the starter image links in the YAML files, so the commands above should both work equally well, now. That said, in that case, you'll need to delete any previously created dotCMS containers and images, to ensure the new ones pull properly. See the pics below:

 

Let me know if this helps!

Jamie Mauro

Technical Writer

dotCMS

[Jameson Mauro]

The username of "admin[at]dotcms.com" got truncated for some reason, apologies!

[Rob]

Thank you so much Jamie, these instructions worked like a charm for me!

[Rob]

Installed and running great Jamie! Now suppose I want to edit VTL files within the container, make new templates or experiment with the velocity code. Can you recommend a good way for doing that? The dotCMs training videos all look to be done using a localhost (not Docker). Thanks!

[Jameson Mauro]

Hey Rob,

Sorry for the delayed response. You've got a couple of options for editing VTLs (etc) from within a Docker environment. 

Option 1: From the admin panel, hit Site -> Browser. The built-in browser allows direct manipulation of assets such as VTLs. So, for example, if you build a theme (which is to say, creating a subfolder of /application/themes/) and build a template.vtl file there, editing it within the site browser gives a view along these lines:

Option 2: You can use WebDAV to handle file uploads/downloads even within a local Docker instance. (We generally recommend Cyberduck — it's free, stable, and dependable.)

Setting it up is similar to how one might set it up for normal web access, albeit using the localhost address. So, for example, I just got it running for a Docker session using the following config:

Note: If you don't see the "More Options" section, try opening it with the "+" button at the bottom instead of the "Open Connection" button at the top. And since you're on HTTP for this setup, it'll give a warning about transmitting a password in plaintext. Just ignore that; all of this is happening local to your machine, so it's no biggie.

Once you've got that set up, you can easily download or upload files or folders right from your local directory structure to your dotCMS instance.

Some docs that may be of use (a few of which were already linked above, but why not):

• Upload and Edit Via WebDAV
• Creating a New Theme
• Creating the Template VTL File
• Adding a Container
• If you've been playing with the Demo site, you may notice most of the containers in use there (like Default) are File-Based Containers, which are a bit like Themes insofar as they consist of various VTL files in a folder. These differ a bit from the kind that live in the database and are edited from the Site -> Containers tool, hence this bullet point & link!
• Templating (includes some useful diagrams for how Themes, Containers, Templates, etc fit together)

Hope this helps!

[Rob]

Thanks Jamie, this worked perfectly!

Question: Is it possible to have more than one dotCMS container installed locally? I already had one installed with the sample content but would like to setup a second if possible with no content. When I ran the command provided for no content (above) it seemed to install in the same location without prompting me but when I run it I'm still seeing the version with the sample content. Thanks again!

[Jameson Mauro]

Hey Rob,

It is indeed possible! Two notes contributing to a hopefully complete explanation of what you've described:

1. Regarding the "installing to the same container" part: It sounds like the issue you're running into here involves the Docker "project name" variable, which defaults to the base directory that the docker-compose.yml file is run out of. Here's a Stack Overflow answer that covers various options for addressing this; the two simplest workarounds are either to use the -p command-line option to specify a new project name (e.g. for "project2," you'd use docker compose -p project2 up), or to run the file from a directory with a different name. There are other solutions discussed as well, involving an environment variable — which might be the best approach for keeping a bunch of containers organized in the long term.
   • Important note: If you use the same port bindings, you'll need to stop the first container to bring the new one up; to run multiple dotCMS containers simultaneously, they'll need to be listening on different ports.
2. Regarding the "still seeing the sample content" part: If you don't delete the previously created dotCMS image, it may continue to use one previously pulled — especially when it thinks it's supposed to bring an existing container back up. That said, it shouldn't be necessary to delete an old image if you're starting a whole new container, per 1).
   

-Jamie