Water Managers, System Administrators or Modelers use the OpenDCS GUI to edit platform information, edit a configuration, add a routing spec, or add an algorithm or computation, etc.   This page describes three ways to launch the OpenDCS GUI.  The sections below are intended for a System Administrator or someone of an comparable skill set and who already has the proper access/permission to the server granted.  Two methods are described for launching OpenDCS from the servers directly, and another method for using the Windows Client.   Users are encouraged to use the Windows Client.  However, depending on the person or task at hand, there are cases where launching the GUI from the server may be necessary.  For example, a) using the DECODES Database Editor to retrieve or view messages (i.e. for backfilling or cleaning out garbage in messages) or b) running computations from the Computation Editor that rely on or use files currently stored the server.  

Server

Both methods outlined below assume the user is familiar with logging into a Unix terminal as oneself and has an ssh key pair set up for oneself.   In the sections below xxdcsaxx user refers to the districts DCSA user account, where xx & xx are unique to each office.

Checklist Before Getting Started:

  1. I have Putty or another applicable software.
    1. If not, see the app portal and search for the latest version of Putty (i.e. Putty Gen)
  2. I can log onto the USACE server as oneself. 
    1. I.e. if run command whoami , should be your Unix account.

    2. whoamil

      $ whoami
username
      BASH
  3. I have set up a ssh key pair for oneself.
  4. I have Xming or another suitable X windows software.
    1. If not, see the app portal and search for the latest version of Xming
    2. Optional: Create a shortcut to xming.exe (suggest putting in location close to session or session shortcuts)
    3. Optional Tip: In the shortcut Target, add ` -multiwindow` at the end of the target. This will make the Window GUI a reasonable size versus taking up the entire screen.  To access Properties right click on the shortcut and navigate to the "Shortcut" tab.

Method 1: Direct Log In to DCSA User

The steps below are instructions for setting up an ssh key directly to the dcsa user.  Once steps 1-3 are completed, users can use a putty session to log in directly and become the dcsa user and launch the GUI (steps 4-5).  In other words, steps 1-3 are one-time steps for each user.  Once completed, users will do steps 4-5 to launch the OpenDCS GUI directly from the server.

  1. Get Your Public Key:
    1. Log into a Unix terminal with an ssh key - as oneself.
    2. Navigate to the .ssh folder

      1. navigate to your .ssh folder

        cd .ssh
        CODE
    3. View the contents of the authorize_keys  file
    4. Copy the public key (i.e. copy to clipboard or even paste into a text editor)
  2. Update the DCSA Public Key
    1. Become the dcsa user

      1. become dcsa user using sudo command

        sudo -iu xxdcsaxx
        CODE
    2. Navigate to the dcsa .ssh folder

      1. navigate to the dcsa .ssh folder

        cd .ssh
        CODE
    3. Verify that the permissions on the .ssh file are rw only for the dcsa user (drwx------) 
      1. If not, make necessary changes using chmod  command
    4. Using VI or VIM, edit the authorized_keys file
      1. Add the public key that was copied from the users authorized_keys  file.  Save and close.
      2. Verify that the permissions on the authorized_keys file are rw only (-rw-------)
        1. If not, make necessary changes using chmod command
    5. Close terminal session
  3. Create a New Putty Session - Directly to DCSA user
    1. Make a copy of the putty session that uses the keypair for your user account
    2. In the new session make the following edits:
      1. Add xxdcsaxx@ before the hostname in the hostname box.
      2. Add some naming to your session name to identify this session and that it goes directly to the xxdcsaxx user. 
      3. Navigate to the X11 options ( on the left hand side under Category see → Connection → SSH → Auth → X11) in the Putty session and make sure that "Enable X11 forwarding" is checked.  
      4. Save the session.
  4. Open New Putty Session Directly to DCSA user
    1. This session will go directly to the dcsa user account, without any prompt for a password. 
    2. Verify the user is the dcsa by using whoami .  
    3. Start X Windows - (ie. by clicking the Xming shortcut). NOTE - this step can be done prior to opening the putty session.
  5. Launch OpenDCS GUI
    1. To launch OpenDCS from the server, type launcher_start  (& optional). Note that the location of the file 

      1. launch GUI using launcher_start command

        launcher_start &
        CODE

    2. And then the following menu will pop up.  This means the GUI is launched.  

       

Method 2: Manipulating X Authority

The steps below are instructions for manipulating X Authority.  The following commands should be run each time before becoming the dcsa user.  The steps below assume a user is familiar with how to log into a Unix terminal, and that they know how to become the dcsa user.   By default, when a user logs onto the server as ones self, and then becomes the dcsa user, the OpenDCS GUI will not launch.  This is because of XWindows authorization.  In the steps below, the user will temporarily manipulate the X Authority information such that they can launch the OpenDCS GUI during this session.  

  1. Log into a Unix terminal as oneself.  
  2. Manipulate the file (as oneself, NOT the dcsa or cwpa user).  The following commands change the X-Authority permissions.
    1. chmod o+x `echo $XAUTHORITY | cut  -f1-3 -d "/"`
chmod o+r `echo $XAUTHORITY`
      BASH
  3. Become the dcsa user

    1. become the dcsa user

      sudo -iu xxdsaxx
      CODE
  4. Launch OpenDCS GUI
    1. To launch OpenDCS from the server, type launcher_start  (& optional to make the GUI run in the background)

      1. launch GUI using launcher_start command

        launcher_start &
        CODE
    2. And then the following menu will pop up.  This means the GUI is launched.   

Either of the methods above will work on the USACE servers.  Alternatively, if a user does not need to log onto the server directly, then using the Windows Client may be sufficient.  See the next section to learn more about the Windows Client. 

Windows Client

The Windows Client is the version that launches from a users Windows PC.   Note that the windows client does not have to be the same version as the version running on the CWMS server.  For example, if a District is running OpenDCS 6.8.14, then a user may be install the windows client 7.0.12.  Sys Admins or Water Managers may prefer using the Windows Client because it requires less steps to log on, is usually faster than launching directly from the server, and if using a more recent version, more features may be available.

Below are the general steps for using the Windows Client.  See online documentation for further information and expanded details on the outline items below: https://opendcs.org 

  1. Verify required version of java is installed and latest client jar from GitHub:
    1. Verify have at least java 1.8
    2. Latest opendcs-installer-#.#.#.jar from GitHub Releases: https://github.com/opendcs/opendcs/releases 
  2. Install Windows Client Software (do not need admin privileges to do this step)
    1. Decide on an install location (i.e. C:\OPENDCS) on local machine and create and empty folder. 
    2. Double click .jar from above and navigate through install directions.  
  3. Configure To Point towards CWMS database
    1. Copy the user.properties from the server (/wm/yyy/xxdcsaxx/opendcs_user/user.properties ) to the windows installation location and rename to decodes.properties (ie C:\OPENDCS\decodes.properties)
  4. Launch Windows OpenDCS GUI
    1. To launch the OpenDCS Windows GUI, double click launcher_start.bat (i.e. "C:\OPENDCS\bin\launcher_start.bat" or "C:\OPENDCS\bin\dcstool_start.bat")

Note that users trying to use the Windows Client to retrieve messages from their LRGS source may need to communicate and coordinate with their counterpart to ensure the Windows IP or computer name is configured in their LRGS configuration.