How to enable Lucee on a domain using Tomcat (VPS/Dedicated only) Print

If you have a VPS or dedicated server with Lucee installed and need to add a new domain to the service, this guide walks through editing the Tomcat server.xml configuration file to register the new domain, then restarting Lucee to apply the changes.

On shared or reseller hosting? Lucee is enabled automatically on all domains, no configuration needed. See: Using Lucee on shared and reseller hosting.

Before you start

You will need:

• SSH or SFTP access to your server
• The full path to your domain's web root (e.g. /home/username/public_html or /var/www/yourdomain.com)
• A text editor, nano or vi via SSH, or an SFTP client such as FileZilla to download, edit, and re-upload the file

Step 1: Locate the Tomcat server.xml file

Connect to your server via SSH or SFTP. The default Lucee installation path on Host Media servers is:

/opt/lucee/tomcat/conf/server.xml

If you are unsure of the path, search for it via SSH:

find / -name "server.xml" -path "*/tomcat/*" 2>/dev/null

Take a backup first: Before making any changes, copy the existing file:

cp /opt/lucee/tomcat/conf/server.xml /opt/lucee/tomcat/conf/server.xml.bak

Step 2: Add a new Host entry

Open server.xml in your editor and locate the HOST ENTRY TEMPLATE comment block. Add the following block after it, replacing yourdomain.com with your domain name and the docBase with the full path to your web root:

<Host name="yourdomain.com"
      appBase="webapps"
      unpackWARs="true"
      autoDeploy="true"
      xmlValidation="false"
      xmlNamespaceAware="false">

  <Context path="" docBase="/home/username/public_html" />
  <Alias>www.yourdomain.com</Alias>

</Host>

Key values to customise:

• name: your bare domain without www (e.g. example.com)
• docBase: the full server path to the folder containing your CFML files
• Alias: the www version so both resolve correctly. Add additional <Alias> lines for any further aliases needed

Important: Do not create duplicate Host entries for the same domain. Lucee will fail to start if it finds two <Host> entries with the same name value. Search the file for your domain before adding a new entry to confirm it is not already listed.

Step 3: Save and upload the file

If you edited the file locally via SFTP, upload it back to /opt/lucee/tomcat/conf/server.xml overwriting the existing file. If you edited directly on the server via SSH, save and close the file.

Step 4: Restart the Lucee service

The change will not take effect until Lucee is restarted. Run the following via SSH:

sudo systemctl restart lucee

If your server uses the older init.d system (use this if systemctl is not available):

sudo /etc/init.d/lucee_ctl restart

Allow up to 30 seconds for the service to come back up.

Step 5: Verify the domain is working

Once restarted, navigate to the Lucee web administrator for your domain to confirm it is running:

http://www.yourdomain.com/lucee/admin/web.cfm

On first access you will be prompted to set a password for the web administrator. Once set, the domain is active and ready to serve CFML.

Troubleshooting

Lucee fails to start after editing server.xml

This almost always means a syntax error in the XML or a duplicate host entry. Check the Tomcat logs for the specific error:

tail -100 /opt/lucee/tomcat/logs/catalina.out

Common causes: a missing closing tag, mismatched quotes, or two <Host> blocks with the same name. If needed, restore your backup and try again:

cp /opt/lucee/tomcat/conf/server.xml.bak /opt/lucee/tomcat/conf/server.xml
sudo systemctl restart lucee

SES (Search Engine Safe) URLs returning 404 errors

If your CFML application uses SES URLs in the format /index.cfm/some/path and these return a 404, the Tomcat servlet mapping needs an additional entry in web.xml.

Locate web.xml (typically at /opt/lucee/tomcat/conf/web.xml) and find the existing CFMLServlet servlet-mapping blocks for *.cfm, *.cfml, and *.cfc. Add the following alongside them:

<servlet-mapping>
  <servlet-name>CFMLServlet</servlet-name>
  <url-pattern>/index.cfm/*</url-pattern>
</servlet-mapping>

Save the file and restart Lucee. SES URLs should resolve correctly afterwards. If your application uses a different entry point (e.g. /index.cfml/*), add an equivalent mapping for that pattern too.

Domain loads but shows the wrong site

Check the docBase path in your Host entry, if it points to the wrong directory, Lucee will serve files from there instead. Also check for a conflicting Apache or Nginx virtual host for the same domain that may be intercepting requests before they reach Tomcat.

If you would prefer our team to handle this configuration, open a support ticket and we are happy to help.