This document provides an introduction to working with WebSight projects. It explains how to configure, build and run a new project using Maven Archetype and Docker. It also describes the contents of the project build and runtime files.
Although the specific contents of your project may vary depending on your needs, the sample project described on this page is a useful starting-point for running Web applications using WebSight CMS.
To create and run a project, you will need Java 17 or later, Maven 3.8.5 or later and Docker Desktop.
You can check your Java version in most environments with:
java -version openjdk 17.0.2 2022-01-18 OpenJDK Runtime Environment Temurin-17.0.2+8 (build 17.0.2+8) OpenJDK 64-Bit Server VM Temurin-17.0.2+8 (build 17.0.2+8, mixed mode)
Check your Maven version with:
Check your Docker installation by running:
Generate a project
To create a new project, first open a command prompt and cd to the directory where you want to store your project.
Next, use a Maven command to create your project, being sure to declare the desired parameters properly.
- Use the groupId, artifactId, and version parameters to declare Maven artifacts for your project.
- Use projectName, projectId and package parameters to define technical requirements (such as application resources paths and Docker image names) and the root package for Java code.
- Use the archetypeVersion parameter to set the archetype version you want to use. You can check the latest version here.
- Use the cmsVersion parameter to specify the WebSight CMS version that the project should use. Check the WebSight Release Notes to find the latest available version.
mvn archetype:generate \ -DarchetypeGroupId=pl.ds.websight \ -DarchetypeArtifactId=websight-cms-ce-project-archetype \ -DarchetypeVersion=1.6 \ -DgroupId=my.groupId \ -DartifactId=my-artifactId \ -Dversion=1.0.0-SNAPSHOT \ -DprojectName="Example Project" \ -DprojectId=example-project \ -Dpackage=com.example.project \ -DcmsVersion=1.15.0
The above command creates a project with the following structure:
. └── my-artifactId ├── README.md ├── application ├── content ├── distribution ├── environment ├── pom.xml └── tests
The contents of the project structure we generated above are an example of what you'd typically include when creating a project for a Web application using WebSight CMS.
Note in particular the following modules:
application- components code and scripts delivered as OSGi bundles
backend- CMS elements (pages, templates, components, etc.), Java models and services
frontend- frontend project bundled by webpack
content- initial content as a JCR vault module (content_package)
distribution- project distribution - Sling feature model and Docker images
environment- scripts and files used to build environments
local- local environment managed by Docker Compose
tests- tests used to validate the distribution
content- content for end-to-end tests
end-to-end- end-to-end tests
Distribution and environment
It is important to note that the project contains built-in server definitions and configurations. The
distribution module is responsible for bundling the application based on the configurations and WebSight CMS modules using
Sling Feature Model. It also prepares the required Docker images to run the complete stack. The finalized project build artifacts are immutable Docker images that can be run on local, test, and production environments. Environment-specific configurations can be implemented by injecting system variables.
It is possible to deploy application modules to running containers without rebuilding the Docker images, but the changes will be lost after each container restart and can be used only for local development.
distribution delivers two Docker images:
- CMS - Image that bundles WebSight CMS with your application
- Nginx - An HTTP server with your project's configuration
A third container runs MongoDB as a default data store for Jackrabbit OAK (the persistence layer used by WebSight CMS). The data store stores content such as pages or assets managed by the CMS.
We use Docker Compose to orchestrate containers during local setup. See the environment/local module for details.
This illustration shows the runtime environment and roles:
Build the instance
To build the project, use the Maven command:
Add e2e profile to execute end-to-end tests:
You should see successful end-to-end test execution in the log:
Execution should end with a successful build message:
On some Mac systems, Docker builds may fail with the following error message
[ERROR] Failed to execute goal io.fabric8:docker-maven-plugin:0.40.1:build (build-docker-image) on project ws-linux-box-distribution: Execution build-docker-image of goal io.fabric8:docker-maven-plugin:0.40.1:build failed: No <dockerHost> given, no DOCKER_HOST environment variable, no read/writable '/var/run/docker.sock' or '//./pipe/docker_engine' and no external provider like Docker machine configured -> [Help 1]
If this occurs, check the Docker Maven Plugin issue tracker issue for details and available workarounds.
Run the instance
Once your project build is complete, you can start a local instance by navigating to the
environment/local folder and running:
The resulting instance runs WebSight CMS and your application at http://localhost:8080/ The default login is wsadmin/wsadmin. Published content is available locally at http://localhost/
See README.md in the
environment/local folders for additional details about the runtime environment.
After login, you will be redirected to the Spaces list. In WebSight CMS content is organized in Spaces. The Spaces list shows you the generated application and its associated content using the
After clicking on the Space name, the Pages dashboard opens with one page delivered in the initial content. You can manage your pages here and navigate to the Assets dashboard (to manage Assets) or open the Page editor to edit page content from within the CMS:
In the Right top corner, you will find an Admin tools menu with links to administration tools. Or, the Admin dashboard can be accessed directly using the following link:
Now that you know how to set up a new project using WebSight CMS, consider learning more about the following topics: