Docs Developer Site
Developer 10111 - Deployment

Deployment and next steps

Contents

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.

Deploy to Enonic Cloud

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:

Task: Install application

  1. Sign up for a free trial by visiting https://cloud.enonic.com (no credit card needed)

  2. Create a new solution. Choose the CMS essentials template, and go with the default values

  3. Connect CLI to the cloud by running this command, and follow the instructions:

    enonic cloud login

  4. From your project folder, install the app by running this command:

    enonic cloud app install

  5. From the Cloud console, verify that the app was installed to your selected environment.

Task: import and publish your content

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:

  1. In your local sandbox - Using Content Studio, select the root item you want to export (for instance the site)

  2. From the context panel on the right, open the Data toolbox widget.

  3. Click export, select and download the export (this will place a zip file on your local device)

  4. Via Cloud Console, sign into to your XP environment by clicking the login button for your environment.

  5. Launch Content Studio, and open the Data toolbox panel on your server instance.

  6. 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.

  7. Finally, select the root item, and select Publish tree from 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.

Task: Go live

To make your content accessible publicly, the final step is to create a Route. Follow these steps to complete the task:

  1. From the Cloud console, go to Routes and 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 /imadeit

  2. 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.

Deploy elsewhere

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.

Installing the app

Regardless of how you deploy your XP instance, installing your app is commonly done in one of two ways:

Task: Alt 1 - via Admin Console

Follow these simple steps:

Your application executable (*.jar file) can be found in project-folder/build/libs/

  1. Log into the XP admin console (user must have Administrator priveliges)

  2. From the XP menu, open the Applications tool.

  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

Alt 2: via API

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.

Virtual hosts = pretty URLs

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 /site/default/master/my-first-site/api.

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 (4)
1 Enable vhosts configuration
2 For all requests to my-first-site.com
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.

Task: Setup vhosts in your Sandbox

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 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. For instance, it might be Sandbox1.

  2. 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 :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 xp-admin.com to 127.0.0.1 by adding the following line to the file:

    127.0.0.1 xp-admin.com
    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 http://xp-admin.com:8080 in your browser. If all has gone well, you should see the familiar XP login screen.

Vhost troubleshooting

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.

What’s next?

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

Build webapps and APIs directly in Enonic. Focuses on JavaScript controllers, serving assets, and routing.

Contents