From 8b1e11c1e3c972eabd1b4152c1029c89572bc7d8 Mon Sep 17 00:00:00 2001 From: Tudor Stanciu Date: Sat, 6 May 2023 02:32:34 +0300 Subject: [PATCH] readme update --- README.md | 101 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 59 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 0c83cde..a457095 100644 --- a/README.md +++ b/README.md @@ -1,70 +1,87 @@ -# Getting Started with Create React App +# Network resurrector -This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app). +Everything must be able to be managed remotely. Even the powered off servers. That's how Network resurrector appeared, the tool I wrote specifically to be able to wake up my machines that I don't need to be powered on all the time. -## Available Scripts +Network Resurrector is a system that comprises of five essential services which allow for the execution of its core functionality. To enable various additional features, such as the notification mechanism, supplementary components may be added to the system as an option. -In the project directory, you can run: +## Main components -### `npm start` +### Frontend -Runs the app in the development mode.\ -Open [http://localhost:3000](http://localhost:3000) to view it in the browser. +- The [frontend](https://lab.code-rove.com/gitea/tudor.stanciu/network-resurrector-frontend) component is a web application written in React JS that has the role of providing the user with a friendly visual interface through which to interact with the system. -The page will reload if you make edits.\ -You will also see any lint errors in the console. +### API -### `npm test` +- The API component is a .NET 6 REST API that has the role of mediating the exchange of data and commands between the frontend component and the database or server component. -Launches the test runner in the interactive watch mode.\ -See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information. +### Server -### `npm run build` +- The server component is a .NET 6 service specialized in executing 'WakeOnLAN', 'Ping' and 'Shutdown' actions for the machines in its network. -Builds the app for production to the `build` folder.\ -It correctly bundles React in production mode and optimizes the build for the best performance. +### Agent -The build is minified and the filenames include the hashes.\ -Your app is ready to be deployed! +- The agent is a .NET 6 service specialized in executing 'Shutdown', 'Restart', 'Sleep', 'Logout' and 'Lock' actions on the host machine on which it is installed. Each action can be executed at the time of launch or with a certain delay. If an action is requested with a delay and later the user changes his mind, he can cancel the action by executing the separate 'Cancel' type action. +- The need for the agent appeared after I realized that the server cannot perform any action on a machine, being outside of it. +- The agent solves this problem because it is installed directly on the targeted machine. Later, the API component can delegate the resolution of an action directly to the agent. +- Most of the time, the execution flow of an action is realized in the following way: + - The user initiates an action, such as starting or stopping a machine, by pressing the corresponding button in the user interface. + - The frontend component sends the command to the API. + - The API checks who is configured as performer for the respective action for the machine and sends the command to it. + - The performer of the action (Agent or Server) executes the command and responds on the flow with status. + - In most cases, the Server component handles the machine startup action while the Agent component manages the machine shutdown action. +- As is probably already obvious, the agent can be installed on as many machines as desired. -See the section about [deployment](https://facebook.github.io/create-react-app/docs/deployment) for more information. +### Tuitio -### `npm run eject` +- [Tuitio](https://lab.code-rove.com/gitea/tudor.stanciu/tuitio) is my personal identity server. It manages user authentication within the application and authorizes requests made by it. Further information about [Tuitio](https://lab.code-rove.com/gitea/tudor.stanciu/tuitio/src/branch/master/README.md) can be found on its dedicated page. -**Note: this is a one-way operation. Once you `eject`, you can’t go back!** +All communication between the five main components is done exclusively through HTTP. -If you aren’t satisfied with the build tool and configuration choices, you can `eject` at any time. This command will remove the single build dependency from your project. +## Secondary components -Instead, it will copy all the configuration files and the transitive dependencies (webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except `eject` will still work, but they will point to the copied scripts so you can tweak them. At this point you’re on your own. +- NATS Streaming - Used to publish notifications about executed actions. +- Correo - Used to send by email the notifications generated by the system. +- Seq - Used to collect and view system logs. -You don’t have to ever use `eject`. The curated feature set is suitable for small and middle deployments, and you shouldn’t feel obligated to use this feature. However we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it. +## Notification system -## Learn More +The notification system is focused on system actions (Wake, Shutdown, etc), and the configuration of notifications is done in structures of the following form: -You can learn more in the [Create React App documentation](https://facebook.github.io/create-react-app/docs/getting-started). +``` +{ + "To": [ "user@homelab.com" ], + "Subject": "Network resurrector: Machine {MACHINE_NAME} has been waked. Status: {ACTION_STATUS}", + "Body": "Hello,{NEWLINE:2}Network resurrector processed a command to start machine {MACHINE_FULLNAME} with IP {MACHINE_IP} at {SYSTEM_DATETIME}.{NEWLINE}The performer who was delegated for this action was {ACTION_PERFORMER}.{NEWLINE}Action status: {ACTION_STATUS}{NEWLINE:2}Have a nice day,{NEWLINE}Network resurrector notification system." +} +``` -To learn React, check out the [React documentation](https://reactjs.org/). +The texts can be written at the user's free choice, and the following placeholders can be used in their composition: `{MACHINE_NAME}`, `{MACHINE_FULLNAME}`, `{MACHINE_IP}`, `{ACTION_STATUS}`, `{ACTION_PERFORMER}`, `{SYSTEM_DATETIME}`, `{ERROR_MESSGE}`, `{NEWLINE}`, `{NEWLINE:2}` -### Code Splitting +`{NEWLINE:x}` is a dynamic placeholder. Any number can be written in place of the 'x' character and the notification system will add that many new lines. -This section has moved here: [https://facebook.github.io/create-react-app/docs/code-splitting](https://facebook.github.io/create-react-app/docs/code-splitting) +## Database -### Analyzing the Bundle Size +Currently, the database server supported by the system is only Microsoft SQL Server. In the following versions, the system will also be compatible with PostgreSQL and SQLite. -This section has moved here: [https://facebook.github.io/create-react-app/docs/analyzing-the-bundle-size](https://facebook.github.io/create-react-app/docs/analyzing-the-bundle-size) +## Logging -### Making a Progressive Web App +The logging functionality is managed with Serilog, and its configuration is done in the `appsettings.json` file. In addition to its standard configuration, Network resurrector also has a preconfigured area where two destinations for logs are available: SqlServer database and Seq. Each of the destinations can be activated or not. If logging in the console is sufficient, all additional logging destinations can be disabled. +This configuration area is: -This section has moved here: [https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app](https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app) +``` +"Logs": { + "SqlServer": { + "Enabled": false, + "Connection": "Server=;Database=;User Id=;Password=;" + }, + "Seq": { + "Enabled": false, + "Url": "", + "ApiKey": "" + } +} +``` -### Advanced Configuration +## Hosting -This section has moved here: [https://facebook.github.io/create-react-app/docs/advanced-configuration](https://facebook.github.io/create-react-app/docs/advanced-configuration) - -### Deployment - -This section has moved here: [https://facebook.github.io/create-react-app/docs/deployment](https://facebook.github.io/create-react-app/docs/deployment) - -### `npm run build` fails to minify - -This section has moved here: [https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify](https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify) +All the components of the system are written in cross-platform technologies, so its host can be any environment.