Basic Use

Using the gda client command

Assuming the daemon is running on the control machine for a beamline and the client is being run on one of the beamline workstations, no configuration or arguments should be needed.

$ # (re)start the server
$ gda server
$ # Stop the server
$ gda server stop
$ # Start the client
$ gda client

The interface has remained largely unchanged from the previous scripts except where it made sense to make things more consistent or better follow conventions. For the equivalent to common commands that have changed, see the migration page.

If $BEAMLINE is defined, control machine will be assumed to be http://$BEAMLINE-control:50051. If $BEAMLINE is not defined and no host is specified on the command line, localhost will be used.

Alternative servers

If you are not running on a beamline workstation or you would like to interact with a different beamline, you can specify the host with the -H or --host option.

$ # start the server on ixx-control
$ gda --host ixx-control server

Accessing help

The full CLI docs are available via the help command. Passing --help to any subcommand will give more detailed help on that specific command.

There is also more documentation available in the cli reference section and its sub-pages. If anything is unclear or does not behave as expected, please open an issue here.

Running the amygdala daemon

The amygdala daemon takes its configuration from two sources. The fields that determine how the process itself runs, are passed as command line arguments - for full details see the amygdala CLI reference. The fields that determine how the GDA processes it launches are started and managed, are loaded from a configuration file. This file is detailed in the config file reference section and can either be set via the -c/--config CLI option, or via the $AMYGDALA_CONFIG environment variable.

For beamline controls machines, the process should be running automatically via systemd. To restart it or to check its status you can use systemctl as a user with sufficient privileges on the control machine (with sudo if required).

$ # Check the status - this should include the path to the binary that is
$ # running if needed
$ systemctl status gda_launcher.service
● gda_launcher.service - "Amygdala - GDA server launcher for ixx"
...
$ # Restart the daemon (see also `gda manage restart` command)
$ sudo systemctl restart gda_launcher.service
...
$ # Stop the daemon (eg to try running the nightly version for testing)
$ sudo systemctl stop gda_launcher.service
...
$ # To start the nightly version
$ sudo systemctl start gda_launcher_nightly.service
...

Running locally

To run the amygdala daemon on a local workstation for development, you can either set the $AMYGDALA_CONFIG environment variable to a config file, or pass the path as an option on the command line:

$ export AMYGDALA_CONFIG=/path/to/config.toml
$ amygdala serve
<...> Starting Amygdala server version="0.3.0" ...
...

The process will then run in the foreground and can be interrupted using Ctrl-C. If a GDA server is running, it will be shutdown gracefully before the process exits. If it has crashed for some reason and amygdala is waiting for it, pressing Ctrl-C again while it is shutting down will send a SIGKILL to the GDA server and terminate immediately.

High level logging related to the service itself is written to the terminal, while more detailed debug logs are available via the -v/--verbose flag. This can be repeated to increase the logging level to DEBUG and then TRACE. Logs can also be written to a date-stamped file in the directory specified by log_directory. The directory being used should be printed to the terminal at start up.

To develop the amygdala codebase itself, see the developer section.