The project generator for the VLINGO/XOOM quick start components.


starter enables project structure generation and components initialization for VLINGO/XOOM applications. The primary generation output contains:

  • vlingo-xoom initializer class

  • Maven build configuration: pom.xml

  • Default test class

The structure is represented here.

├── src
| ├── main
| | └── java
| | └──[custom-package]
| | └──
| └── test
| └── java
| └──[custom-package]
| └──
└── pom.xml


  • Java 8+

  • Maven 3.x.x

  • Docker Desktop 18.x


Download starter compressed distribution file via curl:

  • zip file: curl -L -O

  • tar file: curl -L -O

Extract the file content, then set an environment variable named VLINGO_XOOM_STARTER_HOME indicating the absolute path for the uncompressed folder. Additionally, on Unix-based operating systems, it is necessary to allow read and execute access on executable script, placed under the root folder, as following:

$ chmod 755 xoom

Ensure it's all set by verifying the vlingo-xoom-starter version:

$ ./xoom -version

Application Generation

In addition to the command-line interface (see below), vlingo-xoom-starter provides a web/graphical user interface for a rapid application generation. Simply open a terminal window, execute xoom gui and your preferred browser will be opened with a wizard-fashioned screen.

Filling in every wizard step. You can readily take advantage of several auto-generated resources:

  • A full maven project structure with all required vlingo-* dependencies

  • Aggregate and Domain Event classes prepared for vlingo-symbio reactive storage types

  • REST resources, CQRS projections, adapters, and data types

  • Storage type providers supporting StateStore and Journal

  • Containerization files facilitating Docker and Kubernetes deployment

Alternatively, you can also generate applications directly from the terminal through xoom gen command. In this case, the project settings have to be informed in a properties file under the vlingo-xoom-starter folder. See a commented properties file sample below:

#Maven artifact version
#Maven project group id
#Maven artifact version
#Base package name
#Absolute path for the project parent folder
#vlingo xoom version
#Docker Image name, required if deployment type is KUBERNETES or DOCKER
#Published Docker Image, required if deployment type is KUBERNETES
#Kubernetes POD name, required if deployment type is KUBERNETES
#Aggregate names (separated by semicolon)
#Domain Events (each events group should be preceded by Aggregate name and separated by semicolon)
#Aggregate Rest Resources
#Storage Type (STATE_STORE or JOURNAL)
#CQRS (true or false)
#Projections Type (NONE, EVENT or OPERATION)
#Domain Model Database, required if CQRS is false (IN_MEMORY, POSTGRES, HSQLDB, MYSQL, YUGA_BYTE)
#Command Model Database, required if CQRS is true or Storage Type is Journal (see database types above)
#Query Model Database, required if CQRS is true or Storage Type is Journal (see database types above)

Executing xoom gen causes the application generation based on the settings above, which are the same available on user interface.

Containerization Commands

vlingo-xoom-starter provides cool shortcuts for interacting with Docker, Kubernetes, and Gloo. The following commands have to be run from the project root folder:




xoom docker status

Shows the container status. Should be executed on the project root folder.


xoom docker package

Builds / update the Docker image from the application current state. Should be executed on the project root folder.

tag: relate a tag to the current image build. If not informed, the default value is latest. Example: xoom docker package --tag 1.0

xoom docker push

Publishes the image into the configured docker repository. Should be executed on the project root folder.

tag: relate the local tag to the remote tag. If not informed, the default value is latest:latest, following the pattern local-tag:remote-tag. Example: xoom docker push --tag 1.0:latest

xoom k8s push

Apply the manifest file(s) placed under deployment/k8s on Kubernetes


xoom gloo init

Install the Gloo Gateway API generating an upstream for each running service on Kubernetes.


xoom gloo suspend

Uninstall the Gloo Gateway API.


xoom gloo route

Create routes, on Gloo Gateway API, for endpoints declared in

In , define the options described below:

gloo.upstream: a Gloo upstream name for the app's service running on K8s. Example: gloo.upstream = default-myxoomapp-8080

gloo.resource.[resource-name]: an endpoint for an application resource identified by resource-name. Example: gloo.resource.balance = v1/balance gloo.gateway.[resource-name]: a gateway route corresponding to a mapped endpoint identified by resource-name. Example: gloo.gateway.balance= balance Note that, for each resource, a pair of gloo.resource / gloo.gateway has to be informed for properly creating a route in the Gloo Gateway API.


Our team really appreciates collaboration, not only because it boosts the evolution of vlingo components but also for the fact: the more standpoints, the more complete and mature vlingo community will be. If you are looking forward to it, take a tour of our development guide.