Sandbox Welcome
Contents
In this chapter we’ll introduce a fundamental concept to start developing with Enonic XP: sandboxes
By the end of the this, 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 instance of Enonic XP running in a specific version.
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 createWhen prompted, give your sandbox the name: tutorial.
Next, when asked which XP distribution you want, use the latest one.
By the end this flow, your terminal should have something that looks like this:
bre@bre-enonic:~$ enonic sandbox create
? Sandbox name: tutorial
Loading...Done
? Do you want to use Enonic XP 7.13.1 (latest, stable)? Yes
Downloading distro [=======================================================] 100.00%
Unzipping distro...Done
Sandbox 'tutorial' created with distro 'enonic-xp-linux-sdk-7.13.1'.
bre@bre-enonic:~$| If you press enter without entering a response, the CLI will use the default response. The default response to a question is listed in brackets after the question. |
Starting the sandbox
Once the sandbox creation is completed, we can use the CLI to start the sandbox, i.e, run a local instance of latest XP:
enonic sandbox start --devWe ran the sandbox with the optional --dev flag, since this makes the sandbox automatically pick up certain changes to locally deployed applications, including most of the work we’ll be doing in the coming chapters. Read more about dev mode in the reference docs. |
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:
____________________________(_)______ ____ _________
_ _ \_ __ \ __ \_ __ \_ /_ ___/ __ |/_/__ __ \
/ __/ / / / /_/ / / / / / / /__ __> < __ /_/ /
\___//_/ /_/\____//_/ /_//_/ \___/ /_/|_| _ .___/
/_/
# Enonic XP 7.13.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/bre/.enonic/distributions/enonic-xp-linux-sdk-7.13.1
# Home directory is /home/bre/.enonic/sandboxes/tutorial/home
*
* DEV mode is ON. This will slow down the system and should NOT BE used in production.
*
[...]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 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 msThis 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:
-
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! -
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:
Admin dashboard
With your sandbox running, lets have a look at XP’s web interface. Point your browser to http://localhost:8080.
You should see the XP boot page:
The boot page gives an overview of endpoints (as mentioned above) and any other services that may be running on this instance.
Click on "Login as Guest" to move on. You should now see the following:
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.
You should now be on the admin dashboard. The right menu, aka "XP admin menu", is responsible to allow navigation through some installed apps on your XP instance. By now you should only have two apps installed:
-
app-users, to manage permissions for users, user groups and roles on your local XP instance (sandbox)
-
app-applications, to install, uninstall and update installed applications on your sandbox
| If things don’t look exactly the same, don’t worry… on every new version of XP the background picture gets updated. Also, admin dashboard automatically translates text based on your browsers preferred language. |
Summary
Congrats! Now you understand 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 with an app development.