update readme documentation.

README.md

@@ -2,96 +2,84 @@
 
 ## About
 
-A group of friends play various games like 7 Days to Die and VRising which require one of us to host a server
-at our home.  We do this as opposed to paying for online hosting because this is a free options.  Often it's a hassle 
-to update a server or handle restarts of a server that might have gone down.  We have often mused over a tool that can 
-handle this workload for us or at least make it easier.  Also, a tool that doesn't require one of us to expose a home 
-server to the open internet or have to require one of us to setup a home VPN. I have not found a very good solution 
-that exists already so this tool might fill that vacuum.   
-
-I am creating a solution that is a sort of two-part solution.  The first part will be what runs on someone's local machine and has the
-ability to install game servers available via steam, start/stop servers, and do other similar tasks.  There will also be a 
-client and a minimal graphical user interface in the form of a system tray application.  The client and the agent, 
-shall be able to communicate securely when performed outside of one's local network so not just anyone can interact with the agent.  
-
-Part one (this repository) is a web api that executes commands on a machine, an agent.  The agent is supposed to be "dumb" 
-in the sense that it can perform tasks, but it's only a puppet and cannot think for itself.  At a minimum, giving this 
-part of the solution out allows a pair of friends to keep a game server running.  One person installs the agent at home, 
-set ups the game server, and gives the other friend located elsewhere the client.  The second friend gets to remotely 
-start/stop the server with the client, if needed.  Anyone, so inclined, can build additional automation around this 
-part of the solution, if desired.   
-
-For Part Two (future work), I intend to make collaborative web application where my friends and I can control our servers 
-via a web browser interface, and have other additional capabilities.  One day, perhaps, I'll also make that available to others.  
-
-## A word about licensing
-
-Out of all my mates, I write software for fun and this is a personal project. Help is always welcome.  If you get use
-out of this tool and with to contribute back, please do.  You're welcome to use this software personally however you like.  
-However, I'm licensing with GPL v3, and that means if you take this work and distribute it for personal gain, then you are
-lawfully required to make available all of your software. That include changes to this code base plus your own work.  There
-is also an obligation to provide a reference to this codebase and its [license](./LICENSE).  My motivation to do this stems from the
-idea that I truly wish this tool to be a community tool.  Even if I wind up building something that goes on to make me money,
-on some level I want it to be free to use for anyone with the skill, time and desire.  Also, I may also want my name on 
-an open source tool that I created. Makes for good resume material! 
+Agent Smith is a self-contained System Tray Application software with Flask Server backend housing
+an API, written in Python.  The GUI built with PyQT and uses the [Operator](https://github.com/agentsofthesystem/operator)
+client to communicate with the server.
+
+
+### Features
+
+Some of Agent Smith's core features are:
+
+1. Installation of Supported Game Servers.
+2. Ability to Start/Stop/Restarted Game Servers.
+3. Provide API Access to external users via API.
+4. Security with NGINX/SSL/HTTPS & Token-Based Access controls.
+
+### Supported Games
+
+Here's a short list of some games Agent Smith is currently programmed to manage.
+
+1. 7 Days To Die
+2. V-Rising
+3. More to come!!!
 
 # Getting Started
 
-I've written instructions for every day use of this software as well as what a developer might need 
+I've written instructions for every day use of this software as well as what a developer might need
 [here](./docs/getting-started.md).
 
+# Security
+
+Opening a port to expose Agent Smith's API to the outside world can be a little scary, so I've
+written a whole [section on it](./docs/security.md).  The author takes security very seriously, and
+wants you to be informed about the risks and what's been done to make this software as safe as
+possible.
+
 # Future Work
 
-I have identified work I intend to do for the future and could use help with in the "Future Work" section.  Please create
-an issue for ideas.  I also wanted to share, what I don't intend to do as well so that is also clear.
+I have identified work I intend to do for the future and could use help with in the "Future Work"
+section.  Please create an issue for ideas.  I also wanted to share, what I don't intend to do as
+well so that is also clear, please see the "Author's areas of dis-interest" section for that.
 
-There will always be room for improvements, but here are some goals the author has to improve behavior and usability
-overall:
+There will always be room for improvements, but here are some high level goals the author has to
+improve behavior and usability overall:
 
 1. Get unit test framework to minimal code coverage; 20%.
-2. Add github actions.
-3. Improve the usage instructions.
-4. Create a simple public facing Git Hub project board. 
-5. Come up with a more permanent name. 
-6. Split the client into its own repository / python package. 
-7. Implement authentication mechanism for client to use.
-8. Implement pyinstaller so that a function EXE file can be deployed/published for releases. 
-9. Cross-platform support - I'd like to be able to support Linux Game Servers as well :)
+2. Cross-platform support - I'd like to be able to support Linux Distributions as well.
+3. Support steam game versions; eg install latest_experiemental or a specific release.
 
 # Limitations
 
 The software has some limitations that users ought to be aware of.
 
-1. The steamcmd client that downloads a game server (based on its steam_id) does so as an anonymous user.  If it 
-   doesn't download publically, it's not supported very well.  The package I used addresses this but I haven't paid 
+1. The steamcmd client that downloads a game server (based on its steam_id) does so as an anonymous user.  If it
+   doesn't download publically, it's not supported very well.  The package I used addresses this but I haven't paid
    much attention to it. If your needs require authentication, be prepared for some issues.
-2. Windows firewall:  This software cannot click the button that says "Allow this app through the firewall".  
+2. Windows firewall:  This software cannot click the button that says "Allow this app through the firewall".
 3. Port Forwarding: This software cannot set up port forwarding rules on any network hardware
-4. Linux: To start, the agent software is intended to operate on Windows.  However, the client can run on windows or 
-   linux. 
+4. Linux: To start, the agent software is intended to operate on Windows.  However, the client can run on windows or
+   linux.
 
 # Author's areas of dis-interest
 
 In this section, the author is attempting to describe what he personally is not interested in working.
 
 1. I want to add the games that I want to manage into the software.  I tried to go for an interface that is genearlized
-   so I didn't have to build the software this way, but each game has unique start up and shutdown needs.  Therefore,
-   if you as a user want a game added.  Be prepared to contribute!  
-2. The Graphical User Interface - To be honest, I'm not a GUI person.  It's not a pretty GUI but it gets the job done. 
-   I'm not going to personally work issues to enhance the GUI, but I'm not opposed to making it better.  If someone
-   wants to make it better go for it!  
-3. Supporting new features so you can use this for personal gain. Again, If you do this, you must share the code back
-   for the community, but I'm not going to be helping.  
-
-# References
+   so I didn't have to build customizations for each game server.  Therefore, if you as a user want a game added.
+   Be prepared to contribute!
+2. The Graphical User Interface: To be honest, I'm not a GUI person.  It's not a pretty GUI but it gets the job done.
+   I will help with bug-related issues, I'm not going to personally work issues to enhance the GUI unless I feel
+   strongly about it.  I'm not opposed to making it better.  If someone wants to make it better go for it!
+3. Supporting new features so you can use this for personal gain. Again, if you do this, you must share the code back
+   for the community, but I'm not going to be helping.
+4. Building any support to upload and run generic executables via API. That is a **HUGE** security risk
+   I don't want this software to put on any user.
+
+# References / Acknowledgements
 
 1. For packaging up and making an installer in the future - https://pyinstaller.org/en/stable/index.html
 2. SteamCMD Documentation - https://developer.valvesoftware.com/wiki/SteamCMD
-
-# Acknowledgements
-
-I'm a big fan of not reinventing the wheel, and I did use some python packages that came from others.  In general,
-have a look at ./requirements.txt for software I reused.
-
-1. I found pythonsteamcmd here - https://github.com/f0rkz/pysteamcmd and it was helpful so I did not have to rebuild
-   an interface to steamcmd. 
+3. All other dependencies, have a look at [requirements.txt](./requirements.txt).
+4. I found pythonsteamcmd here - https://github.com/f0rkz/pysteamcmd and it was helpful so I did not
+   have to rebuild an interface to steamcmd.

docs/developer-add-game-server.md

@@ -0,0 +1,3 @@
+# Adding a Game Server
+
+TODO - Add this section.

docs/developer.md

@@ -3,6 +3,12 @@
 
 The following are instructions for developers.
 
+## The obvious...
+
+Why oh why did you pick windows!?!? - Well... the author wanted to target windows first because, in truth,
+most people using this tool are likely to be gaming on a windows machine.  The author has tons of linux
+experience and recognizes that Linux/Dockerized platforms are entirely relevant and in the future.
+
 ## Pre-requisites
 
 This software was developed on Windows 10. The chosen software language is Python 3, which can be installed
@@ -23,12 +29,17 @@ feel free to figure out what's different and make a change yourself ;).
 The [Gitflow Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow)
 is used and is enforced.
 
-## Development Environment Setup
+All features get stacked up in the develop branch and then, after testing, released to the main branch.
+GitHub Actions automate DevOps Continuous Integration checks along the way.  On the main branch, however,
+a packaged release of Agent Smith is generated and attached to the release section.
+
+## Development Environment Preparation
 
-### Ubuntu Linux
+### Ubuntu/Debian Based Linux
 
 Please note that development on linux is experimental for now.  In the future, it will be supported
-but not until a later release.
+but not until a later release.  And when that time comes, Ubuntu/Debian will likely be the first
+distro supported.
 
 1. sudo apt update
 2. sudo apt install python3 python3-venv python3-pip lib32gcc-s1
@@ -47,6 +58,11 @@ NOTE:
 3. Open a powershell and test that one can run the "python" command to verify python is installed.
 4. install git for windows from here: https://git-scm.com/download/win
 
+## Docker
+
+The backend flask server could be containerized and the PyQT GUI could just simply communicate with
+a container, but this has yet to be developed.
+
 # Development Environment
 
 ## Stand Alone & Development
@@ -59,15 +75,16 @@ One must create a python virtual environment.  Therefore python3 must be present
    - windows:  .\venv\bin\Activate.ps1
 3. pip install -U pip
 4. pip install -r requirements.txt
-5. Run the backend server: python .\server.py
-6. Run the frontend GUI: python .\gui.py
-7. cd scripts
-8. python (your-script.py)
+5. pip install -r test-requirements.txt
+6. Run the backend server: python .\server.py
+7. Run the frontend GUI: python .\gui.py
 
 NOTE:
-   - There is another script (python .\launch.py), and that can be used to run both the backend server and the front
+   - There is another script (python .\agent-smith.py), and that can be used to run both the backend server and the front
      end GUI simultaneously.  Use this for final testing of features.
    - The backend server operates on port 5000, and the frontend GUI is built to use that port by default.
+     That port should never change. Nginx is used to expose ports and that's where changes are made to
+     port numbers.
 
 **Warning**: If one is using a windows only environment, the second step where the python virtual environment is activated
 may require a windows policy to be enabled which allows powershell scripts to be run.  This is a windows security
@@ -80,15 +97,6 @@ This software uses the coverage and pytest python packages for a testing framewo
 and are split up by unit tests and functional tests.  Any unit test is a simple test of a singular function or independent
 object.  A functional test is
 
-# Secrets File
-
-Create a file called ".env" and inside of it the following secrets must be added.
-
-1. SECRET_KEY - This is the application secret.
-
-NOTE:
-   - This is only used for development.  In production this would be unused or implemented via alternative feature.
-
 # Software Development Process
 
 ## Documentation & Code Quality

docs/getting-started.md

@@ -1,24 +1,20 @@
 # Getting Started
 
-This document should contain everything a developer needs to know in order to develop and/or use this software.
+This document should contain everything a developer or user needs to know in order to utilzie this
+software.
 
 ## Usage
 
+TODO - Need to finish this section.
+
 The every day user of this software may find instructions [here](./usage.md).
 
 ## Development
 
-Development documentation can be found [here](./developer.md).
-
-## A word about security
+## Setting up an environment
 
-Flask is not a production server, ultimately.  The software does have tha ability to acept ssl certificates but how
-each user obtains one is an independent venture.  Some may chose to self genreate one while others may choose to use
-something else.  If communicating with this appication over HTTPS is a priority for you, then the author recommends that
-the reader place this application behind a reverse proxy, such as NGINX.  
+Development Environment setup documentation can be found [here](./developer.md).
 
-If one does use nginx, here is the windows version: https://nginx.org/en/docs/windows.html 
+## Adding a new supported game server
 
-Why do this? It's simple, the authentication token used in this application would be directly exposed over the open 
-internet over HTTP as opposed to securly with HTTPS.  One runs the risk of having someone else intercept that token and
-use it for alternative purposes.
+A description of the software pattern used to add another supported game server can be found [here](./developer-add-game-server.md).