diff --git a/readme.MD b/readme.MD index 203711777ba21bc5dd7f8b2b9e8231d36280d075..56dd883743d996c702cd5b5f4add0bfdeb7c7a46 100644 --- a/readme.MD +++ b/readme.MD @@ -1,113 +1,14 @@ -# Tor's Ticket Lobby - -## Table of Contents -1: General Information and Project Layout - -2: Getting Started: -- Notes on Packages -- Setting Up a Local Instance -- Notes on Virtual Environment - -3: Django In A Nutshell: -- Templates -- Models -- Views -- URLs -- Tests - -4: GitLab Python - -## 1.0: General Information and Project Layout, Including Quickstart Notes For Admins: - -Django applications or projects generally contain a main project folder -(in this case 'ticketlobby'), as well as several app folders, which can be -'turned on' and 'turned off' by their inclusion in the main project folder's -settings.py file. - -This project has been structured in such a way to maximize the potential -for later development and expansion. It is currently divided into three -main folders: - -1. ***/TicketLobby***: This is main project folder, in which the settings.py file -and other base Django files are found. - -2. ***/AnonTicket***: This is the folder for the AnonTicket app. - -3. ***/Shared***: This is a pseudo-app, primarily for static files and -templates likely to be expanded or utilized in other parts of the project. - -### Adding Projects - -Once an admin has created a superuser, adding a project to the database -is extremely simple, in that it requires only one piece of information-- -the gitlab id number of the project (available on the project's gitlab -page. (From the admin panel, click "projects" - > "create" - > and type in the -gitlab id number. Hit save.) - -Django will then create a gitlab object instance and fetch all the project's -details for the database entry and save them. It will also check the GLGroup's to -see if a matching gitlab group already exists in the database; if it does -not, it will fetch the group's information from gitlab, create the group, and -assign the project to the relevant gitlab group. - -## 2.0 Getting Started: -### Notes on Packages: - -The packages in the requirements.txt file are necessary for the ticketlobby -to function (see below for installation instructions, or 'packages' below -for more information on specific packages.) - -Environment variables are tracked using the python-decouple package, which -increases security by moving important keys, tokens, etc. to the .env -file located in the base folder. If you're unable to perform -manage.py runserver, make sure you have set something in the SECRET_KEY -field in the .env file, and that DEBUG is set to "True". If DEBUG is -set to "False", you will need to make sure something is filled in for -the allowed hosts field. - -### Notes on Moderators Group: - -Once the project has been installed and migrations applied, it is -recommended to run create_groups for ease of admin administration. - -/anonticket/management/commands has a file in it, "create_groups.py", -which will automatically create two groups, "Moderators" and "Account -Approvers", when run from the command line with: - -$ python manage.py create_groups - -The "Moderators" will automatically have the following permissions assigned: -- View User Identifier -- View Git Lab Group -- View Project -- Add/Delete/Change/View Issue -- Add/Delete/Change/View Note - -The "Acount Approvers" will automatically have the following permissions assigned: -- View User Identifier -- Add/Delete/Change/View Gitlab Account Request - -Once create_groups.py is run, users can be created by a super_user via -the admin panel. make sure to: -1. Assign "staff" status to moderators and account approvers so that -they are able to login. -2. Assign the group "Moderators" to users that will be editing notes -and issues. -3. Assign the group "Account Approvers" to users that will be approving -Gitlab Account Requests (this functionality has not yet been added to the -portal but should be coming at a future date.) -4. Note: Users can be in more than one group. - -If, in the future, you wish to update the permissions for the group, you -can do so via the admin panel, but it's recommended to update the file -in anonticket/management/commands/create_groups.py instead, as this -will ensure consistency at a later date. - -### To run it locally - -You need to start by setting the `SECRET_KEY` variable in the .env file. - -Then run the following commands: +# Anon-Ticket: Anonymous Gitlab Reporting for Tor + +A web application that allows web users to create +anonymous tickets on the Tor Browser's Gitlab instance by leveraging +the GitLab API (Python-Gitlab package.)
+
+*** +## 1.0 Quickstart: +Clone the repo. Rename the env_sample.txt file to just “.env”. Open it +and delete first line that says "delete me", then set the SECRET_KEY to a string of +your choosing. Run the following commands: ``` 1. Make a virtual environment: @@ -122,73 +23,164 @@ Then run the following commands: $ python manage.py migrate 6. You can check or launch by using the "runserver command." $ python manage.py runserver -7. Create the superuser +7. Create a superuser $ python manage.py createsuperuser - (follow the prompts): + (follow the prompts) 8. Create groups "Moderators" and "Account Approvers"(see explanation above): $ python manage.py create_groups 9. Add gitlab tokens and other variables in the .env file. - ``` - When `runserver` is running, you should be able to point your browser to - and reach the local version of the application. + and reach the local version of the application.
+
+*** +## Table of Contents: + +1. Quickstart (above) +2. Notes for Admins + - 2.1 Fast Project Add From Gitlab + - 2.2 Programmatic Groups and Permissions + - 2.3 Adding Moderators and Account Approvers +3. Project Structure and Function: + - 3.1 Folder Layout + - 3.2 Anon-Ticket Request-Response in a Nutshell + - 3.3 Models + - 3.4 Views + - 3.5 URL Pathing + - 3.6 Templates +4. Packages +5. Tests + +*** + +## 2.0 Notes for Admins + +*** + +### 2.1 Fast Project Add from GitLab +In order to use Anon-Ticket to receive issues, notes, and gitlab account +requests, a project has to be first be added to the database by a +superuser via the admin panel. The only piece of information needed to +do this is the ***project’s Gitlab ID number***, available on that +project’s gitlab page. Once the number is filled in and the project is +saved, Anon-Ticket will ***automatically fetch*** all necessary project +information from the GitLab API, including the group, title, description, +web_urls, etc. + +Anon-Ticket will also check the GitLabGroup objects to see if a +matching group already exists in the database; if not, Anon-Ticket will +***automatically create*** the GitlabGroup object, including fetching +the information from Gitlab, creating the group, and assigning the +project to the relevant group. +
+ +### 2.2 Programmatic Groups and Permissions: + +Once the project has been installed and migrations applied, Moderator +and Account Approvers can be created from the command line: +$ python manage.py create_groups -### Notes on the virtual environment +Anon-Ticket will automatically create two groups, "Moderators" and +"Account Approvers", and assign the permissions defined in the dictionaries +in /anonticket/management/commands/create_groups.py. These permissions +can be changed by changing this file. These Group names are important; +they are used during the authentication process for Moderator and +Account-Approver specific views. -Make sure you're inside of your virtual environment when you're making -any changes! You'll know it's on, because (myvenv) will be at the -beginning of the command line. If you ever type: - $ python manage.py runserver +The "Moderators" will automatically have the following permissions assigned: +- View User Identifier +- View Git Lab Group +- View Project +- Add/Delete/Change/View Issue +- Add/Delete/Change/View Note -and you see something like: +The "Account Approvers" will automatically have the following permissions assigned: +- View User Identifier +- Add/Delete/Change/View Gitlab Account Request -> Command 'python' not found, did you mean: -> command 'python3' from deb python3 +If, in the future, you wish to update the permissions for the group, you +can do so via the admin panel, but it's recommended to update the file +in anonticket/management/commands/create_groups.py and then rerun +“python manage.py create_groups” instead, as this will ensure +consistency at a later date. All users assigned to a group will have +their permissions updated. + +### 2.3 Adding Moderators and Account Approvers (Users): + +1. Create the user in the admin panel - only username and email are +necessary. +2. Assign "staff" status; without "staff", the user will not be able to +log into the system to perform moderation tasks. +3. Assign the group "Moderators" to users that will be editing notes +and issues. +4. Assign the group "Account Approvers" to users that will be approving +Gitlab Account Requests (this functionality has not yet been added to +Anon-Ticket, but should be coming at a future date.) +5. Note: Users can be in more than one group. -then you may have accidentally turned your viritual environment off! +
-If you want to ever exit your virtual environment, just type - $ deactivate. +*** ---- -## 3.0 Django (and this project) in A Nutshell: +## 3.0 Project Structure and Function -When a user navigates to an URL associated with this project, Django matches the -URL to the appropriate pattern in urls.py. It strips any needed arguments from the URL based on -the logic in urls.py, and, based on urls.py, determines which VIEW to use. The -view itself may contain logic, including what to do with any arguments from the URL, how -to handle forms, GET vs POST requests, when to communicate with the database, etc. +*** -Once those steps are carried out, the view generally instructs Django to initiate a redirect -to another view, or to render an html page using one or more html TEMPLATES. Arguments for -rendering the html template are usually passed to the template as a dictionary (associative array), -and can be called by the template (e.g., if the dictionary is passed as {results}, {{results.user_identifier}} -is equivalent to results['user_identifier'].) Context dictionaries can contain strings, lists, or -other dictionaries, but a Mixin has been created (PassUserIdentifierMixin) that has been -used to create all of the class based views. This Mixin will automatically pass -the user_identifier from the url argument to a context dictionary called "results" -to minimize code duplication when repurposing templates across function and class -based views. +### 3.1 Folder Structure: +Django applications or projects generally contain a main project folder +(in this case 'ticketlobby'), as well as several app folders. Apps can +be turned “on” or “off” by changing the allowed_apps setting in +/ticketlobby/settings.py. -### Templates +This project has been structured in such a way to maximize the potential +for later development and expansion. It is currently divided into three +main folders: -Templates specific to the anonticket portion of this project are in anonticket/templates/anonticket. -The repetition of anonticket above is Django's recommend method for namespacing; as Django will -search for templates within *any* app folder called 'templates', this name-spacing prevents confusion. +1. ***/TicketLobby***: The main project folder, in which most +configuration files are found. -Additionally, there is a folder called 'templates' in 'shared'; here, 'shared' is -a pseudo-app that contains files that will be used across various apps in this project. The -overall layout template, including side-bar menu, is here, as well as the css files, fonts, -and other static files (like images.) The CSS is based on Tor Project's style-guide -(styleguide.torproject.com), which uses bootstrap templates for layout. +2. ***/AnonTicket***: The folder for the AnonTicket app. + +3. ***/Shared***: This is a pseudo-app, primarily for static files and +templates likely to be expanded or utilized in other parts of the project. -### Models +### 3.2 Anon-Ticket Request-Response in a Nutshell + +When a user navigates to an URL associated with this project, +Django matches the URL to the appropriate pattern in urls.py. It strips +any needed arguments from the URL based on the logic in urls.py, and, +based on urls.py, determines which VIEW to use. The view itself may +contain logic, including what to do with any arguments from the URL, how +to handle forms, GET vs POST requests, when to communicate with the database, etc. + +Once those steps are carried out, the view generally instructs Django to +return a redirect to another view, or to render an html page using one +or more html TEMPLATES. Arguments for rendering the html template are +usually passed to the template context as a dictionary (associative array), +and can be called by the template (e.g., if the dictionary is passed as +{results}, a {{results.user_identifier}} call in the template is equivalent to +results['user_identifier'].) Context dictionaries can contain strings, lists, or +other dictionaries. + +In order to increase privacy for end users, who may wish to be anonymous, +users do not authenticate via a standard username/password cookie method. +Instead, once a User Identifier code-phrase is created, it is passed +to views via an arg/kwarg from the URL path, e.g., , +into a dictionary called "results". In order to create consistency between +class based views (CBV's) and function-based views (FBV's), both of which +are utilized in this project, a Mixin has been created called +PassUserIdentifierMixin, which passed the user_identifier kwarg (if it +exists) from the URL to the CBV's context dictionary inside of another +dictionary called "results". This minimzes code duplication across +views and allows developers to repurpose the same template for CBVs and +FBVs. + +### 3.3 Models The models for database objects are in anonticket/models.py. -### Views +### 3.4 Views The 'engine' that drives this project is primarily contained in anonticket/views.py. At current, this project uses a mixture of class-based views and function-based views. @@ -202,7 +194,7 @@ wraps the view in a function that determines if the user_identifier codephrase i URL path meets validation requirements; if not, it redirects the user to an invalid user_identifier view. -### URL-Pathing +### 3.5 URL-Pathing The main URL structures at this time are located in anonticket/urls.py (and all of these URLs are included in the main URLS.py located at ticketlobby/urls.py) Values that @@ -213,7 +205,61 @@ User Identifier code-phrases are not saved to the database until they have been to perform an action, such as create a ticket. As such, there are validation functions in the views which take arguments from the URL as noted above. -### Tests +### 3.6 Templates + +Templates specific to the anonticket portion of this project are in anonticket/templates/anonticket. +The repetition of anonticket above is Django's recommend method for namespacing; as Django will +search for templates within *any* app folder called 'templates', this name-spacing prevents confusion. + +Additionally, there is a folder called 'templates' in 'shared'; here, 'shared' is +a pseudo-app that contains files that will be used across various apps in this project. The +overall layout template, including side-bar menu, is here, as well as the css files, fonts, +and other static files (like images.) The CSS is based on Tor Project's style-guide +(styleguide.torproject.com), which uses bootstrap templates for layout. + +## 4.0 Packages + +### Notes on Packages: + +The packages in the requirements.txt file are necessary for the ticketlobby +to function. + +Environment variables are tracked using the python-decouple package, which +increases security by moving important keys, tokens, etc. to the .env +file located in the base folder. If you're unable to perform +manage.py runserver, make sure you have set something in the SECRET_KEY +field in the .env file, and that DEBUG is set to "True". If DEBUG is +set to "False", you will need to make sure something is filled in for +the ALLOWED_HOSTS field. + +### Python-Gitlab + +The anonticket app uses the Python-Gitlab package to communicate with +the GitLab API. + +Some sample reference files to demonstrate dictionaries returned by +get queries, including pretty-printed issue and note dictionaries, +are available in shared/reference_files. + +### Django-Markdownify + +Python-Django package that allows you to use a 'markdownify' filter +to render markdown as html, including safe functions. Automatically +installs Markdown and Bleach dependencies. + +To run, markdownify is added as an app in ticketlobby/settings.py +(and can be disabled by removing that line.) + +To load into a template, use the {% loadmarkdownify %} template tag. +Add '|markdownify|' as a filter where you want markdown rendered as +html. + +Documentation here: https://django-markdownify.readthedocs.io/en/latest/index.html + +### Python-Coverage +(See "Tests", below.) + +### 5.0 Tests Tests currently live in the tests.py files that are automatically set up when the apps are created (e.g., the anonticket folder has a tests.py file @@ -256,28 +302,5 @@ $ coverage html This creates a folder called htmlcov. Open up htmlcov/index.html and you'll see an easier to parse version of the report. -## Packages -### Python-Gitlab -The anonticket app uses the Python-Gitlab package to communicate with -the GitLab API. - -Some sample reference files to demonstrate dictionaries returned by -get queries, including pretty-printed issue and note dictionaries, -are available in shared/reference_files. - -### Django-Markdownify - -Python-Django package that allows you to use a 'markdownify' filter -to render markdown as html, including safe functions. Automatically -installs Markdown and Bleach dependencies. - -To run, markdownify is added as an app in ticketlobby/settings.py -(and can be disabled by removing that line.) - -To load into a template, use the {% loadmarkdownify %} template tag. -Add '|markdownify|' as a filter where you want markdown rendered as -html. - -Documentation here: https://django-markdownify.readthedocs.io/en/latest/index.html