Local-only setup

Explains advanced satellite setup with all code and configuration deployed as local files (for security-sensitive environments).

Standard satellite installation run code and configuration deployed from server (both code and configuration files are stored as assets).
Server also has ability to call any service on any satellite, which is typically used to shutdown or restart the satellite.

This setup might be unacceptable for some customers with strict operation security guidelines; in that case, it is possible to disable any and all control of server over the satellite. All code and configuration will be used from local files and server can only provide website content.

Ignoring server-supplied deployments and calls

Satellite can be started in special mode in which all deployment requests and service calls from server are ignored.
This mode completely disables one direction of the deployment protocol; when enabled, satellite never asks for updates and completely ignores any commands issued from server (including, but not limited to "Satellite restart" and "Satellite shutdown").
The opposite direction is not affected and satellite keeps sending status information about active bundles and services.

There are three ways to enable this mode:

• Special property in config.properties (any non-empty value other than false (case-insensitive) is considered true)
  BASH

    com.censhare.satellite.deployer.DeployerService$disable-server-control=true

• Environment variable DISABLE_SERVER_CONTROL (any non-empty value other than false (case-insensitive) is considered true). This is useful mainly in docker environment.
• Commandline option of Satellite.sh script:
  BASH

    ./bin/Satellite.sh start --disable-server-control

- This option actually sets the environment variable **DISABLE_SERVER_CONTROL**, but it also clears the **work** directory ensuring that any previous deployments are not present by accident.

Disabled server control is indicated in satellite log by following line:

c.c.s.d.impl.DeployerServiceImpl  - server control disabled: no deployments and calls from server will be accepted!

Note: This mode prevents deployment from server, but it does not affect any deployment that has been already done! If the satellite has been already started in standard mode, deployed bundles and configurations can be removed by cleaning all contents in the work directory. This is automatically done when using the ./bin/Satellite.sh start --disable-server-control option.

Local deployment of bundles (static)

OSGI bundles that are normally stored as assets on censhare server can be deployed simply by copying them to bundles/ directory (this directory already contains some OSGI bundles necessary for satellite to start and to connect to the server).

Note: unlike deployment via assets, adding (and removing or replacing) OSGI bundles requires restart; all jar files in this directory are loaded only once when satellite starts.

Local deployments of configuration files (dynamic)

Unlike OSGI bundles, configuration files can be only deployed dynamically either from server (assets) or from special local directory for dynamic deployment.
There is no such directory by default; it must be created and configured in config.properties:

com.censhare.satellite.deployer.DeployerService$deployment-dir=dynamic-deployment

This directory is watched for changes (added, removed, or changed files). Each added file is parsed and if its content is valid XML configuration file or OSGI bundle, it is deployed.

• Any file with .xml suffix is parsed and if it contains valid OC bundle configuration, it is deployed. Note that the filename itself is completely irrelevant, aside the extension.
• Any file with .jar suffix is parsed and if it contains valid OSGI bundle, it is deployed. Note that the filename itself is completely irrelevant, aside the extension.

Note that these deployments and undeployments are done in runtime and do not require restart. On the contrary, changing content of dynamic deployment directory while the satellite is stopped can lead to inconsistent state; in particular, configurations (or bundles) deleted during shutdown are never properly uninstalled!
Such situation can be solved by work directory cleanup:

./bin/Satellite.sh restart --clean-work

or by using the commandline option (which also cleans work directory on each start):

./bin/Satellite.sh start --disable-server-control

Required configuration asset on server

Datastore configuration is special: each instance must be present on both satellite and censhare server, because some crucial security-sensitive configuration options are required for server operation.
Most important is the list of output channels (<output-channels> element) and other options that restrict data set accessible by the satellite. Even if the satellite configuration is compromised, it cannot access (or even modify) sensitive data stored on server.

Usually, both configuration files are kept the same; there is, however, one important case where different versions makes sense: AWS S3 configuration. Both configurations must use the same buckets, but they might use different credentials (read-only for satellite, full access for server).