Sandboxes

Contents

In this chapter we’ll introduce the fundamental concepts of Enonic XP development. You’ll get a brief introduction to the Enonic command line interface (CLI), XP sandboxes, starter kits, and building and deploying apps on XP. By the end of the chapter you’ll have spun up an instance of XP and deployed an app to it.

There’s lots to cover, so let’s get to it, shall we?

The Enonic CLI

If you haven’t installed the Enonic CLI yet, be sure to check out the installation instructions in the previous chapter.

The Enonic command line interface is a powerful tool, built specifically for Enonic XP. The CLI allows you to interact with XP instances and deploy and develop apps.

To see all available options, run the following command in your terminal:

enonic

It should output something that looks a bit like this:

Main help page
Enonic CLI v.1.5.1
Manage XP instances, home folders and projects

USAGE:
   enonic [global options] command [command options] [arguments...]

COMMANDS:
     snapshot  Create and restore snapshots
     dump      Dump and load complete repositories
     export    Export data from a given repository, branch and content path.
     import    Import data from a named export.
     app       Install, stop and start applications
     repo      Tune and manage repositories
     cms       CMS commands
     system    System commands
     latest    Check for latest version
     vacuum    Removes old version history and segments from content storage
     help, h   Shows a list of commands or help for one command

PROJECT COMMANDS:
     sandbox  Manage XP development instances
     project  Manage XP development projects

GLOBAL OPTIONS:
   --help, -h     show help
   --version, -v  print the version

If you want to know more about how to use one of the subcommands, you can use the help subcommand. For instance, if you want to know more about the sandbox subcommand, you can run

enonic sandbox help

This should result in something like the following being printed to your screen:

Sandbox help page
NAME:
   Enonic CLI sandbox - Manage XP development instances

USAGE:
   Enonic CLI sandbox [global options] command [command options] [arguments...]

VERSION:
   1.5.1

COMMANDS:
     list, ls         List all sandboxes
     start            Start the sandbox.
     stop             Stop the sandbox started in detached mode.
     create           Create a new sandbox.
     delete, del, rm  Delete a sandbox
     upgrade, up      Upgrades the distribution version.

GLOBAL OPTIONS:
   --help, -h  show help

Sandboxes

When talking about sandboxes, we’re actually talking about local instances of Enonic XP. Having a local (and running) instance of XP is essential for an effective development workflow. Using sandboxes allows you to run different versions of XP because each sandbox has an associated XP version. In this guide, though, we’ll stick to using a single sandbox.

Let’s create a new sandbox by using the CLI. When you create a new sandbox, the CLI will present you with a few questions for configuring the sandbox, such as the sandbox name. To respond to a question, type in the desired response and press enter.

Run the following command to get started:

enonic sandbox create

When prompted, give your sandbox the name: tutorial. Next, when asked which XP distribution you want, use the latest one (at the top of the list).

If you press enter without entering a response, the CLI will use the default response. The default response to a question is listed in parentheses after the question.

The CLI will download the Enonic XP SDK distribution for your operating system and link it to the sandbox.

Creating a sandbox
? Sandbox name: tutorial
? Enonic XP distribution: mac-sdk-7.2.0
Downloading distro [===================>--------------------------------]  37.64%

Once completed, we can use the CLI to start the sandbox:

enonic sandbox start

You can also run the sandbox with the --dev flag. This makes the sandbox automatically pick up certain changes to deployed applications, including most of the work we’ll be doing in the coming chapters. Read more about dev mode in the reference docs. With the flag, the command would be

enonic sandbox start --dev

Choose the tutorial sandbox and watch it boot up in your terminal. The boot output should look something like this, but with values adjusted for your system.

Output when booting sandbox
                         _____
____________________________(_)______   ____  _________
_  _ \_  __ \  __ \_  __ \_  /_  ___/   __  |/_/__  __ \
/  __/  / / / /_/ /  / / /  / / /__     __>  < __  /_/ /
\___//_/ /_/\____//_/ /_//_/  \___/     /_/|_| _  .___/
                                               /_/

# Enonic XP 7.6.1
# Built on 2021-02-25T14:26:46Z (hash = 6359021fdb52fda156e39465d824153c915d903c, branch = 7.6)
# OpenJDK 64-Bit Server VM 11.0.10 (AdoptOpenJDK)
# Linux 5.4.108 (amd64)
# Install directory is $HOME/.enonic/distributions/enonic-xp-linux-sdk-7.6.1
# Home directory is $HOME/.enonic/sandboxes/tutorial/home
[...]

The initial output gives you a lot of information about this sandbox, including its home and install directories. We won’t be needing them in this chapter, but knowing where you can find these details might be useful at a later time.

After the sandbox has started, you should see something like the following output in your terminal:

[...] - Started [email protected]{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
[...] - Started [email protected]{HTTP/1.1,[http/1.1]}{0.0.0.0:4848}
[...] - Started [email protected]{HTTP/1.1,[http/1.1]}{0.0.0.0:2609}
[...] - Started @12314ms
[...] - Started Jetty
[...] - Listening on ports [8080](xp), [4848](management) and [2609](monitoring)
[...] - Searching for installed applications
[...] - Found [0] installed applications
[...] - Started Enonic XP in 11207 ms

This means that your local XP instance is up and running and ready to serve requests. The instance exposes the following ports:

  • 8080: Web

  • 4848: Management API (Used by the CLI when running commands against this XP instance)

  • 2609: Monitoring API (Used for metrics and instance info)

To stop your sandbox, press ctrl-c in the terminal hosting the process. You can also run enonic sandbox stop in a different terminal instance.

Troubleshooting

If you have problems booting the sandbox, it may be that one or more of the ports used by XP are already in use. The command should warn you if something doesn’t work right. It’ll do this in one of two ways:

  1. If the CLI checks for the availability of some ports when starting up. If one of these ports isn’t available, the CLI will abort with a message like this:

    Port 8080 is not available, stop the app using it first!
  2. For ports where the CLI doesn’t check for availability before starting, you might get an exception in the boot log. This is usually identifiable by a printed stack trace in your logs. Here’s an example from what happens if port 4848 isn’t available. The […​] replaces most of the stack trace for legibility reasons.

    2021-04-06 11:24:01,168 ERROR c.e.xp.web.jetty.impl.JettyActivator - bundle com.enonic.xp.web.jetty:7.6.1 (80)[com.enonic.xp.web.jetty.impl.JettyActivator(171)] : The activate method has thrown an exception
    org.apache.felix.log.LogException: java.io.IOException: Failed to bind to 0.0.0.0/0.0.0.0:4848
    	at org.eclipse.jetty.server.ServerConnector.openAcceptChannel(ServerConnector.java:349)
    	at org.eclipse.jetty.server.ServerConnector.open(ServerConnector.java:310)
    [...]
    Caused by: java.net.BindException: Address already in use
    	at java.base/sun.nio.ch.Net.bind0(Native Method)
    	at java.base/sun.nio.ch.Net.bind(Net.java:455)
    	at java.base/sun.nio.ch.Net.bind(Net.java:447)
    	at java.base/sun.nio.ch.ServerSocketChannelImpl.bind(ServerSocketChannelImpl.java:227)
    	at java.base/sun.nio.ch.ServerSocketAdaptor.bind(ServerSocketAdaptor.java:80)
    	at org.eclipse.jetty.server.ServerConnector.openAcceptChannel(ServerConnector.java:345)
    	... 78 common frames omitted

If some ports are unavailable, you’ll have to find out what programs are using those ports and then shut those programs down. How you find open ports varies from operating system to operating system, but if you’re unsure about how to do it on your OS, check out the appropriate guide for Linux, macOS, or Windows.

Admin console

With your sandbox running, lets have a look at XP’s admin console. Point your browser to http://localhost:8080.

You should see the default XP login screen:

The XP login screen.
Figure 1. The XP login screen

From the login screen, click "log in without a user". What this actually does is log you in as the XP instance’s super user. Because we’re working on a local development environment for now, we won’t concern ourselves with users and administrators. We’ll talk more about this in a later chapter.

After signing in, you will be greeted by the XP welcome tour. Complete the tour and install the applications listed in the final step. You’ll need some of them later in this tutorial.

A prompt to install a set of applications from the Enonic Market including Content Studio, Live Trace, and Data Toolbox.
Figure 2. The final step of the welcome tour
If the welcome tour does not start automatically or if you want to take it again, you can always click the "XP Tour" icon on the home screen to start it manually.

The applications in the welcome tour all modify the XP admin experience, so once you’ve installed them, you’ll get some extra entries in the XP admin menu that you can explore:

The XP Admin menu with extra apps installed. It shows the newly added apps between the menu items 'Home' and 'Users'.
Figure 3. The XP admin menu with new entries
XP localizes the admin menu item names, so they might be translated to another language based on your settings.

Contents