Custom Service

To permanently run a part of your application as a background service, for example, to operate a queue worker, we provide the custom service configuration.

Configuration

Command

To define the command to run your custom service, use the custom_service.command parameter within the Custom JSON Website Level Configuration:

{
   "custom_service": {
      "command": "~/myservice.sh"
   }
}

Workers

By default, one service worker will be started. You can configure up to 64 parallel workers by setting the custom_service.workers parameter within the Custom JSON Website Level Configuration:

{
   "custom_service": {
      "command": "~/myservice.sh",
      "workers": 64
   }
}

Logging

For each service worker, a dedicated log and error log pair will be created in ~/log/. Output sent to stdout will be appended to custom-service-<number>.log, output sent to stderr will be appended to custom-service-<number>.err.log

$ ls -1 ~/log/custom-service.*
~/log/custom-service-1.err.log
~/log/custom-service-1.log

If you configure multiple workers, a log file pair will be created for each worker:

$ ls -1 log/custom-service.*
~/log/custom-service-1.err.log
~/log/custom-service-1.log
~/log/custom-service-2.err.log
~/log/custom-service-2.log

Control Commands

Start

Your service will be started automatically. If you wish to do so manually, for example, after a manual stop, you can do so by using the custom-service-start command. By default, the command will be run for the first worker. If you have multiple workers, you can select the desired one by using its number as the first parameter.

# start first worker
$ custom-service-start

# start a particular worker
$ custom-service-start 2

Stop

If you wish to do stop a service manually, use the custom-service-stop command. By default, the command will be run for the first worker. If you have multiple workers, you can select the desired one by using its number as the first parameter.

# stop first worker
$ custom-service-stop

# stop a particular worker
$ custom-service-stop 2

Restart

If you wish to do restart a service manually, use the custom-service-restart command. By default, the command will be run for the first worker. If you have multiple workers, you can select the desired one by using its number as the first parameter.

# restart first worker
$ custom-service-restart

# restart a particular worker
$ custom-service-restart 2

Status

To show the status of your custom service, use the custom-service-status command. By default, the command will be run for the first worker. If you have multiple workers, you can select the desired one by using its number as the first parameter.

# show first worker status
$ custom-service-status
● custom-html@1.service - html custom systemd service (instance 1)
   Loaded: loaded (/etc/systemd/system/custom-html@.service; enabled; preset: enabled)
   Active: active (running) since Thu 2025-05-08 09:04:00 CEST; 4h 39min ago

# show status of a particular worker
$ custom-service-status 2
● custom-html@2.service - html custom systemd service (instance 2)
   Loaded: loaded (/etc/systemd/system/custom-html@.service; enabled; preset: enabled)
   Active: active (running) since Thu 2025-05-08 13:38:25 CEST; 6min ago