LYNX-APP Installation for Linux

This page will help you install the LYNX-APP (LYNX Application Component) in a Linux/Unix environment. Follow the steps in order and contact email Series25 Support or your assigned LYNX support analyst for assistance.

See LYNX-APP Installation for Windows.

Requirements for Installation:

  • These instructions should be completed by your school's qualified Linux Systems Administrator.
  • Ensure you have prepared your SIS database by deploying the necessary tables for database integration.
  • The target server may need to be restarted during this process for installation to complete successfully.

Review Java and Network Requirements

  • Review Series25 Technical Specifications.
  • Ensure your target server for this installation is running a suitable version of Java.
    • Java 8, 11 or 15 (32-bit or 64-bit) is currently supported.
    • You may use the Oracle commercial distribution of Java (this may incur licensing fees) or the OpenJDK distribution of Java.
  • Ensure your target server can communicate with your SIS database through the desired JDBC port.
  • Ensure your target server can communicate with CollegeNET's LYNX WebServices ( https://lynx.collegenet.com/ ... SSL / port 443 )
    • If your target server must use a proxy server to reach LYNX WebServices, you can configure it after installation.

Retrieve Installation Files

Consider Deployment Options

  • Consider two options:
    • Install the Production LYNX-APP on the same server as Test LYNX-APP
    • Install the Production LYNX-APP on a separate server from the Test LYNX-APP
  • If you install Prod and Test on the same server, you will need to install the LYNX-APP folder twice. Example:
    • /usr/local/bin/LYNX-APP-test
    • /usr/local/bin/LYNX-APP-prod
    • In this case, run through the instructions below twice, once for each application instance. You will need to flag the process appropriately as Prod or Test on startup (runBackground.sh).
  • If you install Prod and Test on different servers, you will still need to flag the process with an argument when running runBackground.sh (this can be something generic such as LYNX, etc)

Copy Files

  • Create a suitable installation target for the application.
  • The most suitable location may depend on best practices for your Linux/Unix Distribution. Example:
    • /usr/local/bin/LYNX-APP-test/
  • Unzip application files from lynx-app-linux.zip into the target directory.
  • Ensure a ~LYNX-APP/logs/ folder is created (you may have to create this manually)

Update Configuration

  • Navigate to the ~LYNX-APP/config/ folder.
  • Open the application.properties configuration file with an appropriate text editor.
  • Update this file with values for your instance.
    • lynx-url-prefix=https://lynx.collegenet.com/lynx-ws/sis/data/
    • lynx-instance-id=
    • lynx-username=
    • lynx-password=
    • db-url=
      • Example Oracle string
      • db-url=jdbc:oracle:thin:@//server:port/service_name OR db-url=jdbc:oracle:thin@server:port:SID
      • Example Microsoft SQL Server string
      • db-url=jdbc:sqlserver://server.school.edu:1433;DatabaseName=lynx
    • db-username=
    • db-password=
  • If you will use a proxy server to reach LYNX WebServices, configure this now.

Review Execution Permissions

  • LYNX processing is started and stopped through two background scripts:
    • runBackground.sh
    • stopBackground.sh
  • Consider if you will need to change permissions to allow these scripts to execute. Example:
    • chmod +x runBackground.sh

    • chmod +x stopBackground.sh

Test Execution of Background Scripts

Test execution of runBackground.sh.

  • You will need to include an input argument. Example:
    • runBackground.sh TEST
  • Verify the process is running with a suitable command. Example:
    • ps aux | grep lynx
  • The command above, for example, might return a line for the grep, as well as a line indicating the application is running ( ...lynx-app.jar ):
user      2494  6.9  8.5 2584496 169848 pts/0  Sl   11:47   0:09 java -jar -Dmode=TEST lynx-app.jar
user      2584  0.0  0.0 119724  1052 pts/0    S+   11:50   0:00 grep --color=auto lynx
  • LYNX-APP may start correctly, but stop itself if there is an error, such as a network connectivity error.
    • Ensure the process is still running after a few moments.
  • If LYNX does not start correctly, check the ~lynx-app/logs/ folder to investigate possible causes.

Test execution of stopBackground.sh.

  • You will need to include an input argument. Example:
    • stopBackground.sh TEST
  • Verify the process from before is no longer running with a suitable command. Example:
    • ps aux | grep lynx
  • The command above might return just one line for the grep at this point:
user      2605  0.0  0.0 119724  1064 pts/0    S+   11:55   0:00 grep --color=auto lynx
  • Use runBackground.sh to start the LYNX-APP process again for the next step.

Review LYNX Dashboard

  • If LYNX-APP starts correctly and continues to run, verify the LYNX Dashboard web page indicates "APP OK" and no errors are presented.
    • Example: https://lynx.collegenet.com/<instance-name>

Consider Configuring Additional Features

  • You may wish to encrypt the passwords in your application.properties file. See Encrypting Passwords in Your LYNX-APP Config File (Linux)
  • Consider automating the startup of runBackground.sh, using a feature such as /etc/init.d or cron.
  • We recommend testing any additional features in Test first.