The tool is meant for use by Virginia localities to help them decide which taxation strategy to use for solar generating facilities, either the new Revenue Share ordinance or the old M&T/Real Estate tax strategy. The tool allows users to create different analyses of solar projects of various electric capacities and land sizes. It provides a user a detailed analysis of the expected revenues of a solar project under both tax options as well as a total summary of the revenues for all projects under both tax options.
SolTax Web App: https://solar-tax-webapp.azurewebsites.net/
Any changes made to the master branch are automatically pushed into the live server on Azure. Make sure changes are working properly before pushing to the master branch. Commit changes to branches other than master branch then merge when appropriate. Make sure you commit changes frequently to save changes to GitHub.
Need Python 3 or later (Developed using Python 3.8.1)
Python Documentation: https://www.python.org/downloads/
Django is a Python web framework meant for rapid development. SolTax Web App was developed using Django 3.1.
Django Documentation: https://www.djangoproject.com/
Installing Django: https://docs.djangoproject.com/en/3.1/topics/install/#installing-official-release
Django Tutorial: https://docs.djangoproject.com/en/3.1/intro/tutorial01/
SolTax and its PostgreSQL database are hosted on Azure which is a cloud computing platform run by Microsoft. When commit changes are pushed onto the master branch, it is deployed directly to Azure. The PostgreSQL database can be viewed through the admin site or Navicat. For Navicat login information, contact Mary Beth Wetherell at meh4q@virginia.edu.
The admin site allows us to manually view all instances of any models created by users and allows us to change the parameter values if needed. For the live server there is already a superuser created with credentials. For admin site login information, contact Mary Beth Wetherell at meh4q@virginia.edu.
SolTax Web App Admin: https://solar-tax-webapp.azurewebsites.net/admin/
The local server needs a username and password to access admin site. You will need to create a superuser. To do this type _python manage.py createsuperuser_ into the command line while in the project directory and fill out the command line prompts. To access the local admin site, run the application using _python manage.py runserver_ , go to http://localhost:8000/admin or http://127.0.0.1:8000/admin and sign in with the credentials set when creating the superuser.
The tool uses a PostgreSQL database which holds information on localites and users. You will need access to the Azure database for development and testing. For Azure database credentials information, contact Mary Beth Wetherell at meh4q@virginia.edu.
PostgreSQL Download: https://www.postgresql.org/download/.
The folder holds the Django project. (Only urls.py and settings.py should be changed)
- settings.py - Defines all the Django settings needed for the project. If you install a new dependency, you may have to add it to INSTALLED_APPS.
- asgi.py - Spins up an instance of the application and uses the settings as defined in the settings.py file.
- wsgi.py - Spins up an instance of the application and uses the settings as defined in the settings.py file.
- urls.py - Defines the admin URL, URLs that authenticate users which are defined by Django, a URL that makes it possible to display a graph for each project analysis, and then any URL that is defined in the models app.
The SolTax tool is a Django application which follows the MVT framework. MVT framework stands for model-view-template. Models are effectively classes that you would find in Java, Python, or C++. Models require certain variables to be defined about them when instantiated. The views take in information from models and request data ("GET" or "POST" methods) and determine what to do with the information. They then pass information to a template. The template is the HTML that defines how to display the information received by the views, although it has a bit more functionality compared to straight HTML as you can pass variables in and use for loops.
- admin.py - Tells the admin site to include information about all the models in the project. The admin site allows us to view all data of the project.
- apps.py - Defines the app to be named models
- forms.py - Defines any forms that are used throughout the project. Most are tied to a model so they can create an instance of a model through a submission of a form.
- models.py - Defines the UserProfile, Locality, Simulation, and Calculation models. A UserProfile is tied to one Locality, and has many simulations. A Locality can be tied to any number of UserProfiles. A Simulation is only tied to one UserProfile and only has one Calculation model associated with it. A Calculation instance is tied to one Simulation instance. Feedback is a model that holds an email and a text field containing feedback or a question. It is not tied to any other model.
- revenue_calculations.py - Python file that has functions to calculate the revenue for projects based on the input parameters.
- urls.py - Defines the URLs that are valid for the web application and which view corresponds to the URL entered.
- views.py - Defines the different views needed for the web application. This is the business logic that is needed to get parameters from instances of models or forms and then transform the data if necessary to pass onto the HTML templates to display the web page correctly.
- templates - Folder contains the HTML template files that are used when a view calls for a template to display with the necessary parameters. base.html is a HTML file that contains code that is to be used as a base for the site so all pages have the same basic design. The registration sub-folder contains the templates that are used for the password reset functionality of the web application.
- static - Folder contains any images that are displayed on the site and the CSS and JS files used to further design the pages of the web application. Add any new images into this folder and continue to edit the CSS and JS files in this folder if needed.
- templatetags - The custom_tags.py file defines tags that can be used in the HTML templates to manipulate data if necessary from variables that are passed into the templates.
- feedback_sender.py - (Function has been phased out) File is used to send an email to the listed stakeholders at 3 PM each weekday, if someone submitted feedback through the web app. It pings the website 3 times an hour each weekday from 9 AM - 5 PM so it is constantly up in the time period.
- manage.py - Default Django file that boots the application up when called (Do not touch unless necessary)
- Pipfile & Pipfile.lock - Files are for the virtual environment and list all the dependencies of the project and the versions used.
- Procfile - File that gets the web application running. It runs python manage.py migrate to make any migrations necessary to the database. It then runs the application with the wsgi.py file and finally creates a cron job to run feedback_sender.py
- requirements.txt - File that lists all dependencies is to be used to automatically install all dependencies at once. Keep updated with any new dependencies that are added.
- .gitignore - File that tells Git to intentional ignore files that in this case contain sensitive information such as login creditionals which should not be pushed to the repository
-
Clone the SolTax repository and create a new branch for development
Working with Github in VS Code Tutorial: https://docs.djangoproject.com/en/3.1/intro/tutorial01/
-
In the command line, run
pip install -r requirements.txtto download the necessary packages -
Create .txt files containing the following names and respective contents under a new hiddenVars folder in the base directory. The file contains sensitive information that should not be shared. The contents may be found on Azure under Settings ➡️ Configuration ➡️ Application settings. Otherwise, contact Mary Beth Wetherell at meh4q@virginia.edu for sensitive information.
| Variable | Description |
|---|---|
| azure_host | URL of database |
| azure_name | Name of database |
| azure_password | Account Password to access database |
| azure_port | Port of database |
| azure_user | Account Username to access database |
| Email Username used for SolTax feedback | |
| email_password | Email Password used for SolTax feedback |
| secret_key | Key used to encrypt sensitive information |
-
Connect to UVA Anywhere VPN
-
In the command line, run
python manage.py runserver. Ensure that your command line is in the same directory as manage.py.- If the command is successful, SolTax should be running on your local server at https://localhost8000 or http://127.0.0.1:8000.
- Otherwise, address the runtime error as needed and run the command again. For additional help, see Debugging Tips.
-
Make the additional needed changes to SolTax while running the server perodically to ensure the changes made are successful
-
When all needed changes have been made and the local server runs successfully, push all your changes to the dev branch. If using Git, in the command line, run
git add file_nameto add the file(s) that have been changed. Next, in the command line, rungit commit 'commit_name'to name your commit and runpush origin -u devto push your changes to the dev branch. -
The dev branch deploys to a SolTax Developer web app which includes the preloaded configurations used by SolTax to test your changes on the Azure server. If changes are needed for the preloaded configurations, contact Mary Beth Wetherell at meh4q@virginia.edu for access. Changes pushed to the dev branch will automatically be deployed to the developer web app and can be tracked in the Actions tab on Github.
SolTax Developer Web App: https://solar-tax-webapp-dev.azurewebsites.net
-
After checking to ensure the developer Azure site is successful, merge your branch with the master branch to update the SolTax web app. Otherwise, if the deployment failed or the server failed to load, address the error as needed, push the changes to your branch, and redeploy the code. For additional help, see Debugging Tips.
- Deprecated packages are outdated past their newest version and should be updated as it may pose both a security risk and result in runtime errors. The runtime error displayed will likely point to the packages that are needing to be updated.
- Updating deprecated packages may require changing
importstatements, adding new lines of code in accordance with the documentation of the newest iteration often made in settings.py, or changing the version in requirements.txt as indicated after the==.
- As packages are updated, this often results in runtime errors as packages often call on each other and therefore rely on certain versions of a particular package. Therefore, requirement.txt must outline packages that include the correct version of each package's dependencies in order to be successfully deployed.The runtime error displayed will likely outline the package's missing dependencies and their necessary versions.
- Changing package dependencies is a process of repeated trial and error, involving deprecating as needed after the
==or changing the order of packages in requirement.txt to be successful. While the packages may run successfully on your computer, there will likely be errors when deploying on Azure as their operating systems differ.
- The error can be found by checking the deployment logs and clicking on the commit ID that was deployed or on the repoistory under actions in the respective workflow.
- As your computer's operating system likely differs from Azure, the error is likely from the result of a failure in Package Dependencies.
- If package dependencies cannot be reconciled, a potential solution is to dockerize the web app by placing it with your computer's operation system but the current iteration of the web app is not dockerized.
- If the developer web app or local server displays an error, additional information can be found by setting
DEBUG = TRUEin settings.py but must set back toDEBUG = FALSEbefore merging your branch with the master branch. - The error is likely the result of Deprecated Packages or updating the code as needed to with the newest iteration of Django.