Skip to main content

Run a JOD Distribution

Once you get and configured a JOD Distribution, you can start it and use the JOSP Object exposed by that distribution.

The best way to handle JOD Distribution is via JOD Distribution Commands, a set of script that allow you to start/stop distributions. Those scripts are included on each JOD Distribution and (depending on distribution purpose) can be executed on Linux or MacOS via Bash, or on Windows via PowerShell terminals.

That, in conjunction with an SSH session, allow you handle local and remote JOD Distribution in the same way.

When you run a JOSP Object, unless otherwise specified in the documentation, it is executed as "AnonymousObject", that means it has no owner.

To register yourself as a JOSP Object's owner, your must add it via a JOSP Services like the JCP FrontEnd.

  1. Go to Public JCP FrontEnd
  2. Login or register using the top-right button
  3. Go to the 'Objects list' and add your object

Remember to copy the JOSP Object's ID from JOD Agent logs or from the state.sh|ps1 JOD Dist Cmd's output.

To run a JOD Distribution on each device reboot, please see the Install JOD Distribution as a service page.

Open terminal session​

Before run downloaded JOD distribution, you must open distribution directory in to a terminal session.

On local machine​

If downloaded distribution is on your working machine, simply open the terminal program and go to downloaded JOD Distribution dir ($JOD_DIST_DIR).

If you are using a Desktop Environment, you can just open your favourite Terminal application.
If you are using the Linux machine from a console, you are all right.

Then, go to distribution dir with $ cd $JOD_DIST_DIR command.

The JOD Dist TMPL projects provide scripts for Bash shell, so every time you call a JOD Dist Cmd, you must use the $ bash cmd_name.sh command.

On remote device​

Otherwise, if you would run the JOD Distribution on a remote device, you must open an SSH session to the remote device. The SSH connection require remote device's IP or address, there are many ways to get it. Depending on the remote device nature the address can be found via a mDNS/Bonjour discovery service (typical for IoT and Smart Home devices); or it can be got from the service provider that host our cloud services (for those objects that must run on cloud or 24/7); or even it can be the same as the DHCP gateway address (when the remote device is the same as provide the Wi-Fi network).

In Linux/MacOS environment you can use the ssh command to connect to a remote device via SSH protocol. This command accept different params to configure the connection with the remote device.
Once the SSH session was opened, you can go to the downloaded JOD Distribution dir.

SSH Connection to remote device
$ ssh [{REMEOTE_USER}@]{REMOTE_HOST}[:{REMOTE_PORT}]
REMOTE_USER@REMOTE_HOST $ cd {JOD_DIST_DIR}
  • REMOTE_USER: username to use on login to the remote device. During the ssh initialization, it asks you for the user password. Check device's documentation for user and password credentials. If not set, current username from local machine will be used.
  • REMOTE_HOST: hostname or ip address of the remote device. You can discover it as described above, or check the device's documentation.
  • REMOTE_PORT: by default ssh works with port 22, some device may change it. Use this param to override default port.

Run JOD Agent​

Now you are in the JOD Distribution directory and can execute his JOD Distribution Commands.

The start.sh|ps1 script runs the JOD Agent, the software that expose the JOSP Object to the JOSP EcoSystem. By default, this script runs the JOD Agent as a background process, then you can close the terminal's session, and the JOD Agent still run after that. Otherwise, with the FOREGROUND param you can run it as a foreground command with the interactive JOD Shell.
Depending on execution mode, you can halt the JOD Agent. Call stop.sh|ps1 script if executed in background mode, or type exit on running JOD Shell.
Logs are always stored in to the logs/jospJOD.log file.

As background process​

Here an example to execute the JOD Distribution as a background process and get his JOSP Object's id with the state.sh|ps1 script:

Run JOD Agent as background process
$JOD_DIST_DIR/ $ bash start.sh
                 < Start command logs
$JOD_DIST_DIR/ $ bash state.sh
                 < JOD Agent state (JOSP Object id, JOD Agent process id...)
$JOD_DIST_DIR/ $ tail -f logs/jospJOD.log
                 < JOD Agent logs
                 < Ctrl+C to exit
$JOD_DIST_DIR/ $ bash stop.sh
                 < Stop command logs

As foreground command​

Alternatively an example to execute the JOD Distribution as a foreground command and get his JOSP Object's id from console logs or via objectInfo JOD Shell's command.

Run JOD Agent as background process
$JOD_DIST_DIR/ $ bash start.sh true
                 < Start command logs
                 < JOD Agent logs (and JOSP Object id)
                 > JOD Shell
                 > objectInfo // type 'objectInfo' to print JOSP Object id
                 > ?list      // type '?list' for JOD Shell command list
                 > exit       // type 'exit' to shutdown JOD Agent

Object registration and usage​

Now your JOSP Object is running. Then you can proceed with the [object registration] (/references/josp/jcp/microservices/fe/usage/register_a_josp_object) to register yourself as the object's owner. After that, you can access to that JOSP Object from any JOSP Service (like the JCP FrontEnd), but also share the JOSP Object with your family, friend and colleagues, and may other things.

For more info about the JOSP Objects and understand how your objects and services can interact with the JOSP EcoSystem, see following sections:

Please check the official JSL Service list for available software that can interact with your JOSP Objects.