Infrastructure and tooling requirements
This guide is to assist people responsible for the infrastructure that is used to build and host applications created on the Genesis platform.
Where available, we point to maintained documentation areas.
If you have any questions or concerns, or if you any content in this guide or its links to be incorrect or lacking detail, please raise them with your Genesis Account Technical Contact, who will be happy to discuss and source any details they are not able to answer directly.
Infrastructure for user development
The Genesis platform includes tools and libraries that enable developers to building applications more quickly.
The following gives an overview of where they are hosted and how corporate infrastructure is typically set up to access them.
Intellij Plugin
Genesis maintains a plugin that allows developers to run the full stack of their application locally for early development phases.
Installing via IntelliJ plugin marketplace
Most developers who use Genesis are able to access the full range of IntelliJ plugins via the market place. Guidelines for developers here https://learn.genesis.global/docs/server/tooling/intellij-plugin/#installation
Installing where access to IntelliJ plugin marketplace is blocked
There are steps to set up an internally hosted marketplace, which Genesis can provide guidance on. If you need this approach, speak to your Genesis Account Technical Contact.
This approach introduces a maintenance overhead when new versions of the plugin are released, and is not recommended.
Postgres (for local development)
By default, the Genesis platform provides an H2 database. This enables you to learn and create simple practice applications without any extra configuration.
However, for serious development and for a production environment, you need a database with a successful record in mission-critical systems. Genesis currently recommends that developers use Postgres for local development. It is free, performant and typically easy to set up.
Installing locally
Postgres can be installed locally in the developer environment and used for development instantly where available.
Running via Docker
If Docker is available within your organisation, developers can guideline to set it up.
Node Packages (NPM)
Genesis provides Foundation UI libraries for web developers via the global NPM Registry.
This is accessible to virtually all web developers with no changes required, as it contains many open source libraries used in modern web development.
If you only have access to listed libraries, raise a request to add @genesislcap/foundation-ui to this list.
If your organisation blocks access to this, contact your Genesis Account Technical Contact to discuss how you prefer to pull npm packages into your infrastructure.
Java libraries
The Genesis Server Framework (GSF) libraries required to build on the platform are hosted and accessible via the Genesis Artifactory.
Genesis supplies client-level user credentials for access to these artifacts.
The options for configuring access to this are discussed below.
Configure access to the Genesis JFROG Artifcatory (preferred approach)
In most cases, you have your own artifactory/nexus/similar store for storing libraries. Your developers point to this location to pull in libraries and develop applications.
The ideal approach is to point your own instance to the Genesis Jfrog Artifactory’s local-release-client repo to find Genesis artifacts, syncing them to your own artifactory as and when developers pull them them.
The Genesis client-level user credentials should be configured in this local repo, and should not shared with developers
Developer instructions to configure access to the Genesis JFROG Artifactory
Alternatively, your developers can point their local Gradle (or Maven) set-up to include the Genesis artifactory.
Artifacts will miss any scanning you may have set up in your artifactory if this approach is adopted.
If you adopt this approach, you need to share the Genesis client-level user credentials with your developers.
Infrastructure for hosting Genesis Apps
Beyond development environments, Genesis applications need to be hosted. You need at least Test and Production environments.
The following section gives an overview of where they are hosted and suggests how corporate infrastructure can be set up to access them.
CICD pipeline
In most cases, you can use your standard CICD pipeline tooling to build and deploy.
Database
There are multiple database technologies supported by Genesis.
Postgres is the recommended standard and conformant database layer to use with Genesis applications. Other database technologies are available if you have a different preference.
Scalable services for production
Postgres is the most popular choice for hosting Genesis applications, because cloud providers typically offer auto-scaling services - for example, the AWS Aurora offering (for Postgres).
Where cloud services are available for use, Genesis recommends using these for production. This is the solution that Genesis uses when we are asked to host environments for clients.
Hosts
Hosting in VMs
Our documentation has a page covering the latest host VM setup requirements and recommendations.
Hosting in containers
You can build containers to deploy into orchestration solutions such as Kubernetes. You can find set-up details in our documentation.
Docker images for containers can be built using the plugin.
There are some additional recommendations when running Genesis in containers:
- Use the healthcheck endpoint for system health
- Decide if you wish to run typical Genesis processes/services in a single container or “compacted” processes. See the use of
--compactProcessesand add to your deployment scripts if desired. - Consul is required in HA setups to propagate real-time data updates to all services in all nodes running a given application environment
- Make log4j changes in the application to push all logs to stdout.
- Runtime data will be lost due to the nature of containers.
- Applications should not use container filesystem storage for any files stored by the application. Instead, we recommend that you use a shared mounted drive, or else S3 (or similar).
- If you still use cgroup v1 in your container set-up and your containers believe they have access to all the CPUs and Memory of the container host, then you probably need to set **
-XX:ActiveProcessorCount={n}**jvm flag where{n}should be set to the true CPU count the container has at runtime. This can be applied to theJVM_OPTIONSsystem definition item so that all processes use the flag on start-up.
Clustering for HA (High Availability)
Genesis application servers can easily be clustered to achieve HA. The clustering section of Genesis documentation gives an overview of how this can be achieved
Genesis Cluster
Clustering two or more nodes, typically across availability zones, for resiliency is simple. Hosts just need to be able to contact each other via the relevant ports, and to be known to each other by listing them in the system definition. See our page on clustering for full set-up details.
Consul
Consul can also be set up and used in a Genesis application environment for high availability (HA). This provides automatic failover of processes that are set to primaryOnly when the primary node becomes unresponsive. This is triggered by monitoring the health status of the process.
Where processes are set to primaryOnly on multiple nodes:
- On start-up, Consul selects one of the processes and starts that process so that it becomes HEALTHY. The same processes on the other nodes are set to STANDBY.
- If the process stops being HEALTHY, Consul selects one of the processes and starts that process so that it becomes HEALTHY. The unhealthy process is terminated. If there are any other processes of the same name on other nodes, one of these is selected and becomes STANDBY.
Our documentation provides details of how to set up Consul.
nginx
Genesis installations usually use nginx as a lightweight web server for:
- serving up SSP (static single page) web client content
- proxying web client (and web API) requests to the Genesis server
- essentially, any client requests with
/gwfwill be routed to the Genesis services with/gwfstripped off.
- essentially, any client requests with
See our config management page for details on configuring nginx.
Other web servers can also be used. If you need to use a different one, this is fine; it simply needs to be set up to perform the same actions that nginx is used for.
Firewall
The standard ports opened between Genesis hosts in a given environment cluster are listed in the table below.
| Port | Used for |
|---|---|
| 80 | Web traffic |
| 443 | Secured web traffic |
| 5000 | Zero MQ outbound traffic |
| 5001 | Zero MQ inbound traffic |
Application development teams can configure these to use different port numbers. Make them aware of these settings so that you avoid clashes with internal policies or set-ups.
Optional supporting infrastructure
The infrastructure described here is optional, and can be used to meet specific requirements, such as HA setups.
Update queue
The Genesis platform abstracts the database layer so that developers don’t have to worry about implementation details. Regardless of the underlying DB, all database actions taken are published to an update queue. Other Genesis processes listen out for this and act upon relevant updates.
Internally on a given host, and in fixed-size environment deployments, ZeroMQ is used for the update queue. Netty + Apache Pekko are used to manage the cluster nodes and distribute database updates between the nodes. These libraries run on the cluster nodes, and no additional infrastructure is required
Instead of ZeroMQ, an MQTT broker queue can be used as an alternative update queue. Usually, this is hosted separately from the application hosts or containers, and the queue is shared between hosts or containers.
Load Balancer
The Genesis platform does not include a Load Balancer. We encourage you to use your enterprise’s preferred LB. Usually, this is set up to point to the nginx server running on each Genesis host. Genesis application environment servers provide a healthcheck endpoint, which the Load Balancer can use to determine server health.
Genesis supports round-robin and sticky-session set-ups.
File storage
For HA setups, your development teams might need you to provide file storage in the form of:
- a managed cloud file storage service, such as AWS S3
- a shared mounted disk between servers
Log storage
As standard, Genesis uses log4j logging, and it logs to the local host's disk. You might prefer to set up a log shipper and push Genesis application logs to it. Genesis works well with all the major log shipping utilities.