nuccess/nuclos-server repository overview

⁠Nuclos

This repository contains Nuclos⁠ and is build by an automated pipeline and published to the public Docker Hub Registry⁠.

⁠Base Docker Image

• eclipse-temurin:17-noble⁠

⁠Docker Tags

Visit Tags⁠

⁠Source Code

Visit BitBucket⁠

⁠Installation

1. Install Docker⁠.

2. Download automated build from public Docker Hub Registry⁠: docker pull nuccess/nuclos-server:latest

   (alternatively, you can build an image from Dockerfile: docker build --build-arg NUCLOS_BRANCH=master --tag my-nuclos https://bitbucket.org/nuccess/docker-nuclos.git)

⁠Usage

The Nuclos containers can either be operated with a separately started PostgreSQL database (Nuclos-DB⁠) or you can use the embedded database variant of the base image (tag names end with "-with-db"). In the second case, the version of the database is specified by the base image and the default port is 5432 with a default PostgreSQL account nuclos and password password.

You can affect the behavior of the container with a variety of environment variables and volumes. The most important are described below. A running Nuclos DB container named nuclos-db is required for the most examples given here. Local directory examples /Users/Maik/Nuclos/Docker/... must be replaced.

⁠Development Environment

⁠for the latest Nuclos version

This is a good start for a default development environment with the embedded PostgreSQL database.

docker run --rm -d --name nuclos-dev -p 8060:8080 -p 5432:5432 -e DOCKER_NUCLOS_PORT=8060 \
-e DEVELOPMENT=true -e TZ=Europe/Berlin -e LOCALE=de_DE.UTF-8 \
nuccess/nuclos-server:latest-with-db

If more flexibility is required and the database is to be run separately, there is an alternative:

docker run --rm -d --name nuclos-dev -p 8060:8080 -e DOCKER_NUCLOS_PORT=8060 \
-e DB_SCHEMA=dev -e DEVELOPMENT=true -e TZ=Europe/Berlin -e LOCALE=de_DE.UTF-8 \
--volumes-from nuclos-db --link nuclos-db:POSTGRES \
nuccess/nuclos-server

Here you will find advanced options for easy access to logs /opt/nuclos/home/logs, generated Java source files /opt/nuclos/home/data/codegenerator and a Java debug port 8000:

docker run --rm -d --name nuclos-dev -p 8060:8080 -p 18060:8000 -e DOCKER_NUCLOS_PORT=8060 \
-e DB_SCHEMA=dev \
-v /Users/Maik/Nuclos/Docker/vol-nuclos-codegen:/opt/nuclos/home/data/codegenerator \
-v /Users/Maik/Nuclos/Docker/vol-nuclos-devlogs:/opt/nuclos/home/logs \
-e DEVELOPMENT=true -e TZ=Europe/Berlin -e LOCALE=de_DE.UTF-8 \
--volumes-from nuclos-db --link nuclos-db:POSTGRES \
nuccess/nuclos-server

⁠Production Environment

⁠for Nuclos latest

For a productive environment it is recommended to place the document attachments outside the container. An update of the Nuclos version therefore only consists of replacing the Nuclos container without having to migrate the document attachments in a manual step. For a secure SSL connection the keystore must be set using volume /opt/nuclos/keystore and password file /opt/nuclos/secrets/keystore_password.

docker run -d --name nuclos-prod -p 8040:8080 -e DOCKER_NUCLOS_PORT=8040 \
-e DB_SCHEMA=production \
-v /Users/Maik/Nuclos/Docker/vol-nuclos-secrets:/opt/nuclos/secrets:ro \
-v /Users/Maik/Nuclos/Docker/vol-nuclos-keystore:/opt/nuclos/keystore:ro \
-v /Users/Maik/Nuclos/Docker/vol-nuclos-backups:/opt/nuclos/backups \
-v /Users/Maik/Nuclos/Docker/vol-nuclos-documents:/opt/nuclos/home/data/documents \
-e TOTAL_RAM_GB=4 -e TZ=Europe/Berlin -e LOCALE=de_DE.UTF-8 \
--volumes-from nuclos-db --link nuclos-db:POSTGRES \
nuccess/nuclos-server:latest

⚠️ Do not run productive, test and development environments in the same Nuclos-DB instance. The restore process of a DockerBackup first deletes the contained schema if it exists. So, if you want to import a DockerBackup of production into a test environment, and these two run in the same Nuclos-DB instance, the production will be deleted!

⁠Test Environment

⁠for Nuclos latest

Here is the example of a test environment based on a restore of a productive environment. The special feature is the volume /opt/nuclos/restorescripts

docker run --rm -d --name nuclos-test -p 8050:8080 -e DOCKER_NUCLOS_PORT=8050 \
-e DB_SCHEMA=test \
-v /Users/Maik/Nuclos/Docker/vol-nuclos-backups:/opt/nuclos/backups \
-v /Users/Maik/Nuclos/Docker/vol-nuclos-restore:/opt/nuclos/restorescripts:ro \
-e DEVELOPMENT=true -e TZ=Europe/Berlin -e LOCALE=de_DE.UTF-8 \
--volumes-from nuclos-db --link nuclos-db:POSTGRES \
nuccess/nuclos-server:latest

The Nuclos DockerRestore job restores a DockerBackup taken from production. After a restore the *.sql scripts in /opt/nuclos/restorescripts are executed automatically. Please also read the warning in the production environment section. Useful examples after a restoration could be:

• Change Nuclos system paramter value of NUCLOS_INSTANCE_NAME

UPDATE T_AD_PARAMETER SET STRVALUE='TEST Instance', STRCHANGED='restorescript',  
DATCHANGED=clock_timestamp() WHERE STRPARAMETER='NUCLOS_INSTANCE_NAME';

• Change a Nuclet parameter to disable productive features, such as sending mails to customers

UPDATE T_MD_NUCLETPARAMETER SET STRVALUE='n', STRCHANGED='restorescript', DATCHANGED=clock_timestamp()  
WHERE STRPARAMETER='Produktivsystem';

• Stop all Nuclos jobs

DELETE FROM T_AD_QRTZ_FIRED_TRIGGERS;  
DELETE FROM T_AD_QRTZ_SIMPLE_TRIGGERS;  
DELETE FROM T_AD_QRTZ_CRON_TRIGGERS;  
DELETE FROM T_AD_QRTZ_TRIGGERS;  
UPDATE T_MD_JOBCONTROLLER SET STRJOBLASTSTATE='Deaktiviert', BLNRUNNING=false,  
STRCHANGED='restorescript', DATCHANGED=clock_timestamp();

• Remove user passwords

UPDATE T_MD_USER SET STRPASSWORD=null, STRCHANGED='restorescript', DATCHANGED=clock_timestamp();

• Disable LDAP

UPDATE T_AD_LDAPSERVER SET BLNACTIVE=false;

⁠Nuclos Clients

• ⁠Nuclos Webclient

The Webclient runs on the specified port: -p 8060:8080 -e DOCKER_NUCLOS_PORT=8060
http://localhost:8060⁠

• ⁠Nuclos Desktop Client (via Nuclos Launcher Download...⁠)

On the start page you will find a link to start via the Nuclos Launcher.
Alternatively, you can add it manually. The server address for our example is: nuclos://localhost:8060/nuclos

• ⁠Nuclos Landing Page

To visit the Nuclos default start page in your browser simply add /nuclos to the webclient URL
http://localhost:8060/nuclos⁠

• ⁠Default User

The default user is nuclos with an empty password.

⁠Data Volumes

• ⁠/opt/nuclos/secrets

Directory of all secrets if you want to use something other than the default.

⁠db_password

Contains the password to be set for the POSTGRES_USER

⁠keystore_password

Contains the password for the specified keystore /opt/nuclos/keystore.

• ⁠/opt/nuclos/backups

Directory for all backups made by the DockerBackup Job. For more information visit the Nuclos wiki⁠

• ⁠/opt/nuclos/home/data/codegenerator

Contains generated Java source files. When development is enabled -e DEVELOPMENT=true, changes to rule sources (Directory src-rule) are automatically detected and compiled by Nuclos. Since it does not work everywhere, depending on the docker environment, a manual import can be initiated via the Desktop Client (Configuration/Rules/Rules (server) -> Toolbar Import file changes)

• ⁠/opt/nuclos/home/data/codegenerator-dependencies

Contains Codegenerator dependencies. When development is enabled -e DEVELOPMENT=true, the dependencies are synchronized in this directory at startup. Then configure the Nuclos system parameters CODEGENERATOR_POM_(\*_)LIBDIR so that the paths of the automatically generated pom.xml match your local system and your IDE is able to find all dependencies. For example CODEGENERATOR_POM_LIBDIR=${pom.basedir}/../codegen-deps/lib/ (Should actually always fit if the two directories are in the same main directory).

• ⁠/opt/nuclos/home/data/documents

Storage of Nuclos managed document attachments.

• ⁠/opt/nuclos/home/data/index

Storage of Nuclos live search index files.

• ⁠/opt/nuclos/home/data/nucletimport

Nuclet dir for auto imports during startup.

• ⁠/opt/nuclos/home/logs

Nuclos server log files.

• ⁠/opt/nuclos/extensions

Nuclos server and client extensions. Same use as with a Nuclos installer.

• ⁠/opt/nuclos/assets

Add or overwrite Nuclos webclient assets such as the favicon. Simply place a file called favicon.png in this volume, and the container will do the rest.

• ⁠/opt/nuclos/keystore

Keystore file for a secure SSL connection between client and server. For more information see Production Environment.

• ⁠/opt/nuclos/restorescripts

After a restore these scripts are executed automatically. For more information see Test Environment.

• ⁠/opt/nuclos/control

Socket-free control plane of the container. By dropping installer JARs and small marker files into this volume, a development container or a parent/cloud orchestrator can trigger install, restart, kill, shutdown and startup operations on this instance — without docker exec, without the host docker socket and without SSH.
⚠️ Everyone with write access to this directory can control the Nuclos instance. Mount it read-write only where that is intended. For more information see Control Directory Contract.

⁠Control Directory Contract

The volume /opt/nuclos/control is a socket-free control channel for a running container. A watcher inside the container (nuclos-run.sh) polls the directory about every 5 seconds and acts on the marker files it finds. This makes the directory the unification point between a development container that drops freshly built installer JARs into it and an orchestrator that deliberately has no access to the host docker socket.

docker run --rm -d --name nuclos-dev -p 8060:8080 -e DOCKER_NUCLOS_PORT=8060 \
-e DEVELOPMENT=true -e TZ=Europe/Berlin -e LOCALE=de_DE.UTF-8 \
-v /Users/Maik/Nuclos/Docker/vol-nuclos-control:/opt/nuclos/control \
nuccess/nuclos-server:latest-with-db

Without a bind mount the container still gets an anonymous volume: the watcher works as usual, it is just not reachable from outside.

⁠Layout

/opt/nuclos/control/
├── installers/   ← installer JARs are dropped here (written by the client)
├── ops/          ← operation markers (written by the client)
└── status/       ← current state of the instance (written by the container)

All three subdirectories are created by the image and re-created on every container start, so they are present from the first watcher tick on.

⁠Operations

Writing the marker file is the canonical interface. The in-container CLI nuclos-from-dev.sh is a thin wrapper that writes exactly the same markers (nuclos-from-dev.sh --help).

To install a JAR, first copy it into installers/, then write its plain basename (no path) into ops/install.

Each tick processes at most one marker in the fixed priority order install > kill > restart > shutdown > startup, and the marker is deleted after it has been handled — a non-empty ops/ directory therefore means that work is pending. On container start any leftover markers of a previous lifetime are cleared, so a crash cannot replay a stale operation.

⁠Status files

Markers and status files are single tiny files, so no locking is required. Installer JARs however should be written under a temporary name and then moved into place (for example installers/.foo.jar.tmp → installers/foo.jar), so that the watcher can never pick up a half-written JAR.

On container start a README.md with the complete contract is seeded into the control directory, but only if no README.md exists there yet — so in-place edits and host-side documentation survive a restart. The same content is kept in control-README.md⁠.

⁠Environment Variables

• ⁠DOCKER_NUCLOS_PORT

Please use the same port as in the mapping -p 8060:8080. Default is 8080 -e DOCKER_NUCLOS_PORT=8060

• ⁠TOTAL_RAM_GB

Set total usable RAM for the Container. If the container is started with a limit (--memory), this has priority. Default is 2.0 GB. -e TOTAL_RAM_GB=2.0

• ⁠NUCLOS_MAX_RAM_PERCENTAGE

The actual memory usage of a Java process under load exceeds the value for a maximum heap (Xmx). This parameter dynamically controls the heap depending on the available TOTAL_RAM, similar to the Java parameter XX:MaxRAMPercentage. Default is 75%. -e NUCLOS_MAX_RAM_PERCENTAGE=75

• ⁠DEVELOPMENT

Enable development features such as external code changes (volume codegenerator), an open Java debug port at 8000, Webclient rest explorer and some more. -e DEVELOPMENT=true
For more information see Development Environment.

• ⁠KEEP_ALIVE_CHECK_TIMEOUT

Sets the timeout (in seconds) of the keep-alive check. If no response is received within this time or if the port is not in use (crash of the Java process), a shutdown/restart takes place automatically. Default is 300s. -e KEEP_ALIVE_CHECK_TIMEOUT=300

• ⁠LOCALE

Set the locale. Default is de_DE.UTF-8. -e LOCALE=de_DE.UTF-8

• ⁠TZ

Set the timezone. Default is Europe/Berlin. -e TZ=Europe/Berlin

• ⁠DB_SCHEMA

Specify the name of the schema to use in the Nuclos-DB. The schema may be used only by one Nuclos application server at the same time. Default is "nuclos". -e DB_SCHEMA=dev

• ⁠DB_CONNECTIONPOOL_SIZE

Set the database connection pool size. Default is 50. -e DB_CONNECTIONPOOL_SIZE=50

• ⁠DB_CONNECTIONPOOL_WAITSECONDS

Set the database connection pool wait time in seconds. Default is 120. -e DB_CONNECTIONPOOL_WAITSECONDS=120

• ⁠NUCLOS_CONNECTION_THREADPOOL_SIZE

Set the application server connection pool size for answering client requests. Default is 200. -e NUCLOS_CONNECTION_THREADPOOL_SIZE=200

• ⁠LIVE_SEARCH

Set Nuclos live search enabled. Default is false. -e LIVE_SEARCH=true

• ⁠CLUSTER_MODE

Starts this instance in cluster mode. Default is false -e CLUSTER_MODE=true For more information visit the Nuclos wiki⁠

• ⁠CLUSTER_NODE_TYPE

Possible values are 'master' or 'slave'. There can only be one master, but many slaves. -e CLUSTER_NODE_TYPE=master

• ⁠CLUSTER_NODE_ID

Assign a unique ID for this node. (Alphanumeric, max. 20 characters [a-zA-Z0-9]). -e CLUSTER_NODE_ID=C3PO

• ⁠CLUSTER_NODE_HOSTNAME

Other nodes can use this name to reach this instance. -e CLUSTER_NODE_HOSTNAME=c3po.local

• ⁠CLUSTER_BALANCER_PROTOCOL

Optional - Possible values are 'http' or 'https'. -e CLUSTER_BALANCER_PROTOCOL=https

• ⁠CLUSTER_BALANCER_HOSTNAME

Optional - Public hostname under which the cluster can be reached. -e CLUSTER_BALANCER_HOSTNAME=my.nuclos.cluster

• ⁠CLUSTER_BALANCER_PORT

Optional - The public port of the cluster. -e CLUSTER_BALANCER_PORT=443

• ⁠CLUSTER_BALANCER_CONTEXT

Optional - Only need to be specified if the load balancer is mapping the URL (example: 'nuclos' (the default) should be mapped to 'r2d2'). -e CLUSTER_BALANCER_CONTEXT=r2d2 Complete example ot CLUSTER_BALANCER_* variables in action: Nuclos node instance (this): http://c3po.local:8060/nuclos⁠ Public cluster (Load balancer): https://my.nuclos.cluster:443/r2d2⁠

• ⁠POSTGRES_USER

In the case of an embedded database, the default PostgreSQL user is nuclos with password password. See also Nuclos-DB⁠. You can change the default password with the file db_password in the volume /opt/nuclos/secrets.

• ⁠DB_MAX_RAM_PERCENTAGE

In the case of an embedded database, dynamically controls the total usable RAM for the PostgreSQL process and reduces the value of NUCLOS_MAX_RAM_PERCENTAGE. See also Nuclos-DB⁠. Default is 10%.

• ⁠DB_MAX_CONNECTIONS

In the case of an embedded database, set the connection limit. See also Nuclos-DB⁠. Default is 50.