diff --git a/README.md b/README.md index 22fa22f..923e2b9 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,12 @@
-# SMA-X server configuration +# smax-server + +SMA Exchange (SMA-X) server configuration kit. + +Last updated: 19 September 2024 + ## Table of contents @@ -21,10 +26,10 @@ ## Introduction The [SMA information eXchange (SMA-X)](https://docs.google.com/document/d/1eYbWDClKkV7JnJxv4MxuNBNV47dFXuUWu7C4Ve_YTf0/edit?usp=sharing) -is a high performance and versatile data sharing platform for distributed software systems. It is built around a -central Redis database, and provides atomic access to structured data, including specific branches and/or leaf nodes, -with associated metadadata. SMA-X was developed at the Submillimeter Array (SMA) observatory, where we use it to share -real-time data among hundreds of computers and nearly a thousand individual programs. +is a high performance and versatile real-time data sharing platform for distributed software systems. It is built +around a central Redis database, and provides atomic access to structured data, including specific branches and/or +leaf nodes, with associated metadadata. SMA-X was developed at the Submillimeter Array (SMA) observatory, where we use +it to share real-time data among hundreds of computers and nearly a thousand individual programs. SMA-X consists of a set of server-side [LUA](https://lua.org/) scripts that run on [Redis](https://redis.io) (or one of its forks / clones such as [Valkey](https://valkey.io) or [Dragonfly](https://dragonfly.io)); a set of libraries to @@ -43,8 +48,7 @@ started. document - [Smithsonian/smax-clib](https://github.com/Smithsonian/smax-clib) -- a C/C++ client library for SMA-X - [Smithsonian/smax-python](https://github.com/Smithsonian/smax-python) -- a Python 3 client library for SMA-X - - [Smithsonian/smax-postgres](https://github.com/Smithsonian/smax-postgres) -- a Postgres connector application for - creating a historical record of the realtime data stored in SMA-X. + - [Smithsonian/smax-postgres](https://github.com/Smithsonian/smax-postgres) -- to create a historical records of SMA-X data in a PostgreSQL time series database. ## Prerequisites @@ -60,6 +64,14 @@ this repo). You may want to edit the `bind` setting to allow connections to your ## Installation + - [Linux install with systemd](#linux-install) + - [Manual installation](#manual-install) + + +### Linux install with systemd + +These instructions are for Linux systems (RPM or Debian based) using `systemd`. + After you have installed and configured Redis (or equivalent), you can configure the Redis server for SMA-X. Simply run ```bash @@ -70,7 +82,7 @@ It will ask you some questions on how exactly you want SMA-X to be installed and an alternative installation mode as an argument to `install.sh`. The following modes are supported: - `auto`: Automatic installation and startup - - `sma` : Automatic installation and startup at the SMA + - `sma` : Automatic installation and startup at the Submillimeter Array (SMA) - `help`: Provides a simple help screen only. Additionally, you may define a couple of shell variables prior to invoking `install.sh` to guide its behavior: @@ -82,3 +94,28 @@ Additionally, you may define a couple of shell variables prior to invoking `inst After a successful installation you may use `systemctl` to manage `redis` and the `smax-scripts` services. + +### Manual installation + +You can also install and configure SMA-X manually, for non-systemd and/or non-Linux systems (e.g. MacOS X, BSD, +Linux SysV, Windows), following the steps below: + +1. Configure your Redis server, for your network and other preferences. + +2. Copy the LUA scripts from the `lua/` folder to an appropriate location for your boot service manager (e.g. + `/usr/share/smax/lua` or equivalent). Optionally, edit the LUA scripts to remove any SMA-specific content, which + is clearly marked. + +3. If your system has bash, copy `smax-init.sh` to an appropriate location (e.g. `/usr/bin` or equivalent) from where + your service manager may run it. Edit the script to reflect the location where you installed the LUA scripts. + Alternatively, you may create a similar initializer for your system using the script language of your choice. + (`smax-init.sh` simply uses a set of `redis-cli` commands to initialize a Redis database for SMA-X.) + +4. To start SMA-X on boot, first make sure that the Redis server is started on boot. Conditional on Redis being + available, you should then configure your system to run the loader script (`smax-init.sh` or equivalent) also on + boot, after Redis. + +5. Reboot or else start Redis and run the LUA script loader manually. + + +