Task

The task is one of the most fundamental components of CloudNet. Tasks form the fundamental building block for your network.

The idea of CloudNet is that every Service is based on a task. A task is comparable to a blueprint for services. In a task, the basic settings for a service are defined.

Name

The name of a task is a unique characteristic of a task across all of CloudNet. Based on the name of the task and the set nameSplitter, the name of the created Service is formed.

If you name your task BedWars and choose -Game- as the name separator, a service of this task would be called BedWars-Game-1. As shown, CloudNet combines the task name with the name separator and appends a number to the end. This number is incremented with each started service. So the next services would be named as follows:

BedWars-Game-2
BedWars-Game-3
...
BedWars-Game-11

To learn more about the name separator and the set limits, read here.

Runtime

The Runtime setting offers the possibility to choose from different runtimes. Based on the selection, the services of this task are started with a different runtime.

By default, jvm is entered here. This runtime is the best choice for most users. In the jvm runtime, all services of the task are started and managed as direct subprocesses of CloudNet.

To meet further requirements, there is (so far) only one other runtime. This is the docker-jvm runtime in which a separate Docker container is started for each service, in which it runs. Even though these services run isolated in containers, CloudNet still manages them as usual and there are no differences in the operation of the various services for the user.

hinweis

In order for the docker-jvm runtime to be used, the (DOCKER MODULE HERE) must be installed and configured.

If none of these runtimes meet the requirements, additional runtimes can be added through modules and selected here. For this, visit the documentation of the CloudServiceFactory.

HostAddress

The HostAddress setting offers the possibility that the services of a task are assigned a different IP address than set in the Node Config. The host address setting allows proxy services to run on a publicly accessible address, while services like the lobby are not accessible from outside. This ensures that no one can bypass the proxy and, for example, enter the network with offline accounts.

If you now use CloudNet in a cluster configuration (SEE HERE), you would encounter the problem that the host addresses on the different Nodes are not the same. The tasks are synchronized within the cluster (see cluster sync). So that the host addresses option can also be used in the cluster, there are so-called IP aliases. These can be configured in the node and serve as placeholders. More about IP aliases can be found here

The resolution of the host address setting happens as follows:

JavaCommand

The JavaCommand setting offers the possibility to change the used Java installation per task. By default, all services are started with the jvmCommand of the node. If a Java command is set in the task of the service, this is used. It is important to mention that in the javaCommand option the complete path to the executable Java installation must be specified and nothing more.

On different operating systems, the Java command setting could look as follows:

• Windows: C:\Users\username\.jdks\temurin-21.0.1\bin\java.exe
• Linux: /usr/lib/jvm/java-17-openjdk-amd64/bin/java

warnung

No Java options like -DPaper.IgnoreJavaVersion=true can be set here. For this, jvmOptions can be used, see here jvmOptions.

warnung

CloudNet requires Java 23 and newer. Even though you can set the Java command per task, the chosen installation still needs to be Java 23 or newer.

NameSplitter

The NameSplitter setting offers the possibility to change how the name of a service ultimately looks. By default, - is set as the name separator for tasks.

info

To avoid problems on the file system, name separators cannot contain all characters. Especially characters like / are not allowed. The following RegEx can be used to check whether a name separator is allowed or not ^[a-zA-Z\d._\-*]+$.

To find more information about using the name separator, read here.

DisableIpRewrite

The DisableIpRewrite setting offers the possibility to disable the automatic setting of IP and port in the configuration files of the various server software. Normally, CloudNet reads the configuration from the installed software (e.g. config.yml for BungeeCord) and writes the IP address and port there, which were assigned by CloudNet. If you set this setting to true, CloudNet no longer changes the configurations.

This option was mainly developed for certain Minecraft Bedrock constructions, as there are no SRV records in this edition of Minecraft and thus the ports for the proxy servers must be fixed. It is recommended to contact CloudNet support for such constructions.

warnung

This option should only be used with caution, because if CloudNet no longer overwrites the IP addresses and ports of the servers, unexpected problems can occur. For example, ports can be assigned twice, which means the services can no longer start.

Maintenance

The Maintenance option offers the possibility to put a task into maintenance. By activating maintenance for a task, the following events are prevented:

• Automatic service starts. Services that should be created based on the minServiceCount are no longer created & started during active maintenance.
• If the (HERE BRIDGE LINK MODULE) is installed, you additionally need the permission cloudnet.bridge.maintenance to enter the services of a task for which maintenance is activated.

info

The maintenance setting of a task is not to be confused with the maintenance setting of the (HERE SYNCPROXY). The setting in the task has no influence on the shown MOTD and also not on the whitelist setting of the SyncProxy module.

AutoDeleteOnStop

The AutoDeleteOnStop setting changes the stop behavior of services. CloudNet services have different lifecycles, this setting ensures that services switch directly to the DELETED lifecycle after the STOPPED lifecycle. This effectively means that the service is completely recreated once. The settings, such as the maxMemoryHeapSize are only applied after the delete.

More about the lifecycles of services can be found here.

gefahr

Disabling this option is not recommended. The attempt to persist the files of services by disabling this function will fail. Instead of disabling this option, the staticServices option in the task should be activated.

StaticServices

The Static Services setting allows the files of a service to be persisted. Normally, services start within the temp/services folder. The Templates of the task are copied into this temporary directory. The files of these services in the temporary folder are removed as soon as the services are stopped, at the latest when the entire cloud is shut down. If you now activate the staticServices setting, the files of the service are stored in local/services. The names of the folder follow the displayed name of the service, e.g. a task with the Name Lobby and the Name Separator - would run in local/services/Lobby-1. This path does not change even after the first creation. It is also important that in static services by default the Templates are only copied on the first creation, then no more.

info

Under no circumstances does CloudNet delete static services. Even the DELETED lifecycle has no influence on the files of static services. Simply put, there is no way for CloudNet to delete them. Deletion can only be done by actively deleting the folder on the file system.

Groups

The Groups setting offers the possibility to specify which Groups a task belongs to. Through these groups, tasks can be given additional settings. Furthermore, through groups, different tasks can be united into a group, allowing configurations and templates to be shared.

When creating a task with the Tasks Setup (COMMAND LINK), a group with the same name is created for this task. Therefore, the entry for most tasks looks as follows:

"groups": [
  "Task-Name"
],

Creating groups is especially useful for certain game modes and their variations. If you have, for example, two tasks for BedWars: BedWars-8x1 and BedWars-8x2, these could be combined with a group BedWars to share Templates, for example.

In this case, the setting would look as follows:

For the BedWars-8x1 task:

"groups": [
  "BedWars-8x1",
  "BedWars"
],

For the BedWars-8x2 task:

"groups": [
  "BedWars-8x2",
  "BedWars"
],

For more information about groups, see here

AssociatedNodes

The Associated Nodes setting offers the possibility to specify on which Node services of a task are allowed to start. Normally, every service is allowed to start on every node and therefore ends up on the node with the most free resources (see node selection link here). For services to be allowed to start on every node, the array in the task must be empty ("associatedNodes": [],).

To prevent services of a task from being allowed to start on all nodes within the cluster (link), individual nodes can be added. This could look like "associatedNodes": ["Node-1"],, now the services of the task would only be allowed to start on the node named Node-1. Of course, multiple nodes can also be allowed by simply adding more. For example, "associatedNodes": ["Node-1", "Node-2"], would allow starting on Node-1 and Node-2.

hinweis

This option is especially recommended for tasks with Static Services, as the files of these services are fixed on one node. If the service starts on another node, it only contains the files of the Template, practically another first creation takes place.

DeletedFilesAfterStop

The DeletedFilesAfterStop setting offers the possibility to determine which files should be deleted after stopping a service. Within the array, multiple paths to files or folders can be specified, which are then deleted. If you want to delete a plugin, for example, you can configure it as follows "deletedFilesAfterStop": ["plugins/ProtocolLib.jar"],. The paths for this option can be both absolute and relative.

This option can also be set for tasks that have Static Services disabled, then the only effect is that the deleted files can no longer be copied by configured Deployments in the task.

For tasks with Static Services enabled, the files are removed from the local/services folder of the service.

warnung

This option only allows deleting files within the service. Attempts to delete files outside the service will lead to an error and the files will not be removed.

Environment

The Environment setting offers the possibility to specify what kind of software the services of this task use. Based on this environment, the configuration files of the respective software are adapted.

Currently, there are the following environments:

• MINECRAFT_SERVER Minecraft servers based on the Vanilla Minecraft server. Including Spigot, Paper & Purpur.
• MODDED_MINECRAFT_SERVER Minecraft servers based on the Vanilla Minecraft server, but supporting mods instead of plugins. Including Sponge & Fabric.
• NUKKIT Nukkit Minecraft servers for the Bedrock version of Minecraft.
• BUNGEECORD BungeeCord proxies. Including BungeeCord & Waterfall
• VELOCITY Velocity proxies.
• WATERDOG_PE WaterDog proxies for the Bedrock version of Minecraft.

MaxHeapMemorySize

The MaxHeapMemorySize setting offers the possibility to specify how much memory (in MB) each individual service of a task is assigned. Setting the memory with this option results in the JVM options Xmx and Xms being set to the respective value. Therefore, these two options cannot be used in the JvmOptions.

Furthermore, this option is used to calculate how many resources a Node has consumed. More about resource calculations can be found here.

JvmOptions

The JvmOptions setting offers the possibility to change which options the Java Virtual Machine is started with. Options such as -DPaper.IgnoreJavaVersion=true can be set.

warnung

CloudNet already sets the -Xmx and -Xms options based on the MaxHeapMemorySize, therefore these cannot be additionally set here.

The options set here are the options that come in a start command between the -jar parameter and the executable file. The options would therefore be inserted at the following position java -jar -DPaper.IgnoreJavaVersion=true paper.jar.

info

In the JVM options, all options must be passed individually, which means that each entry may contain at most one option and additional ones must be added to new entries. So the options should look as follows:

"jvmOptions": ["-DPaper.IgnoreJavaVersion=true", "-DReallyGoodJVMOption"],

instead of

"jvmOptions": ["-DPaper.IgnoreJavaVersion=true -DReallyGoodJVMOption"],

ProcessParameters

The ProcessParameters setting offers the possibility to set additional parameters for the services of the task. Here options such as nogui can be set. The options set here are built into the start command as follows: java -jar paper.jar nogui

info

In the process parameters, all options must be passed individually, which means that each entry may contain at most one option and additional ones must be added to new entries. So the options should look as follows:

"processParameters": ["nogui", "prettyGoodOption"],

instead of

"processParameters": ["nogui prettyGoodOption"],

EnvironmentVariables

The EnvironmentVariables setting offers the possibility to set environment variables for the services of the task. Each variable has a key and a value that is hidden behind this key. With this key, the value can later be read out on the service. The environment variables can be set as follows:

"environmentVariables": {
  "KEY": "VALUE",
  "ANOTHER_KEY": "another-value"
}

info

The keys of the environment variables are always passed to the service in uppercase letters. In the configuration, these can also contain lowercase letters, but CloudNet always makes them uppercase.

StartPort

The StartPort setting offers the possibility to determine which is the smallest possible port of a service. CloudNet always looks for a free port for services to start, so you don't have to ensure that the port intervals don't overlap. The start port determines at which port CloudNet should begin the search for a free port.

If the start port is set to e.g. 30000 and the service starts, then it is checked whether this port is currently not being used by any other process on the entire host system. If it is already being used, the next port (30001) is tried, until a free port is found.

warnung

If the start port is set too high, the port limit of 65535 can be reached quickly. In this case, no more services can be started. Furthermore, it should be noted that ports <1024 are reserved for the root user. If CloudNet is not started with the root user, this area cannot be used either.

MinServiceCount

The MinServiceCount setting offers the possibility to determine how many services of a task should be available at minimum. CloudNet always tries to create new services until the chosen number is reached. If not enough resources are available, the new services are only created when enough resources are available again. More about resource calculation can be found here.

Templates

The Templates setting offers the possibility to configure which files Services of the task should contain. By default, all templates from the option are copied to the service to be created and then it is started.

When creating a task with the Tasks Setup (COMMAND LINK), a template is also created for this task. Usually, the task name is chosen as the prefix for the template and default is chosen as the name. This does not mean, however, that the templates must follow this specific schema. A task can contain the most diverse templates.

One of these templates from the tasks setup could look like this:

"templates": [
  {
    "prefix": "Fabric",
    "name": "default",
    "storage": "local",
    "priority": 0,
    "alwaysCopyToStaticServices": false
  }
],

At the same time, such templates are also possible:

"templates": [
  {
    "prefix": "Servers",
    "name": "software-plugins",
    "storage": "local",
    "priority": 0,
    "alwaysCopyToStaticServices": false
  },
  {
    "prefix": "Servers",
    "name": "worlds",
    "storage": "local",
    "priority": 0,
    "alwaysCopyToStaticServices": false
  }
],

For more information about templates and the options, see here.

Deployments

The Deployments setting offers the possibility to determine which files of a service should be copied back to a given template after stopping.

Within a task, a deployment that only copies the logs folder back to a template could look as follows:

"deployments": [
  {
    "template": {
      "prefix": "Deploy",
      "name": "fabric-logs-storage",
      "storage": "local",
      "priority": 0,
      "alwaysCopyToStaticServices": false
    },
    "excludes": [
      "wrapper\\.jar",
      "\\.wrapper/"
    ],
    "includes": [
      "logs/.*"
    ],
    "properties": {}
  }
],

warnung

Deployments are executed after files have been deleted that were set under the DeletedFilesAfterStop option. This means that these files cannot be copied, whether specifically included or not.

For more information about deployments, see here.

Includes

The Includes setting offers the possibility to determine which files should be downloaded before starting a service.

A Service Remote Inclusion that downloads e.g. ProtocolLib before starting can look as follows:

"includes": [
  {
    "url": "https://ci.dmulloy2.net/job/ProtocolLib/lastSuccessfulBuild/artifact/build/libs/ProtocolLib.jar",
    "destination": "plugins/ProtocolLib.jar",
    "properties": {}
  }
],

For more information about Remote Inclusions, see here.