Installing OpenCMS

OpenCms is a web content management system written in Java, free software under the LGPL, maintained by Germany's Alkacon Software. It is not the CMS you install on R$ 20 shared hosting — it is what companies and public agencies put on Tomcat to manage institutional websites with approval workflows, versioning, and multiple languages.

Where OpenCms came from

The story starts before the name. Between 1994 and 1998, Alexander Kandzior developed a system at BKM Online medien GmbH called Mht — Meta-Hyper-Text. It was closed-source code, an internal tool at a consulting firm.

In 1998, BKM merged and became mindfact interactive medien AG. And here is the decision that created the project: since mindfact's business was internet consulting, not software sales, the company concluded there was no point keeping the code private. The next version of Mht was published as free software.

The public release happened in March 2000, under LGPL, with a new name: OpenCms. Kandzior later founded Alkacon Software, in Cologne, which coordinates development to this day. It follows the same pattern as OTRS and GLPI: an internal tool at a German or French company becomes a free software project and gains a software publisher around it.

What distinguishes it from both is the platform. While GLPI is PHP and OTRS is Perl, OpenCms has always been pure Java — which explains both its strength (it runs on any system with a JVM and scales in a servlet container) and its niche (you need Tomcat, which rules out half the market).

What it does

• In-place editing — the editor works on the page itself, without a separate panel.
• Publishing workflow — content lives in an offline project and only goes live when someone publishes. No “I saved it and it went to production.”.
• Versioning — each file's history, with rollback.
• XML-structured content — content has a schema; it is not just a loose rich-text field.
• Multi-site and multilingual on a single server.
• Mercury — the modern, responsive template bundled with the distribution.

Requirements in 2026

Here is the change most likely to break an old installation: OpenCms 21 requires Java 21 or newer, and is compatible through Java 25. And it must be the JDK, not the JRE.

• Java: JDK 21 or higher.
• Servlet container: Tomcat or Jetty.
• Database: MariaDB or MySQL — with the blob size adjustment before installation, or setup fails halfway through.

The shortcut: Docker

It did not exist in 2017 and solves the whole problem: Alkacon publishes an official image with the correct Java and Tomcat versions already included.

services:
  db:
    image: mariadb:11
    restart: always
    command: --max_allowed_packet=64M --innodb_log_file_size=256M
    environment:
      MARIADB_ROOT_PASSWORD: troque-esta-senha
    volumes:
      - ./dbdata:/var/lib/mysql

  opencms:
    image: alkacon/opencms-docker:21.0.1
    restart: always
    depends_on: [db]
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - ./opencms:/usr/local/tomcat/webapps/ROOT/WEB-INF/config

docker compose up -d
# assistente de instalação: http://127.0.0.1:8080/setup/

Manual installation on Tomcat

If you prefer controlling every component, the path is still the same as in 2017 — with updated versions.

1. The database adjustment nobody can skip. OpenCms stores files as BLOBs in the database, and MariaDB's default packet size is too small. Without this, installation breaks when importing modules:

sudo tee /etc/mysql/mariadb.conf.d/60-opencms.cnf >/dev/null <<'EOF'
[mysqld]
max_allowed_packet = 64M
innodb_log_file_size = 256M
EOF

sudo systemctl restart mariadb
sudo mariadb -e "SHOW VARIABLES LIKE 'max_allowed_packet';"

sudo mariadb -e "CREATE DATABASE opencms CHARACTER SET utf8mb4;"
sudo mariadb -e "CREATE USER 'opencms'@'localhost' IDENTIFIED BY 'troque-esta-senha';"
sudo mariadb -e "GRANT ALL ON opencms.* TO 'opencms'@'localhost'; FLUSH PRIVILEGES;"

2. Java and Tomcat. Check the version before downloading anything — this is where most 2017 installations fail today:

sudo apt install -y openjdk-21-jdk
java -version        # precisa ser 21 ou mais novo

3. OpenCms. Download the package from the official download page — it includes the core plus the Mercury template:

sudo systemctl stop tomcat

cd /tmp
unzip opencms-*.zip
sudo mkdir -p /usr/local/tomcat/webapps/opencms
sudo unzip -d /usr/local/tomcat/webapps/opencms opencms.war
sudo chown -R tomcat:tomcat /usr/local/tomcat/webapps/opencms

sudo systemctl start tomcat
# assistente: http://SEU-SERVIDOR:8080/opencms/setup/

Once the wizard is finished, delete the setup directory — leaving it online is an open invitation:

sudo rm -rf /usr/local/tomcat/webapps/opencms/setup

Nginx in front (and why AJP was removed)

The original post used mod_proxy_ajp from Apache. Do not do this anymore. The AJP connector was targeted by Ghostcat (CVE-2020-1938), which allowed reading arbitrary application files, and since Tomcat 9.0.31 it has been disabled by default — when present. Use plain HTTP:

server {
    listen 443 ssl;
    http2 on;
    server_name site.exemplo.com.br;

    ssl_certificate     /etc/letsencrypt/live/site.exemplo.com.br/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/site.exemplo.com.br/privkey.pem;

    client_max_body_size 200m;   # upload de mídia no editor

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

And close 8080 in the firewall: Tomcat must never be directly accessible from the internet.

Is it worth it in 2026?

It depends on your situation:

• It makes sense if your organization already uses Java, if you need a real editorial approval workflow, versioning, and multiple languages, and if the site is institutional with many editors and publishing rules.
• It does not make sense if you want a blog or store: the PHP ecosystem has WordPress and Magento with an order of magnitude more themes, plugins, and people who know how to use them.
• Infrastructure costs are different. A JVM, Tomcat, and a database with large blobs need more memory than PHP-FPM. This is not a job for a 1 GB VPS.
• The community is small. Just over 500 GitHub stars and a quiet mailing list. In return, the project has delivered new releases on schedule for twenty-five years — and in 2026 even AI translation was added to the content editor.

Timeline

• 1994–1998 — Alexander Kandzior develops Mht (Meta-Hyper-Text) at BKM Online medien, closed-source.
• 1998 — BKM becomes mindfact interactive medien AG, which decides to open the code: consulting does not depend on selling software.
• March 2000 — first public release as OpenCms, under LGPL.
• 2000s — Kandzior founds Alkacon Software, in Cologne, which takes over development.
• 2011 — the code moves to GitHub, at alkacon/opencms-core.
• 2017 — version 10.5, which this post originally taught readers to install.
• April 2026 — OpenCms 21 (build 21.0.1): requires Java 21, is compatible with 25, and brings AI translation to the XML editor.

The original post (April 2017)

Preserved as a record. The procedure below installed OpenCms 10.5 beta and must not be used today — the URL is offline, the version is obsolete, and the AJP proxy is no longer recommended:

## Aumentar o max_allowed_packet do MariaDB para 32M
FILE_DB=/etc/mysql/mariadb.conf.d/50-server.cnf
sed -i "s|max_allowed_packet= 16M|max_allowed_packet= 32M|" ${FILE_DB}
service mysql restart

systemctl stop tomcat
cd /tmp/
wget http://www.opencms.org/downloads/opencms/opencms-10.5.0_beta.zip
unzip opencms-10.5.0_beta.zip
unzip -d opencms opencms.war
mv opencms /usr/local/tomcat/webapps/
chown -R tomcat:tomcat /usr/local/tomcat/webapps/*
systemctl start tomcat
## http://seu_server:8080/opencms/setup/

Original gist: jniltinho/a7bd30288342a5d352e6

Links

• opencms.org · download · documentation
• github.com/alkacon/opencms-core · Alkacon Software
• Here on the blog: Installing Tomcat on Linux · Nginx as a reverse proxy · The main programming languages