Sandboxes
Contents
In this chapter we’ll introduce the fundamental concepts of Enonic XP. You’ll get a brief introduction to the Enonic command line interface (CLI), XP sandboxes, starter kits, and building and deploying 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:
Enonic CLI v.2.3.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
auditlog Manage audit log repository
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
CLOUD COMMANDS:
cloud Manage Enonic cloud
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:
NAME: Enonic CLI sandbox - Manage XP development instances USAGE: Enonic CLI sandbox [global options] command [command options] [arguments...] VERSION: 2.3.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 discussing local instances of Enonic XP. Having a local (and running) instance of XP is essential for an effective development workflow.
Sandboxes allow 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 now download the Enonic XP SDK distribution for your operating system and link it to the sandbox.
? Sandbox name tutorial ? Enonic XP distribution: mac-sdk-7.11.0 (latest,stable) Downloading distro [===============>-----------------------------------------------------------------------------] 16.55%
Once completed, we can use the CLI to start the sandbox:
enonic sandbox start
|
You can also run the sandbox with the 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.
_____
____________________________(_)______ ____ _________
_ _ \_ __ \ __ \_ __ \_ /_ ___/ __ |/_/__ __ \
/ __/ / / / /_/ / / / / / / /__ __> < __ /_/ /
\___//_/ /_/\____//_/ /_//_/ \___/ /_/|_| _ .___/
/_/
# Enonic XP 7.10.3
# Built on 2022-08-31T13:24:37Z (hash = e4ea190187bd27bc1143a29c4ff2c80e564f58c0, branch = e4ea190187bd27bc1143a29c4ff2c80e564f58c0)
# OpenJDK 64-Bit Server VM 11.0.15 (GraalVM Community)
# Mac OS X 12.4 (x86_64)
# Install directory is $HOME/.enonic/distributions/enonic-xp-mac-sdk-7.10.3
# 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 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)
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. 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 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 "Admin Console Login" to move on.
You should now see the following:
| The background picture gets updated with every new version of XP |
From the login screen, click ".. or 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 - if this is the first time you use XP, 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.
| 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:
| XP localizes the admin interface automatically based on your browsers preferred language, so things may be translated to another language based you your settings. |