diff --git a/README.md b/README.md index 91bc240fdeb8412715481c776782b26c07254a87..9bbe055fe0612b77fe0487720f4e5e61d7b64db2 100644 --- a/README.md +++ b/README.md @@ -1,183 +1,27 @@ -# Introduction -This is a flask application that leverages [RabbitMQ](https://www.rabbitmq.com/) and [Celery](https://docs.celeryproject.org/en/latest/getting-started/introduction.html) -to asynchronously create a Cheaha user account. Currently the project is being developed on an Openstack cluster. -# Project Setup - -To clone this repo use the command: -``` -$ git clone https://gitlab.rc.uab.edu/rc/account-app.git -$ cd account-app -``` -## Prerequisites -### Setup a Virtual Environment -- Ensure you have created a [virtual environment](https://docs.python.org/3/library/venv.html) -called `venv` setup running python3. - - Note, this project requires a virtual environment running __python3__ (__3.6.8__ in this case). - - Create this by navigating to you home directory via typing `$ cd` and entering the following commands:<br> - ``` - $ python3 -m venv ~/venv - $ source ~/venv - ``` - - Upon Activation, you should see the prompt update accordingly: - ``` - [centos@ood ~]$ <------Old Prompt - (venv) [centos@ood ~]$ <------New Prompt - ``` - In this case, the env name is displayed as `venv` but would change to reflect whatever name you initialized it with - in the previous step. Additionally, this example is running on the `ood node` provisioned - via __OpenStack__. -- Ensure [pip](https://docs.python.org/3/installing/index.html) is installed. - - #### Mac/Linux - - Check if installed by typing `$ pip` - - Install pip using `$ python -m pip install --user --upgrade pip`. - - #### Windows - - Check if installed using `$ py` - - Install pip using `$ py -m pip install --upgrade pip`<br><br> -- Ensure Flask and other dependencies are installed to you virtual environment using the following commands: -``` -$ cd ~/your/repo/path/account-app -$ pip install -r requirements.txt -``` -- Note, to install flask in your own `$HOME` use `pip install --user Flask`. -### Install RabbitMQ -(Reference: [here](https://www.rabbitmq.com/tutorials/tutorial-four-python.html)) -- Install RabbitMQ server on the host machine. ([Installation Guide](https://www.rabbitmq.com/download.html)) - - #### Mac/Linux - - `$ brew update` - - `$ brew install rabbitmq` - - it is recommended that you add the following line to your `.bash_profile`: - `export PATH=$PATH:/usr/local/opt/rabbitmq/sbin`. - - Start server using the command `$ rabbitmq-server`. (Note, this implementation assumes RabbitMQ is running on localhost on standard port 5672) - - #### Windows - - Download the installer from [here](https://github.com/rabbitmq/rabbitmq-server/releases) and run. - - Post install, the server should be running. To check, run `$ rabbitmqctl.bat status`. - - #### CentOS 7 - - First, import signing key using `$ rpm --import https://github.com/rabbitmq/signing-keys/releases/download/2.0/rabbitmq-release-signing-key.asc` - - Next, install Erlang using `$ yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm` - - Finally, install RabbitMq using `$ yum install rabbitmq-server-3.8.2-1.el8.noarch.rpm` - - The server is not started as a daemon by default when the RabbitMQ server package is installed. To start the - daemon by default when the system boots, as an administrator run: `$ chkconfig rabbitmq-server on`. - - As an administrator, start and stop the server as usual: <br/>`/sbin/service rabbitmq-server start` - <br/> `/sbin/service rabbitmq-server stop` - - Add the user "reggie" using the command `$ rabbitmqctl add_user reggie reggie`. - - The current configuration assumes the following username password combination. To change the password, type - `$ rabbitmqctl change_password reggie <new_password>`. - - Note that rabbitmqctl may require sudo permissions and that changing the password will require a password - change in the credentials within `test_producer.py` and `base_consumer.py` as well. - - -### Setup pre commit hook +# Introduction -- via Homebrew(Mac) +This is a flask application that leverages [RabbitMQ](https://www.rabbitmq.com/) and [Celery](https://docs.celeryproject.org/en/latest/getting-started/introduction.html) -```shell -brew install pre-commit -``` +to asynchronously create a Cheaha user account. Currently the project is being developed on an Openstack cluster. -- via pip +# Project Setup -```shell -pip install pre-commit -``` +Since this project is currently being developed only on an Openstack cluster all you will need to do to get started is to either create a new cluster referencing the steps [here](https://gitlab.rc.uab.edu/rc/cod-heat-stack) or work off of your existing one that will already have everything set up as part of the cluster creation through ansible. -After pre-commit is installed, run install in the repo directory: -```shell -$ pre-commit install -> pre-commit installed at .git/hooks/pre-commit -``` # Run Project -## 1. Connect to OHPC/OOD -1. Network Setup: <br> - Assuming proper steps have been run to provision your openstack cluster, your network - topology should look like the following:<br> -  - -2. Locate Floating Ip for each instance: <br> - <br> - According to this diagram of the network infrastructure, the IP Addresses that you will need to - connect to in order to ssh into each machine will be `164.111.161.xxx` where - `.xxx` is the last octet of your assigned Floating IP Addresses shown below.<br> - <br> - Note that these numbers will typically vary depending on factors in the provisioning - process. - -3. SSH into each machine: <br> - Now that you have the IP Addresses of the OHPC and OOD nodes, you can connect - to them via the following command in two separate shell windows/tabs: <br> - ``` - $ ssh centos@164.111.161.xxx - ``` - -4. Drop Firewall: <br> - Currently, the firewall prevents us from connecting to our soon to be running flask app. - To check if the firewall is active, type: <br> - `$ sudo systemctl status firewalld` <br> - In the case the firewall is still active, type: <br> - `$ sudo systemctl stop firewalld` <br> - In the case you need to turn the firewall back on, type: <br> - `sudo systemctl start firewalld` - -5. Edit Security Rules: <br> - Lastly, we want to make sure that our network it open to run on our flask application - which runs on `localhost:5000` by default. Modify your __Default__ security group to - reflect the following rules: <br> -  <br> - The main takeaway/modification in these rules is that traffic is allowed in and out of port 5000. - - -## 2. Initialize RabbitMQ -Make sure that you are running rabbitmq via the command `sudo rabbitmq server`. -## 3. Test RabbitMQ -For a simple example on the functionality of RabbitMQ, do the following: -- Open up a new ssh terminal and ssh into your ohpc node and, in a separate window, ssh into your ood node. -- Additionally, ensure you have a rabbitmq user configured with the username and password as `reggie`. - -``` -# Run consumer on ohpc node -$ python base_consumer.py ohpc -``` - You will notice that the script is awaiting a message to display. - To produce a message, run the following on the ood node terminal session: - ``` -$ python test_producer.py ohpc -``` +The project should already be running if your cluster deployment ran completely and correctly. You will need to edit your hosts file to point to the node you are wanting to work on if you haven't already done so in your cluster setup. -You should now see that the message has been sent and displayed on the ohpc node. +From here you can confirm that the account-app is working by navigating to yourname.rc.uab.edu/account-app. -## 4. Celery Worker -In order to execute our tasks asychronously, we create a celery worker using the fllowing: <br> -`$ celery -A tasks worker --loglevel=info --concurrency=4 1> ~/celery.out 2> ~/celery.err &` <br><br> -In this case, the `celery -A tasks worker --loglevel=info --concurrency=4` portion of the command -is what is initiating the worker and the remainder serves to write the stdout and stderr to two separate files -located in the home directory and to run the process in the background. <br> -## 5. Initialize the Flask App -Simply type `$ python run.py` <br> -Alternatively, type `$ python run.py > ~/flask.out 2> ~/flask.err &` to run the process in the background -and output to files in the home directory. +For an example of how the account-app/rabbitmq-agents workflow progresses please refer to this chart  +and this for information about the messages being sent  -## 6. Check Job status -If all goes well, you should have your processes running in the background. Check the status of these by typing -`$ jobs`. You should now see the something similar to the following: <br> -``` -(venv) [centos@ood account-app]$ jobs -[1]- Running celery -A tasks worker --loglevel=info --concurrency=4 > ~/celery.out 2> ~/celery.err & -[2]+ Running python run.py > ~/server.out 2> ~/server.err & -(venv) [centos@ood account-app]$ -``` +# Contribute to Project -## 7. Connect to Server -Open a new browser window and connect to the __OOD__ node by typing `http://164.111.161.xxx:5000` in the -address bar replacing `.xxx` with the final octet of the __OOD__ node. You should see something like this: <br> - <br> -## 8. Key Info/Observe -- Fill out the form and hit "Submit" -- You should see an overlay signifying the account is being created. After 5 seconds it should disappear and signify the account creation has been successful. -- You can now enter the command `kill %1 %2` to terminate the celery worker and the flask server. -- You can view the output/errors of either the worker and flask server by opening `flask.out`, `flask.err`, -`celery.out`, or `celery.err`. +To begin you will need to navigate to /var/www/ood/register/register/account \(this may change in the future when upstream projects are updated to allow custom repos/project names to be injected\) and checkout your branch. From here you will also need to run `git config --global user.name "Your Name"` and `git config --global user.email "you@example.com"` to make sure that your commits will be properly tracked. \ No newline at end of file diff --git a/docs/images/floating_ips.png b/docs/images/floating_ips.png deleted file mode 100644 index dc6c24604ffeb5e914075437d26babdf5b038d65..0000000000000000000000000000000000000000 Binary files a/docs/images/floating_ips.png and /dev/null differ diff --git a/docs/images/network_topology.png b/docs/images/network_topology.png deleted file mode 100644 index 192e173a0635c64f739ae2c9de801a4bf81d81c2..0000000000000000000000000000000000000000 Binary files a/docs/images/network_topology.png and /dev/null differ diff --git a/docs/images/rabbitmq-agents-flowchart.png b/docs/images/rabbitmq-agents-flowchart.png new file mode 100644 index 0000000000000000000000000000000000000000..64ebf741caeafd01aa0eabd72570810e8950cda2 Binary files /dev/null and b/docs/images/rabbitmq-agents-flowchart.png differ diff --git a/docs/images/rabbitmq-agents-messages.png b/docs/images/rabbitmq-agents-messages.png new file mode 100644 index 0000000000000000000000000000000000000000..e3a6709b50ba205f5757a844971e08adf5219ab1 Binary files /dev/null and b/docs/images/rabbitmq-agents-messages.png differ diff --git a/docs/images/rc-network .png b/docs/images/rc-network .png deleted file mode 100644 index 42e3244c98cc41516805f0bc39ac94f0acc274dd..0000000000000000000000000000000000000000 Binary files a/docs/images/rc-network .png and /dev/null differ diff --git a/docs/images/security_rules.png b/docs/images/security_rules.png deleted file mode 100644 index 0081fdf31891ff85aacbde479a855cc62370e3d5..0000000000000000000000000000000000000000 Binary files a/docs/images/security_rules.png and /dev/null differ diff --git a/docs/images/site_example.png b/docs/images/site_example.png deleted file mode 100644 index 116abb2b0c053c460a229c7c96b26d12313486bc..0000000000000000000000000000000000000000 Binary files a/docs/images/site_example.png and /dev/null differ