Docs Developer Site
DeveloperDocsDeveloper 101StableSandbox

Sandbox

Contents

In this chapter we’ll introduce a fundamental concept to start developing with Enonic XP - Sandboxes

By the end, you’ll have created and started a sandbox using the CLI, understanding what it is and what is their purpose.

What is a sandbox?

A sandbox is basically a local developer instance of Enonic XP. Each sandbox may have different versions of XP, different data and configuration.

Having a local (and running) instance of XP is essential for developing apps on Enonic XP.

It is possible to setup multiple sandboxes on your machine, each one of them using XP on a specific version.

Your first sandbox

To create a sandbox using the CLI, start by running the following command:

enonic sandbox create tutorial -t essentials -f

This creates a sandbox called tutorial based on the essentials templat (a set of applications on Enonic Market), and starts it. The -f forces the use of default vaules for all other options.

You will now see a fair amount of output in your terminal, here are the most notable parts:

Creating the sandbox 
Loading templates from Enonic Market...Done.
Using template 'Essentials'
Loading...Done
Downloading distro [=======================================================] 100.00%
Unzipping distro...Done

Sandbox 'tutorial' created with distro 'enonic-xp-mac-sdk-7.14.0'.
Starting the sandbox 
____________________________(_)______   ____  _________
_  _ \_  __ \  __ \_  __ \_  /_  ___/   __  |/_/__  __ \
/  __/  / / / /_/ /  / / /  / / /__     __>  < __  /_/ /
\___//_/ /_/\____//_/ /_//_/  \___/     /_/|_| _  .___/
                                               /_/

# Enonic XP 7.14.1
# Built on 2023-07-26T12:31:19Z (hash = d5bf8d725738b778e153d839f16cdaa9e4641444, branch = d5bf8d725738b778e153d839f16cdaa9e4641444)
# OpenJDK 64-Bit Server VM 17.0.7 (GraalVM Community)
# Linux 5.19.0-50-generic (amd64)
# Install directory is /home/username/.enonic/distributions/enonic-xp-linux-sdk-7.14.1
# Home directory is /home/username/.enonic/sandboxes/tutorial/home

*
* DEV mode is ON. This will slow down the system and should NOT BE used in production.
*
[...]

This gives you some useful information about this sandbox, including its XP version, and the Home directory.

Reserved ports 
[...] - Started xp@523d2774{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
[...] - Started api@22bce39c{HTTP/1.1,[http/1.1]}{0.0.0.0:4848}
[...] - Started status@37f8a3e8{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)

Installing and starting applications 
[...] - Installed application com.enonic.app.contentstudio bundle 101
[...] - Registering application com.enonic.app.contentstudio bundle 101
[...] - Global Application [com.enonic.app.contentstudio] installed successfully

The sandbox will download and install the applications from the essentials template, producing logs like you see above. Applications may also produces logs when it is started.

If you experience problems starting the sandbox, check the Troubleshooting section at the end of this chapter.

Stopping and starting

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.

To start your sandbox, use the following command:

enonic sandbox start tutorial
The sandbox starts in development (aka dev) mode by default. To run the sandbox in production mode simply add --prod to the start command

XP Admin

Let’s have a look at the Sandbox' web interface. Open http://localhost:8080 in your browser (or just click this link).

You should now see the XP boot page:

The XP boot page

The boot page provides an overview of the sandbox, including installed application, as well as the default configuration files.

Thanks to the Essentials template, several useful XP apps, including Content Studio, were automatically downloaded and installed.

Click Log In as Guest to open the XP admin dashboard. What this actually does is log you in as the XP instance’s Super User. After logging in you should see something like this:

The XP admin dashboard

You are now on the Admin Dashboard. The right hand menu (aka XP menu) enables navigation between admin tools. More admin tools may be injected as extensions via applications.

If things don’t look exactly the same, don’t worry. In every new version of XP the background picture gets updated. Also, admin dashboard is automatically localized - based on your browsers preferred language.

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.

    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
The […​] replaces most of the stack trace for legibility reasons.

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:

Summary

Congrats! Now you know what a sandbox is, got more familiar with the CLI, and also visited the admin dashboard page for the first time.

You’re now ready to move forward by creating your own app.

Contents

Contents