LIGHTSTREAMER QUICK SETUP
=========================

Thanks for downloading Lightstreamer!

This distribution includes a base installation for development, testing,
and production, and a separate, preconfigured demo environment with
ready-to-run examples.

These QuickStart notes guide you through setting up and running the
demo environment.

By default, Lightstreamer ENTERPRISE Edition runs with a
Demo License, which can be used for evaluation, development, and
testing, but not for production. The Demo License allows a maximum
of 20 concurrent user sessions. If you need to
evaluate Lightstreamer without this limit, or need any information
on the other license types, please contact info@lightstreamer.com.

The Demo License is independent of whether you run the demo environment
or the base installation.

Lightstreamer Server, COMMUNITY Edition, does not require a license
key and can be used for free for any purpose, including production
(see the Software License Agreement for full details).

To see the edition and features you have enabled, open the
Monitoring Dashboard (License tab) of your running Lightstreamer Server.

Please read the Software License Agreement carefully before using
Lightstreamer.


===================
SYSTEM REQUIREMENTS
===================

You need a Java SE platform implementation installed on your system.
You can download a JDK from Oracle:
https://www.oracle.com/java/technologies/downloads/
Alternatively, use another Java SE implementation, such as a distribution
based on OpenJDK.

Lightstreamer Server requires Java 8 or later and is compatible with
versions up to at least Java 27.
A recent version, such as Java 25 LTS, is recommended for best
performance.

The Server must be able to access the Internet for license validation
unless you use the COMMUNITY Edition, a Demo License, or FILE validation.


===============
DEMO QUICKSTART
===============

----------------------
1) Extract the Archive
----------------------

* On a Linux, macOS, or Unix system:
Extract the contents of the tar.gz archive to your hard drive.
A "Lightstreamer" directory will be created, which is your
installation home directory.

* On a Windows system:
Unzip the zip file to your hard drive. A "Lightstreamer" directory
will be created, which is your installation home directory.

-----------------
2) Configure Java
-----------------

The launch scripts use JAVA_HOME if it is set; otherwise, they look
for Java on the system PATH. To select a specific Java installation,
set JAVA_HOME to your JRE or JDK installation directory. Setting it as an
environment variable is the recommended approach, as it keeps the launch
scripts unchanged and spares you from reapplying your changes after a Server
upgrade. Alternatively, you can set it directly in the launch script:

* On a Linux, macOS, or Unix system:
You can set JAVA_HOME in "LS.sh" under the "bin/unix-like" directory.

* On a Windows system:
You can set JAVA_HOME in "LS.bat" under the "bin\windows" directory.

Values set explicitly in these scripts override environment variables.

------------------------
3) Choose Your TCP Ports
------------------------

By default, the demo environment uses TCP ports 8080 for HTTP and
8888 for JMX/RMI.
If either port is already in use on your system, change the corresponding
port in the demo configuration file by editing the following elements
in "examples/demo/conf/lightstreamer_conf.xml":
  <port> (inside the <http_server> block, for HTTP)
  <port> (inside the <rmi_connector> block, for JMX/RMI)

-------------------------
4) Launch the Demo Server
-------------------------

* On a Linux, macOS, or Unix system:
Go to the "examples/demo/bin/unix-like" directory and execute "start.sh".

* On a Windows system:
Go to the "examples\demo\bin\windows" directory and execute
"Start_LS_as_Application.bat".

-----------------------
5) Test the Demo Server
-----------------------

Open your browser at "http://localhost:8080" (change the port number
if you configured a different HTTP port in step 3).

You should see a welcome page with the bundled demos ready to run.
In case of problems, errors are reported in the "Lightstreamer.log"
file under the "examples/demo/logs" directory.

Try the Monitoring Dashboard, a tool for monitoring the
state of the Lightstreamer Server in real time.
In the demo environment, it is accessible without authentication at
"http://localhost:8080/dashboard" (use the same HTTP port as above).

Do not expose the demo environment to untrusted networks.

-----------------------
6) Stop the Demo Server
-----------------------

* On a Linux, macOS, or Unix system:
Go to the "examples/demo/bin/unix-like" directory and execute "stop.sh".

* On a Windows system:
Go to the "examples\demo\bin\windows" directory and execute
"Stop_LS_as_Application.bat".


==========================
DEVELOPMENT AND PRODUCTION
==========================

--------------------------
Develop Your Applications
--------------------------

To develop and deploy your own applications, use the base installation
rather than the demo environment. Its main configuration file is
"conf/lightstreamer_conf.xml".

To deploy your application, first add and configure your Adapters.
Then configure at least one HTTP or HTTPS listening port (including a TLS
keystore and its access settings for HTTPS), Client access policies, and
management credentials. Unlike the demo environment, the base installation
does not serve the bundled demo pages and requires authentication for the
Monitoring Dashboard.

After configuring the base installation, start it with "start.sh" under
"bin/unix-like" on Linux, macOS, or Unix, or "Start_LS_as_Application.bat"
under "bin\windows" on Windows. See the "README.TXT" file in the
corresponding script directory for configuration and launch options.

To use the provided stop scripts, ensure that the JMX RMI connector
(<rmi_connector> within <jmx>) is enabled and accessible locally on its
configured TCP port (8888 by default). Define at least one <user> with an
id and password in this block; the scripts use the first user configured.

An Adapter is a software component that connects Lightstreamer Server
to your data sources. To develop a Lightstreamer Adapter, you can
choose among Java, .NET, Node.js, Python, and plain TCP sockets.

A Client connects to Lightstreamer Server to subscribe to the real-time
data provided by your data sources. To develop a Lightstreamer Client,
you can choose among many different technologies, including JavaScript,
iOS, Android, Java, .NET, and Unity.

To learn the main concepts of Lightstreamer development, start with
the following resources:

* "Hello World" examples:
  JavaScript Client:
  https://github.com/Lightstreamer/Lightstreamer-example-HelloWorld-client-javascript
  Java Adapter:
  https://github.com/Lightstreamer/Lightstreamer-example-HelloWorld-adapter-java

* Demo Gallery with links to full source code hosted on GitHub:
  https://demos.lightstreamer.com/

* General theory:
  "docs/General Concepts.pdf"

* Developer guides and API references for Adapter and Client SDKs:
  follow the "API Docs" and "Protocol Specs" links on the download page:
  https://lightstreamer.com/download/

* Online support forum:
  https://forum.lightstreamer.com

-----------------
Production Notes
-----------------

Use the base installation, not the demo configuration, for production.

- Remove the "examples" folder, which contains the demo environment and
its ready-to-run pages. It is intended for development and testing only
and should not be present in a production deployment.

- Review the JVM options for your workload, particularly heap sizing and
garbage collection. Set JAVA_OPTS in the environment or in the launch
script described in step 2 of the Demo QuickStart. Explicit settings in
the script override the environment.

- To enable HTTPS on Lightstreamer Server, configure it in
"conf/lightstreamer_conf.xml" and provide a valid, trusted certificate.
The default certificate is for local testing only; accepting it as a
browser security exception is not suitable for production.

-----------------
Security Warnings
-----------------

The base installation ("conf/lightstreamer_conf.xml") already ships with
secure defaults, so no security change is required to deploy it safely.
The following notes are warnings about configuration changes that, if applied
carelessly, may expose private information on the Server operations to
unauthorized people. Review them before relaxing any of the related settings.

1) Monitoring Dashboard access.

   The embedded Monitoring Dashboard lets you monitor the Server status in
   real time and administer the Server through its embedded JMX web client.
   In the base configuration, Dashboard access already requires
   authentication (<public> is set to N within <dashboard>). To enable access:
   - keep <public> set to N and define at least one user id and password
     using the <user> elements;
   - keep <available_on_all_servers> set to N and use the
     <available_on_server> elements to make the Dashboard available through
     a dedicated listening port and/or NIC, isolated from external traffic;
   - set <jmxtree_enabled> to Y to enable the JMX Tree tab.
   If you broaden access, also consider these precautions:
   - change the default Dashboard URI using <dashboard_url_path>;
   - leave the JMX Tree tab disabled (<jmxtree_enabled> set to N), or
     restrict its visibility using the "jmxtree_visible" attributes on
     the <user> and <available_on_server> elements;
   - if your edition supports SSL/TLS, make the Dashboard available only
     over HTTPS to protect passwords from interception.

2) JMX access.

  The Java Management Extensions (JMX) interfaces provide a standard way to
  monitor and administer the Server and is also used by the provided
  "stop" scripts. In the base configuration, <rmi_connector> already
  requires authentication (<public> is set to N). To enable access, define
  at least one user id and password using the <user> elements.
  Keep <public> set to N and use your firewall to restrict access to these
  JMX TCP ports:
  - <port> within <rmi_connector> (8888 by default)
  - <data_port> within <rmi_connector> (unused by default)
  - <port> within <jmxmp_connector> (unset by default)

3) Cross-origin policies.

   The base configuration disallows access from any page, even on the local
   host, by having <use_protected_js> set to Y and <cross_domain_policy>
   containing no <allow_access_from> rule. If you relax these elements to
   permit access, read the inline elements documentation carefully.
   Note anyway that those rules only apply to browser-based JavaScript
   client connections and do not prevent in any way accesses from
   other kinds of clients.

4) HTTPS strength.

   If you use HTTPS, consider making it stronger:
   - Ensure that the 256-bit cipher suites are installed in your Java Virtual
     Machine, as for some JVMs and in some countries such cipher suites need to
     be downloaded separately (search for "JCE Unlimited Strength Jurisdiction
     Policy Files").
   - Disable low-encryption ciphers (usually those with key length smaller than
     128 bits): set the "LightstreamerLogger.io.ssl" logger in
     "lightstreamer_log_conf.xml" to DEBUG, inspect the enabled cipher suites
     in the log file, and configure the ones to disable through the
     <remove_cipher_suites> elements (or, equivalently, express the allowed
     ones through the <allow_cipher_suite> elements). Keeping the preconfigured
     lines is advisable.
   - Disable weak protocols (for instance SSLv3, already disabled by the
     supplied configuration): inspect the enabled protocols through the same
     logger and configure the ones to disable through the <remove_protocols>
     elements (or, equivalently, the <allow_protocol> elements). Keeping the
     preconfigured line is advisable.

5) Internal Web Server.

   In the base configuration the internal Web Server is completely disabled
   (<enabled> is set to N within the <web_server> element); it is available
   only in the demo configuration. As it is recommended to host your pages on
   an external Web server, do not enable the internal Web Server in production.

6) Server version information disclosure.

   By default the Server, when identifying itself to the clients (for instance
   through the "Server" HTTP response header), would include information on its
   current version and build. The base configuration already overrides this
   default by setting the <server_tokens> element to MINIMAL, so that such
   information is suppressed. Keep this setting unless disclosing version
   information is compliant with your security policies.

7) Local configuration information sent to the clients.

   Upon connection, the Server notifies the client of the local port on which
   it managed the request, reporting the "name" attribute of the <http_server>
   or <https_server> block on which the port is configured; ensure that the
   chosen names don't convey meaningful information.
   The Server may also notify the client of the client's IP address as seen by
   the Server. This is supposed to be a public address, but its determination
   depends on the <client_identification> block; if the configuration is not
   correct, the determined address may be one from the local intranet. For this
   reason, the base configuration already overrides the default by setting the
   private="Y" attribute on the <client_identification> block, which prevents
   the address from being sent to the clients. Keep this setting unless you are
   sure the determined address is public.

Enjoy!
