{"id":26164698,"url":"https://github.com/optum/legionio","last_synced_at":"2025-04-14T15:22:05.763Z","repository":{"id":56880958,"uuid":"372972312","full_name":"Optum/LegionIO","owner":"Optum","description":"LegionIO is an extensible framework for running, scheduling and building relationships of tasks in a concurrent matter","archived":false,"fork":false,"pushed_at":"2021-10-31T14:05:22.000Z","size":60,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-14T15:21:59.464Z","etag":null,"topics":["async","automation","ifttt","legionio","lex","scheduler"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Optum.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":"SECURITY.md","support":null}},"created_at":"2021-06-01T22:05:53.000Z","updated_at":"2021-10-31T14:03:13.000Z","dependencies_parsed_at":"2022-08-20T13:00:43.984Z","dependency_job_id":null,"html_url":"https://github.com/Optum/LegionIO","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Optum%2FLegionIO","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Optum%2FLegionIO/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Optum%2FLegionIO/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Optum%2FLegionIO/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Optum","download_url":"https://codeload.github.com/Optum/LegionIO/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248904626,"owners_count":21180836,"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":["async","automation","ifttt","legionio","lex","scheduler"],"created_at":"2025-03-11T15:39:38.981Z","updated_at":"2025-04-14T15:22:05.730Z","avatar_url":"https://github.com/Optum.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LegionIO\n\nLegionIO is a framework for automating and connecting things. You can see all the docs inside confluence  \nhttps://legionio.atlassian.net/wiki/spaces/LEGION/overview\nhttps://legionio.atlassian.net/wiki/spaces/LEX/pages/7864551/Extensions\n*Soon to be migrated to GitHub Wiki*\n\n### What does it do?\nLegionIO is an async job engine designed for scheduling tasks and creating relationships between things that wouldn't \notherwise be connected. Relationships do not have to be a single path. Both of these would work\n* `foo → bar → cat → dog`\n```\na → b → c\n    b → e → z\n        e → g\n```\nIn the second scenario, when a runs, it causes b to run which then causes both c and e to run in parallel\n\nIt supports both conditions and transformation. The idea of a transformation is you can't connect two indepedent services \nand expect them to know how to talk to each other. \n\n### Running\nRun `gem install legionio` to install legion. If you want to use database features, you will need to \nrun `gem install legion-data` also. \n\nAfter installing gem you can use the commands `legionio` to start legion, `legion` to access things\nand `lex_gen` to generate a new legion extension\n\n### Example Legion Extensions(LEX)\n* [lex-http](https://github.com/LegionIO/lex-http/src/master/) - Gives legion the ability to make http requests, [docs](https://legionio.atlassian.net/wiki/spaces/LEX/pages/12910593/Lex+Http)\n* [lex-influxdb](https://github.com/LegionIO/lex-influxdb/src/master/) - Write, read, and manage influxdb nodes, [docs](https://legionio.atlassian.net/wiki/spaces/LEX/pages/614891774/Lex+Influxdb)\n* [lex-log](https://github.com/LegionIO/lex-log/src/master/) - Send log items to either stdout or a file with lex-log, [docs](https://legionio.atlassian.net/wiki/spaces/LEX/pages/614858995/Lex+Log)\n* [lex-memcache](https://github.com/LegionIO/lex-memcached/src/master/) - run memcached commands like set, add, append, delete, flush, reset_stats against memcached servers, [docs](https://legionio.atlassian.net/wiki/spaces/LEX/pages/614858753/Lex+Memcached)\n* [lex-pihole](https://github.com/LegionIO/lex-pihole/src/master/) - Allows Legion to interact with [Pi-Hole](https://pi-hole.net/). Can do things like get status, add/remove domains from the list, etc \n* [lex-ping](https://github.com/LegionIO/lex-ping/src/master/) - You can ping things?, [docs](https://legionio.atlassian.net/wiki/spaces/LEX/pages/631373895/Lex+Ping)\n* [lex-pushover](https://github.com/LegionIO/lex-pushover/src/master/) - Connects Legion to [Pushover](https://pushover.net/), [docs]()\n* [lex-redis](https://github.com/LegionIO/lex-redis/src/master/) - similiar to lex-memcached but for redis\n* [lex-sleepiq](https://github.com/LegionIO/lex-sleepiq/src/master/) - Control your SleepIQ bed with Legion!\n* [lex-ssh](https://github.com/LegionIO/lex-ssh/src/master/) - Send commands to a server via SSH in an async fashion, [docs](https://legionio.atlassian.net/wiki/spaces/LEX/pages/614891551/Lex+SSH)\n\nBitbucket repos for extensions that are active or being worked on\n[lex list](https://github.com/LegionIO/workspace/projects/LEX)\nA nice list in the wiki to view all the extensions, their docs and status\n[Legion Extensions](https://github.com/topics/legionio?l=ruby)\n\n### Scheduling Tasks\n1) Ensure you have the Legion::Data gem installed and configured  \n2) Make sure to have `lex-scheduler` extension installed so that it generates the schedules table in the database  \n3) From there you can add a function to be run at a given cron syntax or interval  \n4) Setting the interval column will make the job run X seconds after the last time it is completed and will ignore the cron colum  \n5) Setting the cron column will ensure the job runs at the given times regardless of when it was run last, only works if interval is null  \n6) Cron supports both `*/5 * * * *` style and verbose like `every minute` and `every day at noon`\n\n### Creating Relationships\n*To be populated*\n\n### Conditions\nYou can create complex conditional statements to ensure that when a triggers b, b only runs if certain conditions \nare met. Example conditional statement\n```json\n{\n  \"all\": [{\n    \"fact\": \"pet.type\",\n\t\"value\": \"dog\",\n\t\"operator\": \"equal\"\n  },{\n\t\"fact\":\"pet.hungry\",\n\t\"operator\":\"is_true\"\n  }]\n}\n\n```\nYou can nest conditions in an unlimited fashion to create and/or scenarios to meet your needs\n```json\n{\n  \"all\": [\n\t\"any\":[\n\t  {\"fact\":\"pet.type\", \"value\":\"dog\",\"operator\":\"equal\"},\n\t  {\"fact\":\"pet.type\", \"value\":\"cat\",\"operator\":\"equal\"}\n\t],\n\t{\n\t  \"fact\": \"pet.hungry\",\n\t  \"operator\": \"is_true\"\n\t},{\n\t  \"fact\":\"pet.overweight\",\n\t  \"operator\":\"is_false\"\n\t}]\n}\n```\n*Conditions are supported by the `lex-conditioner` extension and are not required to be run inside the legion framework*  \nYou can read the docs with more examples in the [wiki](https://legionio.atlassian.net/wiki/spaces/LEX/pages/614957181/Lex+Conditioner)\n\n\n### Transformations\nTransformations are a critical piece of interconnecting two independent items. Without it, service B doesn't know what\nto do with the result from service A\n`lex-conditioner` uses a combination of the [tilt](https://rubygems.org/gems/tilt) gem and erb style syntax.\n##### Examples\nCreating a new pagerduty incident \n```json\n{\"message\":\"New PagerDuty incident assigned to \u003c%= assignee %\u003e with a priority of \u003c%= severity %\u003e\",\"from\":\"PagerDuty\"}\n```\nExample transformation to make the `lex-log` extension output a message\n```json\n{\"message\":\"transform2\",\"level\":\"fatal\"}\n```\nYou can also call Legion services to get the data you need, example sending a pushover message\n```json\n{\"message\":\"This is my pushover body\", \"title\": \"this is my title\", \"token\":\"\u003c%= Legion::Settings['lex']['pushover']['token'] %\u003e\" }\n```\nOr if you wanted to make a real time call via `Legion::Crypt` to get a [Hashicorp Vault](https://www.vaultproject.io/) value\n```json\n{\"message\":\"this is another body\", \"title\":\"vault token example\", \"token\":\"\u003c%= Legion::Crypt.read('pushover/token') %\u003e \"}\n```\n*Transformations are supported by the `lex-transformation` extension and are not \"technically\" required to be run inside the legion framework*  \nYou can read the docs with more examples in the [wiki](https://legionio.atlassian.net/wiki/spaces/LEX/pages/612270222/Lex+Transformer)\n\n## FAQ\n### Does it scale?\nYes. Actually quite well. The framework uses RabbitMQ to ensure jobs are scheduled and run in a FIFO order. As you add\nmore works, it just subscribes to the queues the workers can support and does more work. It is really geared towards a\ndocker/K8 type of environment however it can be run locally, on a VM, etc.   \n\nAs of right now, it has been tested to around 100 workers running in docker without any performance issues. You will \nlikely see performance issues on the DB or RabbitMQ side before Legion has issues. \n\nAnother benefit is that you can run multiple LEXs in one worker or you could have dedicated workers that only run a single LEX.  \nIn example if you have to make a ton of ssh connections via `lex-ssh`, maybe you want to run 10 pods with no other extensions in them\nbut then run a pod with `lex-pagerduty`, `lex-log` and `lex-http` to send out notifications after each ssh task is completed\n\n### High Availability\nBecause you can run this thing with multiple processes and it will distribute the work, it is naturally HA oriented. \nif a worker goes down for some reason, another one should pick it up(assuming another work has that LEX enabled). There\nare no hidden features, pay walls, etc to get HA. Just run more instances of LegionIO\n\n### Price and License\nLegionIO is completely free. It was build using free time. There are no features held back, no private repos.\nEverything is under an MIT license to keep it as open as possible. With that, the devs can't always help with support,\nwell because it's free.\n\n### Who is it geared for?\nAnyone? Everyone? It could be used in a homelab to automate updating VMs. It could be used by someone to take ESPHome\nsensor data and pipe it to influxdb. At least that is what @Esity does. It could also be used by a company or enterprise looking\nto replace other tools.\n\n### But it is written in ruby\nYep. \n\n### Similiar projects\nThere are multiple projects that are similiar. Some things like IFTTT are great(but is it?) but then again, cost money.  \n* [Node-Red](https://nodered.org/) - No HA but has some good features and a great drag and drop interface  \n* [n8n.io](https://n8n.io/) - Working on HA but [not there yet](https://github.com/n8n-io/n8n/pull/1294)  \n* [StackStorm](https://stackstorm.com/) - Written in Python, has potential but I feel they are removing features to convince you to pay for it  \n* [Jenkins](https://www.jenkins.io/) - It's jenkins. I don't need to say anything else  \n* [Huginn]() - Another IFTTT style app written in ruby. Not sure on this one but it doesn't have HA from what I can tell [github issue](https://github.com/huginn/huginn/issues/2198)  \n\n### Other fun facts\n* Supports Hashicorp vault for storing secrets/settings/etc  \n* Can enable global message encryption so that all messages going through RMQ are encrypted with aes-256-cbc  \n* Each worker generates a private/public key that can be used for internode communication, it also will generate a cluster secret  \nfor all nodes to have so they can share data accross the entire cluster. The cluster secret by default is stored only in memory and\nand is generated when the first worker starts\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foptum%2Flegionio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foptum%2Flegionio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foptum%2Flegionio/lists"}