Add manual installation instructions

README.md

@@ -7,7 +7,12 @@
 </picture>
 <br clear="all">
 
-# 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.
 
 <a name="prerequisites"></a>
 ## Prerequisites
@@ -60,6 +64,14 @@ this repo). You may want to edit the `bind` setting to allow connections to your
 <a name="installing"></a>
 ## Installation
 
+ - [Linux install with systemd](#linux-install)
+ - [Manual installation](#manual-install)
+
+<a name="linux-install"></a>
+### 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.
 
 
+<a name="manual-install"></a>
+### 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.
+
+
+