Deployment and next steps
In this final chapter, we’ll look into how you can deploy your application for real-life usage. There are essentially two options - Enonic Cloud, and everything else.
Enonic Cloud is our fully managed and hassle free hosting option. Sit back, relax and let Enonic take care of your infrastructure, monitoring, backups, etc.
Enough with the sales pitch. Follow the steps below to get deploy your app on Enonic Cloud:
Sign up for a free trial by visiting https://cloud.enonic.com (no credit card needed)
Create a new solution. Choose the
CMS essentialstemplate, and go with the default values
Connect CLI to the cloud by running this command, and follow the instructions:
enonic cloud login
From your project folder, install the app by running this command:
enonic cloud app install
From the Cloud console, verify that the app was installed to your selected environment.
Since the cloud instance is a completely new environment, the content you created locally will not be available here.
You can choose to a) manually create new content on the server, or b) export and import content from your local machine to the server.
Lets try the import:
In your local sandbox - Using Content Studio, select the root item you want to export (for instance the site)
From the context panel on the right, open the
Click export, select and download the export (this will place a zip file on your local device)
Via Cloud Console, sign into to your XP environment by clicking the login button for your environment.
Launch Content Studio, and open the
Data toolboxpanel on your server instance.
Using Data toolbox, upload and then import the file that was saved on your local device. Content studio should now fill up with content items.
Finally, select the root item, and select
Publish treefrom the top right action menu in Content studio. After publishing, validate that your content is listed as "Published".
With the app installed, and fresh content available - we are ready for the final step.
To make your content accessible publicly, the final step is to create a Route. Follow these steps to complete the task:
From the Cloud console, go to
Routesand click create. Choose the following options:
Choose target environment (if there are more than one)
Accept the default domain
Use the internal path
/site/default/master(Given that this actually matches your content project)
The public path could for instance be
Once the route has been created, you may click its link in the Cloud console to visit it.
Congratulations, your API is now live, with your content :-)
For more information on Enonic Cloud, visit the Enonic Cloud marketing page.
If Enonic Cloud isn’t your thing, you need to start by getting the platform (Enonic XP) up and running, before you can actually deploy your application.
Enonic XP is compatibile with just about any public cloud out there. There’s a number of different deployment strategies and subscription options to choose from, based on what suits your particular situation best.
Setting up the entire platform is beyond the scope of this tutorial. As such, we’ll focus on the steps required for getting your app live - assuming you already have the platform running.
For more details on deplying the platform, check out the deployment section of the XP reference docs.
Regardless of how you deploy your XP instance, installing your app is commonly done in one of two ways:
Follow these simple steps:
|Your application executable (*.jar file) can be found in
Log into the XP admin console (user must have Administrator priveliges)
From the XP menu, open the Applications tool.
Choose install from the toolbar, and upload your application
.jarfile. You can drag and drop your application or navigate the file hierarchy via the upload button.Figure 1. Drag and drop applications to upload them
If you have access to your server’s management API (available on port 4848), you can also deploy directly via this endpoint, or by using the CLI.
This approach is most commonly used in a Continuous Integration/Delivery setup, where your build server automatically checks out, builds and installs the application.
When accessing XP resources such as the GraphQL API explorer in this tutorial, the URLs have been long and unsightly. In a production setting you want short, pretty URLs that are easy to remember. Virtual host (vhosts) configuration lets you do just that.
Setting up a vhost is only required once per application/site you want deploy.
Vhosts can be defined in your sandbox’s configuration directory. This file contains mappings from public-facing URLs to internal URLs. For instance, this lets the user access
my-first-site.com/api and while retrieving content from
An example vhosts file that achieves the mapping mentioned would look something like this:
enabled = true (1) mapping.example.host = my-first-site.com (2) mapping.example.source = / (3) mapping.example.target = /site/default/master
|1||Enable vhosts configuration|
|2||For all requests to
|3||Map any request that starts with this path …|
|4||… to the internal URL.|
For more details on virtual hosts, head to the Vhosts section of the deployment documentation.
To explore how vhost mappings work, let’s configure vhosts for our local XP instance. Then, to test it, we’ll have override your computer’s DNS resolver by updating it’s
Find and open your sandbox’s vhosts file. From your user’s home directory, the path will be
<sandbox-name>varies depending on which sandbox you want to configure. For instance, it might be
Update the vhosts file.
enabled = true mapping.admin.host = xp-admin.com (1) mapping.admin.source = / mapping.admin.target = /admin mapping.admin.idProvider.system = default mapping.localhost.host = localhost (2) mapping.localhost.source = / mapping.localhost.target = / mapping.localhost.idProvider.system = default
1 If requests go to
xp-admin.com:8080, send them to
2 This block allows the localhost mappings to keep working. Without this,
localhost:8080wouldn’t work anymore.
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.
To test this out, update your local hosts file (hosts file on Wikipedia) to point
127.0.0.1by 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
http://xp-admin.com:8080in 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
http://xp-admin.com:8080 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 xp-admin.com:8080/tools
If the connection is successful, one of the lines in the output should say something to the effect of
* Connected to xp-admin.com (127.0.0.1) 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.
Congrats! You’ve reached the end of this introduction. If you’d like to go further now, try one of the following guides which introduce additional aspects of the Enonic 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.
- Building sites with Enonic and Next.js
Everything you need to start building Next.js-based sites with Enonic as your CMS. This integration allow editors to enjoy full WYSIWYG editing
- My first site
If you’re interested in building a traditional CMS-based application with server rendered pages in Enonic (no 3rd party framework required), this is the guide for you. It covers building pages and using building blocks such as regions, parts, and page templates.
- My first webapp