Deployment and next steps


Working on your local copy is great for development, but you can’t expose what you build to someone else that way. For that, you need to deploy XP and your app to somewhere. In this chapter, we’ll give a high-level overview of how you do just that.


You have two main choices for deploying XP, as described below:

Enonic Cloud

This is our fully managed and hassle free hosting option. Sit back, relax and let Enonic take care of your infrastructure, including monitoring, backups, automation, and more.

Enonic Cloud is the easiest way of getting Enonic up and running. To learn more about it and get a free trial, head over to the Platform as a Service page.

Self-hosted (Software)

If Enonic Cloud isn’t for you, you can also run the Enonic platform yourself. There’s a number of different deployment strategies and subscription options to choose from, based on what suits your particular situation best.

To learn more about our software offerings and deployment strategies, check out the deployment section of the XP reference docs.

Uploading apps

Regardless of how you deploy your XP instance, installing your application can be done in the same way.

To upload an app:

  1. Log into your XP deployment

  2. Use the admin menu to navigate to the applications page

  3. Choose install from the toolbar and upload your application .jar file. You can drag and drop your application or navigate the file hierarchy via the upload button.

    The application installation menu with a blue overlay. The overlay says 'drop files to upload'
    Figure 1. Drag and drop applications to upload them
Deployment can also be done directly from CLI, which is useful in a Continuous Integration setup.

Virtual hosts = pretty URLs

When accessing XP resources such as the GraphQL API explorer in this tutorial, the URLs have been long and unsightly. When working in production environment, this isn’t something you want. Instead, you want short, pretty URLs that are easy to remember. Virtual hosts (vhosts) configuration lets you do just that.

Your vhosts file is a configuration file that sits in your XP sandbox’s configuration directory. This file contains mappings from public-facing URLs to internal URLs. This lets the user access and retrieve content from /site/default/master/my-first-site/api.

An example vhosts file that achieves the mapping mentioned could contain the following:

enabled = true (1) = (2)
mapping.example.source = / (3) = /site/default/master/my-first-site/
1 Enable vhosts configuration
2 Intercept requests to
3 Map any request that starts with this path …​
4 …​ to the internal URL.

To read more about virtual hosts, head to the Vhosts section of the deployment documentation.

Task: local vhosts config

To explore how vhosts mappings work, let’s configure vhosts for our local XP instance. Then, to test it, we’ll configure our local hosts file.

  1. Find and open your sandbox’s vhosts file. From your user’s home directory, the path will be .enonic/sandboxes/<sandbox-name>/home/config/com.enonic.xp.web.vhost.cfg, where <sandbox-name> varies depending on which sandbox you want to configure. If it is your first one, it’ll be Sandbox1.

  2. Update the vhosts file.

    enabled = true = (1)
    mapping.admin.source = / = /admin
    mapping.admin.idProvider.system = default = localhost (2)
    mapping.localhost.source = / = /
    mapping.localhost.idProvider.system = default
    1 If requests go to, send them to :8080/admin
    2 This block allows the localhost mappings to keep working. Without this, localhost:8080 wouldn’t work anymore.
  3. If you’re watching your XP process, you should see a message like this:

    2021-06-09 13:49:43,405 INFO  c.e.x.s.i.config.ConfigInstallerImpl - Loaded config for [com.enonic.xp.web.vhost]
    2021-06-09 13:49:43,411 INFO  c.e.x.w.v.i.c.VirtualHostServiceImpl - Virtual host is enabled and mappings updated.

    This means that XP has updated the mappings and is ready to go.

  4. To test this out, update your local hosts file (hosts file on Wikipedia) to point to by adding the following line to the file:
    On Linux and macOS you’ll find the hosts file at /etc/hosts. On Windows, it’s located at c:\Windows\System32\Drivers\etc\hosts
  5. Now access in your browser. If all has gone well, you should see the familiar XP login screen.


If you’re not seeing anything when you direct your browser to or aren’t able to access the resources, that may be due to a browser setting. Try using a different browser and see if that makes a difference. Alternatively, you can try running

curl -v

If the connection is successful, one of the lines in the output should say something to the effect of

* Connected to ( port 8080 (#0)

and you should get a massive block of HTML printed to the terminal. This HTML is the content of the login page in raw form.

You might not be able to do much with that output, but it means the mapping has worked successfully, which is the important part for this task.

What’s next?

Congrats! You’ve reached the end of the introduction for now. This document is still a work in progress and new content will be added at a later date. If you’d like to go further now, why don’t you try one of the following guides which introduce extra aspects of the XP experience?

Introduction to headless CMS

If you’ve enjoyed the headless aspects of this introduction, why not visit this guide to further your knowledge of how to use the GraphQL API and how to customize it.

My first site

If you’re interested in building a traditional CMS-based application with server rendered pages, this is the guide for you. It covers building pages and using more Content Studio building blocks such as regions, parts, and page templates.

My first webapp

If you’re more interested in building web apps than web sites, how about this guide which focuses more on the web app aspects, including JavaScript controllers, serving assets, and routing.