{"id":18818430,"url":"https://github.com/smithsonian/smax-server","last_synced_at":"2025-10-17T23:58:22.687Z","repository":{"id":257167209,"uuid":"629682017","full_name":"Smithsonian/smax-server","owner":"Smithsonian","description":"Server configuration kit for the SMA-X structured realtime database","archived":false,"fork":false,"pushed_at":"2024-12-20T15:51:46.000Z","size":114,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":10,"default_branch":"main","last_synced_at":"2024-12-30T02:43:16.244Z","etag":null,"topics":["data-exchange","data-exchange-standard","distributed-systems","lua-script","open-source","real-time-database","real-time-systems","realtime-database","realtime-system","redis","redis-server","structured-data"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Smithsonian.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-18T20:12:27.000Z","updated_at":"2024-12-20T15:51:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"6ba1f3a1-9417-4867-92e4-f50583dbab43","html_url":"https://github.com/Smithsonian/smax-server","commit_stats":null,"previous_names":["smithsonian/smax-server"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Smithsonian%2Fsmax-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Smithsonian%2Fsmax-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Smithsonian%2Fsmax-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Smithsonian%2Fsmax-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Smithsonian","download_url":"https://codeload.github.com/Smithsonian/smax-server/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239753733,"owners_count":19691162,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-exchange","data-exchange-standard","distributed-systems","lua-script","open-source","real-time-database","real-time-systems","realtime-database","realtime-system","redis","redis-server","structured-data"],"created_at":"2024-11-08T00:16:42.671Z","updated_at":"2025-10-17T23:58:22.662Z","avatar_url":"https://github.com/Smithsonian.png","language":"Lua","readme":"![Installer status](https://github.com/Smithsonian/smax-server/actions/workflows/test.yml/badge.svg)\n\n\u003cpicture\u003e\n  \u003csource srcset=\"resources/CfA-logo-dark.png\" alt=\"CfA logo\" media=\"(prefers-color-scheme: dark)\"/\u003e\n  \u003csource srcset=\"resources/CfA-logo.png\" alt=\"CfA logo\" media=\"(prefers-color-scheme: light)\"/\u003e\n  \u003cimg src=\"resources/CfA-logo.png\" alt=\"CfA logo\" width=\"400\" height=\"67\" align=\"right\"/\u003e\n\u003c/picture\u003e\n\u003cbr clear=\"all\"\u003e\n\n# smax-server\n\n[SMA Exchange (SMA-X)](https://docs.google.com/document/d/1eYbWDClKkV7JnJxv4MxuNBNV47dFXuUWu7C4Ve_YTf0/edit?usp=sharing)\nstructured real-time database server configuration kit.\n\nLast updated: 19 September 2024\n\n\n## Citation\n\nIf you use SMA-X for your project, please cite as: \n\n - Kovács, Attila, Grimes, Paul K., Moriarty, Christopher, and Wilson, Robert, Journal of Astronomical Telescopes, Instruments, and Systems, Volume 11, id. 017001 (2025). (DOI: [10.1117/1.JATIS.11.1.017001](https://ui.adsabs.harvard.edu/link_gateway/2025JATIS..11a7001K/doi:10.1117/1.JATIS.11.1.017001)). \n\nYou may also find the citation record on ADS as [2025JATIS..11a7001K](https://ui.adsabs.harvard.edu/abs/2025JATIS..11a7001K/abstract).\n\n\n## Table of contents\n\n - [Introduction](#introduction)\n - [Prerequisites](#prerequisites)\n - [Installation](#installing)\n\n------------------------------------------------------------------------------\n\n\u003ca name=\"introduction\"\u003e\u003c/a\u003e\n## Introduction\n\nThe [SMA Exchange (SMA-X)](https://docs.google.com/document/d/1eYbWDClKkV7JnJxv4MxuNBNV47dFXuUWu7C4Ve_YTf0/edit?usp=sharing) \nis a high performance and versatile real-time data sharing platform for distributed software systems. It is built \naround a central Redis database, and provides atomic access to structured data, including specific branches and/or \nleaf nodes, with associated metadata. SMA-X was developed at the Submillimeter Array (SMA) observatory, where we use \nit to share real-time data among hundreds of computers and nearly a thousand individual programs.\n\nSMA-X consists of a set of server-side [LUA](https://lua.org/) scripts that run on [Redis](https://redis.io) (or one \nof its forks / clones such as [Valkey](https://valkey.io) or [Dragonfly](https://dragonfly.io)); a set of libraries to \ninterface client applications; and a set of command-line tools built with them. Currently we provide client libraries \nfor C/C++ and Python 3. We may provide Java and/or Rust client libraries too in the future.\n\nThis repository is for the SMA-X server configuration specifically. It contains a LUA scripts, a shell script to load \nthem into a database, and a `systemd` unit file that allows to load the SMA-X scripts automatically whenever Redis is \nstarted.\n\n\n \u003ca name=\"related-links\"\u003e\u003c/a\u003e\n### Related links\n\n - [SMA-X specification](https://docs.google.com/document/d/1eYbWDClKkV7JnJxv4MxuNBNV47dFXuUWu7C4Ve_YTf0/edit?usp=sharing) \n   document\n - [Smithsonian/smax-clib](https://github.com/Smithsonian/smax-clib) -- a C/C++ client library for SMA-X\n - [Smithsonian/smax-python](https://github.com/Smithsonian/smax-python) -- a Python 3 client library for SMA-X\n - [Smithsonian/smax-postgres](https://github.com/Smithsonian/smax-postgres) -- to create a historical records of \n   SMA-X data in a PostgreSQL time series database.\n\n\u003ca name=\"prerequisites\"\u003e\u003c/a\u003e\n## Prerequisites\n\nBefore you install the SMA-X server configuration, you will need to install [Redis](https://redis.io) (or one \nof its forks / clones such as [Valkey](https://valkey.io) or [Dragonfly](https://dragonfly.io)). On Linux you may simply \nuse your package manager such as `dnf` (RPM-based distros) or `apt` (Debian-based distros).\n\nAfter installing Redis (or equivalent), edit `/etc/redis.conf` (or equivalent) to customize for your system. We provide\na sample configuration file for local connections (from 127.0.0.1 only) and with logging enabled (see `redis.conf` in \nthis repo). You may want to edit the `bind` setting to allow connections to your Redis server from your local network.\n\n\u003ca name=\"installing\"\u003e\u003c/a\u003e\n## Installation\n\n - [Linux install with SystemD](#linux-install)\n - [Manual installation](#manual-install)\n\n\u003ca name=\"linux-install\"\u003e\u003c/a\u003e\n### Linux install with SystemD\n\nThese instructions are for Linux systems (RPM or Debian based) using `systemd`. \n\nAfter you have installed and configured Redis (or equivalent), you can configure the Redis server for SMA-X. Simply run\n\n```bash\n  sudo ./install.sh\n```\n\nIt will ask you some questions on how exactly you want SMA-X to be installed and deployed. Optionally, you may define\nan alternative installation mode as an argument to `install.sh`. The following modes are supported:\n\n - `auto`: Automatic installation and startup\n - `sma` : Automatic installation and startup at the Submillimeter Array (SMA)\n - `help`: Provides a simple help screen only.\n \nAdditionally, you may define a couple of shell variables prior to invoking `install.sh` to guide its behavior:\n\n - `DESTDIR` : Set the deployment root directory (default is `/usr`)\n - `PREFIX`  : Set a staging prefix. If `PREFIX` is defined and not empty, `install.sh` will stage only, without\n   starting up services (which are not yet in their final location).\n\nAfter a successful installation you may use `systemctl` to manage `redis` and the `smax-scripts` services.\n\n\n\u003ca name=\"manual-install\"\u003e\u003c/a\u003e\n### Manual installation\n\nYou can also install and configure SMA-X manually, for non-SystemD and/or non-Linux systems (e.g. MacOS X, BSD,\nLinux SysV, Windows), following the steps below:\n\n1. Configure your Redis or Valkey server, for your network and other preferences.\n\n2. Copy the LUA scripts from the `lua/` folder to an appropriate location (e.g. `/usr/share/smax/lua`). Optionally, \n   edit the LUA scripts to remove any SMA-specific content, which is clearly marked.\n   \n3. If your system has bash, copy `smax-init.sh` to an appropriate location (e.g. `/usr/bin` or equivalent) from where \n   you or your service manager may run it. Edit the script to reflect the location where you installed the LUA \n   scripts. Alternatively, you may create a similar initializer for your system using the script language of your \n   choice. \n   \n4. If using Valkey (not Redis) as your server, you should also replace `redis-cli` in your installed `smax-init.sh`\n   with `valkey-cli` (`smax-init.sh` simply uses a set of `redis-cli` commands to initialize a Redis database for \n   SMA-X.)\n\n4. To start SMA-X on boot, first make sure that the Redis server is started on boot. Conditional on Redis being \n   available, you should then configure your system to run the loader script (`smax-init.sh` or equivalent) also on \n   boot, after Redis.\n   \n5. Reboot or else start Redis and run the `smax-init.sh` manually.\n\n\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmithsonian%2Fsmax-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmithsonian%2Fsmax-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmithsonian%2Fsmax-server/lists"}