├── .github ├── ISSUE_TEMPLATE │ ├── bug_report.md │ └── feature_request.md └── PULL_REQUEST_TEMPLATE │ └── pull_request.md ├── .gitignore ├── CODE_OF_CONDUCT.md ├── LICENSE ├── Pipfile ├── Pipfile.lock ├── README.md ├── docs ├── .gitignore ├── Makefile └── source │ ├── _static │ ├── css │ │ └── custom.css │ ├── gif │ │ └── oauth.gif │ ├── github_banner.svg │ ├── licenses │ │ ├── gnu_fdl.png │ │ └── gnu_gplv3.png │ ├── maintainers │ │ ├── img_logo.png │ │ └── img_wordmark.png │ └── site │ │ ├── favicon.ico │ │ ├── op_card.png │ │ ├── op_logo.png │ │ └── op_wordmark.png │ ├── _templates │ └── layout.html │ ├── conf.py │ ├── credits.rst │ ├── environments │ ├── development.rst │ ├── index.rst │ └── production.rst │ ├── how_to │ ├── access_app_registry.rst │ ├── brand_omniport.rst │ ├── create_an_app.rst │ ├── examine_database.rst │ ├── index.rst │ ├── migrate_database.rst │ ├── monitor_health.rst │ ├── read_logs.rst │ ├── use_oauth2.rst │ └── write_logs.rst │ ├── index.rst │ ├── introduction │ ├── features.rst │ ├── index.rst │ ├── philosophy.rst │ └── the_stack.rst │ ├── legal │ ├── brand_usage_guide │ │ ├── index.rst │ │ ├── information_management_group.rst │ │ └── omniport.rst │ ├── developer_terms_of_use.rst │ ├── index.rst │ ├── open_source.rst │ └── privacy_policy.rst │ ├── references │ ├── config_files │ │ ├── app │ │ │ ├── config_json.rst │ │ │ ├── config_yml.rst │ │ │ └── index.rst │ │ ├── index.rst │ │ └── project │ │ │ ├── base_yml.rst │ │ │ ├── index.rst │ │ │ └── site_yml.rst │ ├── formula_one │ │ ├── components │ │ │ ├── app_footer.rst │ │ │ ├── app_header.rst │ │ │ ├── app_main.rst │ │ │ ├── custom_cropper.rst │ │ │ ├── default_dp.rst │ │ │ ├── index.rst │ │ │ ├── maintainer_view.rst │ │ │ ├── masonry_layout.rst │ │ │ ├── no_match.rst │ │ │ ├── non_maintainer_view.rst │ │ │ ├── tile_card.rst │ │ │ ├── tiles.rst │ │ │ └── user_card.rst │ │ ├── functions │ │ │ ├── app_details.rst │ │ │ ├── common_apps.rst │ │ │ ├── get_cookie.rst │ │ │ ├── get_theme.rst │ │ │ ├── get_theme_object.rst │ │ │ ├── if_role.rst │ │ │ └── index.rst │ │ ├── index.rst │ │ └── urls.rst │ ├── index.rst │ └── scripts │ │ ├── backend │ │ ├── clone │ │ │ ├── everything.rst │ │ │ ├── index.rst │ │ │ ├── services.rst │ │ │ └── shell.rst │ │ ├── create_app.rst │ │ ├── index.rst │ │ └── start_django.rst │ │ ├── docker │ │ ├── build │ │ │ ├── django.rst │ │ │ ├── index.rst │ │ │ ├── nginx.rst │ │ │ ├── postgres.rst │ │ │ ├── rabbitmq.rst │ │ │ └── react.rst │ │ ├── clone │ │ │ ├── backend.rst │ │ │ ├── everything.rst │ │ │ ├── frontend.rst │ │ │ └── index.rst │ │ ├── index.rst │ │ └── start │ │ │ ├── development.rst │ │ │ ├── index.rst │ │ │ └── logs.rst │ │ ├── frontend │ │ ├── build_frontend.rst │ │ ├── clone │ │ │ ├── everything.rst │ │ │ ├── formula_one.rst │ │ │ ├── index.rst │ │ │ └── services.rst │ │ ├── create_app.rst │ │ ├── index.rst │ │ └── start_react.rst │ │ └── index.rst │ ├── setting_up │ ├── development.rst │ ├── docker.rst │ ├── index.rst │ ├── omniport_docker.rst │ ├── omniport_docs.rst │ ├── production.rst │ └── server_configuration.rst │ └── structure │ ├── architecture.rst │ ├── folder_structure.rst │ ├── index.rst │ └── repositories.rst ├── readme-assets ├── maintainers │ └── wordmark.svg └── site │ └── wordmark.svg └── requirements.txt /.github/ISSUE_TEMPLATE/bug_report.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Bug report 3 | about: Create a report to help us improve 4 | title: '' 5 | --- 6 | 7 | **Describe the bug** 8 | A clear and concise description of what the bug is. 9 | 10 | **To Reproduce** 11 | Steps to reproduce the behavior: 12 | 13 | **Expected behavior** 14 | A clear and concise description of what you expected to happen. 15 | 16 | **Screenshots** 17 | If applicable, add screenshots to help explain your problem. 18 | 19 | **Operating System:** 20 | - OS: [e.g. iOS] 21 | - Browser [e.g. chrome, safari] 22 | - Version [e.g. 22] 23 | 24 | **Additional context** 25 | Add any other context about the problem here. 26 | 27 | **Want to take up?** 28 | Are you interested in and capable of tackling this issue? [yes|no] 29 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature_request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Feature request 3 | about: Suggest an idea for this project 4 | title: '' 5 | --- 6 | 7 | **Is your feature request related to a problem? Please describe.** 8 | A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] 9 | 10 | **Describe the solution you'd like** 11 | A clear and concise description of what you want to happen. 12 | 13 | **Describe alternatives you've considered** 14 | A clear and concise description of any alternative solutions or features you've considered. 15 | 16 | **Additional context** 17 | Add any other context or screenshots about the feature request here. 18 | 19 | **Want to take up?** 20 | Are you interested in and capable of tackling this issue? [yes|no] 21 | -------------------------------------------------------------------------------- /.github/PULL_REQUEST_TEMPLATE/pull_request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Pull request 3 | about: Submit a patch to help us improve 4 | title: '' 5 | --- 6 | 7 | **Description** 8 | What does this PR achieve? [feature|hotfix|refactor] 9 | 10 | **Fixes** 11 | Issue # by @ 12 | 13 | **Technical** 14 | Notable details about the implementation. 15 | 16 | **Testing** 17 | Steps for the reviewer to verify that this PR fixes the problem: 18 | 19 | **Evidence** 20 | If applicable, add screenshots to show the problem and the solution. 21 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # IntelliJ configuration 2 | .idea/ 3 | 4 | # VSCode configuration 5 | .vscode/ 6 | 7 | # macOS files 8 | .DS_Store 9 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Contributor Covenant Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | In the interest of fostering an open and welcoming environment, we as 6 | contributors and maintainers pledge to making participation in our project and 7 | our community a harassment-free experience for everyone, regardless of age, body 8 | size, disability, ethnicity, sex characteristics, gender identity and expression, 9 | level of experience, education, socio-economic status, nationality, personal 10 | appearance, race, religion, or sexual identity and orientation. 11 | 12 | ## Our Standards 13 | 14 | Examples of behavior that contributes to creating a positive environment 15 | include: 16 | 17 | * Using welcoming and inclusive language 18 | * Being respectful of differing viewpoints and experiences 19 | * Gracefully accepting constructive criticism 20 | * Focusing on what is best for the community 21 | * Showing empathy towards other community members 22 | 23 | Examples of unacceptable behavior by participants include: 24 | 25 | * The use of sexualized language or imagery and unwelcome sexual attention or 26 | advances 27 | * Trolling, insulting/derogatory comments, and personal or political attacks 28 | * Public or private harassment 29 | * Publishing others' private information, such as a physical or electronic 30 | address, without explicit permission 31 | * Other conduct which could reasonably be considered inappropriate in a 32 | professional setting 33 | 34 | ## Our Responsibilities 35 | 36 | Project maintainers are responsible for clarifying the standards of acceptable 37 | behavior and are expected to take appropriate and fair corrective action in 38 | response to any instances of unacceptable behavior. 39 | 40 | Project maintainers have the right and responsibility to remove, edit, or 41 | reject comments, commits, code, wiki edits, issues, and other contributions 42 | that are not aligned to this Code of Conduct, or to ban temporarily or 43 | permanently any contributor for other behaviors that they deem inappropriate, 44 | threatening, offensive, or harmful. 45 | 46 | ## Scope 47 | 48 | This Code of Conduct applies both within project spaces and in public spaces 49 | when an individual is representing the project or its community. Examples of 50 | representing a project or community include using an official project e-mail 51 | address, posting via an official social media account, or acting as an appointed 52 | representative at an online or offline event. Representation of a project may be 53 | further defined and clarified by project maintainers. 54 | 55 | ## Enforcement 56 | 57 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 58 | reported by contacting the project team at img@iitr.ac.in. All 59 | complaints will be reviewed and investigated and will result in a response that 60 | is deemed necessary and appropriate to the circumstances. The project team is 61 | obligated to maintain confidentiality with regard to the reporter of an incident. 62 | Further details of specific enforcement policies may be posted separately. 63 | 64 | Project maintainers who do not follow or enforce the Code of Conduct in good 65 | faith may face temporary or permanent repercussions as determined by other 66 | members of the project's leadership. 67 | 68 | ## Attribution 69 | 70 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, 71 | available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html 72 | 73 | [homepage]: https://www.contributor-covenant.org 74 | 75 | For answers to common questions about this code of conduct, see 76 | https://www.contributor-covenant.org/faq 77 | -------------------------------------------------------------------------------- /Pipfile: -------------------------------------------------------------------------------- 1 | [[source]] 2 | name = "pypi" 3 | url = "https://pypi.org/simple" 4 | verify_ssl = true 5 | 6 | [dev-packages] 7 | 8 | [packages] 9 | sphinx = "*" 10 | sphinx-autobuild = "*" 11 | jsx-lexer = "*" 12 | 13 | [requires] 14 | python_version = "3.8" 15 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | > The documentation of the one true portal for any and every educational institute 4 | 5 | ## Status 6 | 7 | [![Documentation Status](https://readthedocs.org/projects/omniport/badge/?version=latest)](https://omniport.readthedocs.io/en/latest/?badge=latest) 8 | 9 | ## Documentation 10 | 11 | Omniport is a portal for educational institutes, designed from the ground up to 12 | be extensible, customizable, performant and powerful. Omniport also comes with 13 | a powerful collection of apps and is simple enough for you to be able to write 14 | your own. 15 | 16 | ## Technological stack 17 | 18 | - Framework: `Sphinx` 19 | - Language: `reStructuredText` 20 | 21 | _This here, is only the documentation of the project, not the project iself._ 22 | 23 | ## Setup 24 | 25 | Refer to the 26 | [setup instructions](https://omniport.readthedocs.io/en/latest/setting_up/omniport_docs.html). 27 | 28 | ## Contribution guidelines 29 | 30 | - Fork the repository to your account. 31 | - Branch out to `a_meaningful_branch_name`. 32 | - Send in a `WIP: Pull request`. 33 | - Commit your changes. 34 | - Get your pull request merged. 35 | 36 | It's that simple! 37 | 38 | ## Credits 39 | 40 | 41 | -------------------------------------------------------------------------------- /docs/.gitignore: -------------------------------------------------------------------------------- 1 | # Ignore the built html files 2 | /build/ 3 | 4 | # Ignore the pickled doctrees 5 | doctrees/ 6 | -------------------------------------------------------------------------------- /docs/Makefile: -------------------------------------------------------------------------------- 1 | # Minimal makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line. 5 | SPHINXOPTS = 6 | SPHINXBUILD = sphinx-build 7 | SOURCEDIR = source 8 | BUILDDIR = build 9 | 10 | SPHINXDEVOPTS = 11 | SPHINXDEV = sphinx-autobuild 12 | 13 | # Put it first so that "make" without argument is like "make help". 14 | help: 15 | @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 16 | 17 | dev: 18 | @$(SPHINXDEV) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXDEVOPTS) 19 | 20 | .PHONY: help Makefile 21 | 22 | # Catch-all target: route all unknown targets to Sphinx using the new 23 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). 24 | %: Makefile 25 | @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -------------------------------------------------------------------------------- /docs/source/_static/css/custom.css: -------------------------------------------------------------------------------- 1 | /* Baskerville */ 2 | @import url('https://fonts.googleapis.com/css?family=Open+Sans:400,400i,700'); 3 | 4 | /* Fira Code */ 5 | @import url(https://cdn.jsdelivr.net/gh/tonsky/FiraCode@1.206/distr/fira_code.css); 6 | 7 | ::selection { 8 | background-color: #5f6fe0; 9 | color: white; 10 | } 11 | 12 | body, body * { 13 | line-height: 1.75; 14 | } 15 | 16 | pre { 17 | border: 1px solid #c6c9cb; 18 | box-shadow: 1px 1px 1px #d8d8d8; 19 | line-height: 1.3; 20 | } 21 | 22 | div.sphinxsidebarwrapper p.logo { 23 | text-align: left; 24 | } 25 | 26 | img.logo { 27 | height: 7em; 28 | } 29 | 30 | .sphinxsidebar a { 31 | font-size: 14px !important; 32 | } 33 | 34 | .highlight * { 35 | font-weight: 400 !important; /* Remove all bold text from code blocks */ 36 | } 37 | 38 | kbd { 39 | padding: 0.1em 0.5em; 40 | border: 1px solid #cccccc; 41 | margin: 0 0.1em; 42 | border-radius: 0.25em; 43 | background-color: #f7f7f7; 44 | box-shadow: 0 1px 0px rgba(0, 0, 0, 0.2), 0 0 0 2px #ffffff inset; 45 | display: inline-block; 46 | line-height: 1.5; 47 | white-space: nowrap; 48 | } 49 | 50 | .ethical-alabaster { 51 | opacity: 0.2; 52 | transition: opacity 1s; 53 | } 54 | 55 | .ethical-alabaster:hover { 56 | opacity: 1; 57 | } -------------------------------------------------------------------------------- /docs/source/_static/gif/oauth.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/IMGIITRoorkee/omniport-docs/a0f942e01599f5a720234f8143a68e75d739a802/docs/source/_static/gif/oauth.gif -------------------------------------------------------------------------------- /docs/source/_static/github_banner.svg: -------------------------------------------------------------------------------- 1 | 2 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | -------------------------------------------------------------------------------- /docs/source/_static/licenses/gnu_fdl.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/IMGIITRoorkee/omniport-docs/a0f942e01599f5a720234f8143a68e75d739a802/docs/source/_static/licenses/gnu_fdl.png -------------------------------------------------------------------------------- /docs/source/_static/licenses/gnu_gplv3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/IMGIITRoorkee/omniport-docs/a0f942e01599f5a720234f8143a68e75d739a802/docs/source/_static/licenses/gnu_gplv3.png -------------------------------------------------------------------------------- /docs/source/_static/maintainers/img_logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/IMGIITRoorkee/omniport-docs/a0f942e01599f5a720234f8143a68e75d739a802/docs/source/_static/maintainers/img_logo.png -------------------------------------------------------------------------------- /docs/source/_static/maintainers/img_wordmark.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/IMGIITRoorkee/omniport-docs/a0f942e01599f5a720234f8143a68e75d739a802/docs/source/_static/maintainers/img_wordmark.png -------------------------------------------------------------------------------- /docs/source/_static/site/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/IMGIITRoorkee/omniport-docs/a0f942e01599f5a720234f8143a68e75d739a802/docs/source/_static/site/favicon.ico -------------------------------------------------------------------------------- /docs/source/_static/site/op_card.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/IMGIITRoorkee/omniport-docs/a0f942e01599f5a720234f8143a68e75d739a802/docs/source/_static/site/op_card.png -------------------------------------------------------------------------------- /docs/source/_static/site/op_logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/IMGIITRoorkee/omniport-docs/a0f942e01599f5a720234f8143a68e75d739a802/docs/source/_static/site/op_logo.png -------------------------------------------------------------------------------- /docs/source/_static/site/op_wordmark.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/IMGIITRoorkee/omniport-docs/a0f942e01599f5a720234f8143a68e75d739a802/docs/source/_static/site/op_wordmark.png -------------------------------------------------------------------------------- /docs/source/_templates/layout.html: -------------------------------------------------------------------------------- 1 | {% extends "!layout.html" %} 2 | {% block extrahead %} 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | {{ super() }} 18 | {% endblock %} 19 | -------------------------------------------------------------------------------- /docs/source/conf.py: -------------------------------------------------------------------------------- 1 | ########################################################### 2 | # Configuration file for the Sphinx documentation builder # 3 | ########################################################### 4 | 5 | # This file does only contain a selection of the most common options. 6 | # For a full list see the documentation: 7 | # http://www.sphinx-doc.org/en/master/config 8 | 9 | 10 | ####################### 11 | # Project information # 12 | ####################### 13 | 14 | # Branding 15 | project = 'Omniport' 16 | documentation = 'Omniport documentation' 17 | oneliner = 'The one true portal for any and every educational institute.' 18 | group = 'Information Management Group' 19 | authors = [ 20 | 'Dhruv Bhanushali', 21 | 'Praduman Goyal', 22 | ] 23 | copyright = group 24 | author = ', '.join(authors) 25 | 26 | # Colouring 27 | purple = '#8f52ec' 28 | blue = '#5f6fe0' 29 | white = '#ffffff' 30 | 31 | # Versioning 32 | version = '' 33 | release = '' 34 | 35 | 36 | ######################### 37 | # General configuration # 38 | ######################### 39 | 40 | # Any Sphinx extension module names 41 | extensions = [ 42 | 'sphinx.ext.autodoc', 43 | 'sphinx.ext.doctest', 44 | 'sphinx.ext.intersphinx', 45 | 'sphinx.ext.todo', 46 | 'sphinx.ext.coverage', 47 | 'sphinx.ext.mathjax', 48 | 'sphinx.ext.ifconfig', 49 | 'sphinx.ext.viewcode', 50 | ] 51 | 52 | # Any paths that contain templates 53 | templates_path = [ 54 | '_templates', 55 | ] 56 | 57 | # The suffix of source filenames 58 | source_suffix = '.rst' 59 | 60 | # The master toctree document 61 | master_doc = 'index' 62 | 63 | # The language for content autogenerated by Sphinx 64 | language = 'en' 65 | 66 | # Files and directories to ignore when looking for source files 67 | exclude_patterns = [] 68 | 69 | # The name of the Pygments style to use 70 | pygments_style = None 71 | 72 | 73 | ######## 74 | # HTML # 75 | ######## 76 | 77 | # The theme to use for HTML and HTML Help pages 78 | html_theme = 'alabaster' 79 | html_theme_options = { 80 | # Sidebar 81 | 'fixed_sidebar': True, 82 | 'logo': 'site/op_logo.png', 83 | 'description': ' ', # Adds a bit of space below the logo 84 | 85 | # GitHub 86 | 'github_user': 'IMGIITRoorkee', 87 | 'github_repo': 'omniport-docker', 88 | 'github_banner': 'github_banner.svg', 89 | 'github_button': False, 90 | 91 | # Header and footer 92 | 'show_relbars': True, 93 | 'show_powered_by': False, 94 | 95 | # Colouring 96 | 'anchor': blue, 97 | 'anchor_hover_bg': white, 98 | 'anchor_hover_fg': purple, 99 | 100 | 'relbar_border': purple, 101 | 102 | 'link_hover': blue, 103 | 104 | # Fonts 105 | 'font_family': '"Open Sans", sans-serif', 106 | 'font_size': '14px', 107 | 108 | 'code_font_size': '1em', 109 | 'code_font_family': '"Fira Code", monospace', 110 | } 111 | 112 | # Path to the favicon of the site 113 | html_favicon = '_static/site/favicon.ico' 114 | 115 | # Add any paths that contain custom static files 116 | html_static_path = [ 117 | '_static', 118 | '_static/css', 119 | ] 120 | 121 | 122 | ############# 123 | # HTML Help # 124 | ############# 125 | 126 | # Output file base name for HTML help builder. 127 | htmlhelp_basename = documentation 128 | 129 | 130 | ######## 131 | # EPUB # 132 | ######## 133 | 134 | # Bibliographic Dublin Core info 135 | epub_title = project 136 | 137 | # The unique identifier of the text 138 | epub_identifier = 'https://omniport.readthedocs.io/' 139 | 140 | # Files that should not be packed into the EPUP file 141 | epub_exclude_files = [ 142 | 'search.html', 143 | ] 144 | 145 | 146 | ######### 147 | # LaTeX # 148 | ######### 149 | 150 | # LaTeX snippets overriding those Sphinx usually puts into the files 151 | latex_elements = { 152 | # Sizes 153 | 'papersize': 'a4paper', 154 | 'pointsize': '10pt', 155 | 156 | # Preamble 157 | 'preamble': ( 158 | r''' 159 | \usepackage[none]{hyphenat} 160 | \usepackage[default]{lato} 161 | \usepackage{inconsolata} 162 | ''' 163 | ), 164 | } 165 | 166 | # Path to the logo of the project 167 | latex_logo = '_static/site/op_wordmark.png' 168 | 169 | # Latex files 170 | # (source start file, target name, title, author, documentclass) 171 | latex_documents = [ 172 | ( 173 | master_doc, 174 | 'Omniport.tex', 175 | documentation, 176 | author, 177 | 'manual' 178 | ), 179 | ] 180 | 181 | 182 | ################ 183 | # Manual pages # 184 | ################ 185 | 186 | # Manual pages 187 | # (source start file, name, description, authors, manual section) 188 | man_pages = [ 189 | ( 190 | master_doc, 191 | project, 192 | documentation, 193 | authors, 194 | 1, 195 | ), 196 | ] 197 | 198 | 199 | ################## 200 | # Texinfo output # 201 | ################## 202 | 203 | # Texinfo files 204 | # (source start file, target name, title, author, dir menu entry, description, category) 205 | texinfo_documents = [ 206 | ( 207 | master_doc, 208 | project, 209 | documentation, 210 | author, 211 | project, 212 | oneliner, 213 | 'Miscellaneous', 214 | ), 215 | ] 216 | 217 | 218 | ############## 219 | # Extensions # 220 | ############## 221 | 222 | # Intersphinx 223 | intersphinx_mapping = {'https://docs.python.org/': None} 224 | 225 | # To-do 226 | todo_include_todos = True 227 | -------------------------------------------------------------------------------- /docs/source/credits.rst: -------------------------------------------------------------------------------- 1 | Credits 2 | ======= 3 | 4 | :: 5 | 6 | __ 7 | __ /\ \__ 8 | ___ ___ ___ ___ /\_\ __ _____ ___ _ __\ \ ,_\ 9 | / __`\ /' __` __`\ /' _ `\/\ \/\_\ /\ '__`\ / __`\/\`'__\ \ \/ 10 | /\ \L\ \/\ \/\ \/\ \/\ \/\ \ \ \/_/_\ \ \L\ \/\ \L\ \ \ \/ \ \ \_ 11 | \ \____/\ \_\ \_\ \_\ \_\ \_\ \_\/\_\\ \ ,__/\ \____/\ \_\ \ \__\ 12 | \/___/ \/_/\/_/\/_/\/_/\/_/\/_/\/_/ \ \ \/ \/___/ \/_/ \/__/ 13 | ______ \ \ \ 14 | /\_____\ \ \_\ 15 | \/_____/ \/_/ 16 | 17 | 18 | Omniport is a team-effort. The sheer size of the project means that no one 19 | person is capable of creating, maintaining or upgrading the project. That said, 20 | some people deserve credit for their exceptional contributions towards the 21 | project. These are mentioned below. 22 | 23 | Docker 24 | ------ 25 | 26 | The Dockerised distribution was made possible by Dhruv Bhanushali (dhruvkb_) 27 | with intermittent help of Pranjal Tale (pranjaltale16_). 28 | 29 | Backend core 30 | ------------ 31 | 32 | The backend was developed and Dockerised by Dhruv Bhanushali (dhruvkb_) with 33 | the idea of swappable models incepted by Rohith Asrk (rohithasrk_). 34 | 35 | Frontend core 36 | ------------- 37 | 38 | The frontend core was developed by Mohit Virli (mohitvirli_), and then 39 | prepped for deployment by Praduman Goyal (pradumangoyal_). It was Dockerised by 40 | Dhruv Bhanushali (dhruvkb_). 41 | 42 | Documentation 43 | ------------- 44 | 45 | This documentation was written by Praduman Goyal (pradumangoyal_) and Dhruv 46 | Bhanushali (dhruvkb_), the latter being the editor as well. 47 | 48 | Services 49 | -------- 50 | 51 | The full set of services for Omniport were developed by Dhruv Bhanushali 52 | (dhruvkb_) on the backend and Praduman Goyal (pradumangoyal_) on the frontend. 53 | 54 | Apps 55 | ---- 56 | 57 | The entire team of the Information Management Group worked on developing apps 58 | for Omniport. They can be found on GitHub (IMGIITRoorkee_) and on our website_. 59 | 60 | Orchestra 61 | --------- 62 | 63 | Like we said earlier, the orchestra deserves a fair share of credit. 64 | 65 | .. figure:: /_static/maintainers/img_wordmark.png 66 | :figwidth: 100% 67 | :height: 64px 68 | :align: center 69 | :alt: IMG wordmark 70 | 71 | All hail the greatest campus development group of all time! 72 | 73 | .. _dhruvkb: https://github.com/dhruvkb 74 | .. _pranjaltale16: https://github.com/pranjaltale16 75 | .. _rohithasrk: https://github.com/rohithasrk 76 | .. _mohitvirli: https://github.com/mohitvirli 77 | .. _gaurav9825: https://github.com/gaurav9825 78 | .. _pradumangoyal: https://github.com/pradumangoyal 79 | 80 | .. _IMGIITRoorkee: https://github.com/IMGIITRoorkee 81 | .. _website: https://img.channeli.in -------------------------------------------------------------------------------- /docs/source/environments/development.rst: -------------------------------------------------------------------------------- 1 | Development 2 | =========== 3 | 4 | The development workflow is the workflow suited to teams where multiple 5 | developers work on multiple projects at the same time. This is the development 6 | flow implemented at IMG, IIT Roorkee. 7 | 8 | The postulates of the development workflow are: 9 | 10 | - **There is a central development server.** 11 | 12 | It must be highly powerful, but it depends on how many developers are 13 | going to be simultaneously developing on and for Omniport. 14 | 15 | - **Developers SSH into the remote from a terminal in the maintainers' lab.** 16 | 17 | Each developer gets a unique account on the remote. They clone the codebase 18 | (and not the infrastructure) in their accounts, each running a copy and 19 | making their changes in said copy. 20 | 21 | All development work happens on the remote. One feasible option is 22 | programming on Vim inside SSH. Another is programming on the codebase 23 | replicated via SFTP. 24 | 25 | - **Application servers share standalone services.** 26 | 27 | The common services such as the database and the message-broker are run in 28 | the Docker sandbox under an altogether different user, which is neither the 29 | ``root``, nor one of the developers. 30 | 31 | At IMG we call this user ``apps``. You are free to name it whatever pleases 32 | you. Just remember this name for later. 33 | 34 | - **All developers run their own application servers.** 35 | 36 | Since application servers hot-load the code from the host, every developer 37 | can host their code independently of other application servers. 38 | 39 | - **Application servers expose a port on the 0.0.0.0 interface on the server.** 40 | 41 | The Django development server runs on ``0.0.0.0:600xx`` and the React 42 | development server runs on ``0.0.0.0:610xx``, proxying requests to the 43 | Django server. 44 | 45 | These servers can be accessed in a browser on the developer's local terminal 46 | by visiting ``http://:/``. 47 | 48 | If this is not your setup and you are not in a postition for this to be your 49 | setup, you are, unfortunately, on your own for this one. See if our production 50 | setup suits you more, but that's about as far as we can go. 51 | 52 | But given that you are developers, we have complete faith that you'll find a 53 | way. *Developers always do.* -------------------------------------------------------------------------------- /docs/source/environments/index.rst: -------------------------------------------------------------------------------- 1 | Environments 2 | ============ 3 | 4 | The Omniport project has been designed keeping both development and production 5 | environments in mind. Although the terms might be generic enough for every 6 | single team in the world to have both of them, every single team implements 7 | these two workflows in a very unique way. 8 | 9 | The Omniport Docker project is highly opinionated on both of these workflows, 10 | which means that the out-of-the-box defaults might very likely not be what you 11 | expect or want. 12 | 13 | .. note:: 14 | 15 | If you are a lone-wolf developer, the default production workflow, albeit with 16 | debugging enabled, is more likely to suit you rather than the default 17 | development one. 18 | 19 | Read on to understand what Omniport's assumption of your workflows looks like. 20 | 21 | .. toctree:: 22 | :caption: Subsections: 23 | 24 | development 25 | production -------------------------------------------------------------------------------- /docs/source/environments/production.rst: -------------------------------------------------------------------------------- 1 | Production 2 | ========== 3 | 4 | The production workflow is the workflow suited to production where no 5 | development takes place and everything runs with maximum automation. 6 | Alternatively this workflow is also applicable to individual developers, 7 | developing on their own computers. This is the production flow implemented at 8 | IMG, IIT Roorkee. 9 | 10 | The postulates of the production workflow are: 11 | 12 | - **There is the production server.** 13 | 14 | It must be powerful enough to bear the load of all the people who would be 15 | using it. Depending on your college size and your own purchasing power, that 16 | could mean your laptops or entire farms. 17 | 18 | - **One person, the sysadmin, the boss, the chief, opens an SSH session.** 19 | 20 | I wasn't sure if SSHs or SSHes, so I went with *'...opens an SSH session'*. 21 | This person must manage an underprivileged user on the server, which still 22 | has Docker rights though. 23 | 24 | At IMG, we call this user ``apps``. Again you can name it whatever you damn 25 | well please, provided you remember this name for future use. 26 | 27 | - **Everything is managed and orchestrated by Docker Compose.** 28 | 29 | You execute one command and everything goes up. 30 | 31 | We are pretty confident that's how any production would work so you should be 32 | fine. If you are smart enough to use an altogether different production setup, 33 | you should be smart enough to tweak this to your use. You're on your own for 34 | this one, unfortunately. 35 | 36 | Remember our advice from :doc:`the development section `. 37 | -------------------------------------------------------------------------------- /docs/source/how_to/access_app_registry.rst: -------------------------------------------------------------------------------- 1 | ... access app registry? 2 | ======================== 3 | 4 | Discovery and Configuration allow Omniport to be extensible and tailored to the 5 | needs and requirements of a particular institute. But this comes at the cost of 6 | integrability as one app can never fully be sure of the existence of another. 7 | 8 | Consider for example, the service Helpcentre which allows users to ask queries 9 | which may have to do with a particular app. To enable this functionality, 10 | Helpcentre needs to know, dynamically, the list of apps that have been installed 11 | in the Omniport ecosystem. 12 | 13 | This is where accessing the app registry comes into the picture. This 14 | functionality enables developers of services like Helpcentre and Notifications 15 | to be aware of the apps installed and configured by the sysadmin. 16 | 17 | Fortunately Discovery provides this feature. To use it, first import the 18 | function ``available_apps``. 19 | 20 | .. code-block:: python 21 | 22 | from discovery.available import available_apps 23 | 24 | Then in a function where the request object is available, such as a view or a 25 | DRF viewset, invoke the ``available_apps`` function. 26 | 27 | .. code-block:: python 28 | 29 | available_app_list = available_apps(request=request) -------------------------------------------------------------------------------- /docs/source/how_to/brand_omniport.rst: -------------------------------------------------------------------------------- 1 | ... brand Omniport? 2 | =================== 3 | 4 | Omniport is the working title of the project. Your portal need not be named 5 | Omniport, although no one's going to stop you from naming it that if you prefer. 6 | 7 | However, for those of us that would like to brand their specific instance of 8 | Omniport, branding has been made really really easy. Effortless actually. 9 | Omniport supports deep branding of the portal to customise it thoroughly for 10 | your institute. 11 | 12 | Very fancy. 13 | 14 | Destination 15 | ----------- 16 | 17 | All paths referenced here lie within the ``omniport-backend/`` folder inside 18 | the ``codebase/`` folder. 19 | 20 | Instructions 21 | ------------ 22 | 23 | - **Follow the naming convention specified.** 24 | 25 | Omniport is not sentient and will 26 | not locate your images if not named and placed according to the pattern. To 27 | omit an asset, leave out the file. 28 | 29 | - **Follow the size and aspect ratio guidelines.** 30 | 31 | This is so that the assets 32 | integrate harmoniously with the rest of the portal. As feature packed as 33 | Omniport is, it is not free of assumptions. 34 | 35 | - **Follow the file format specification.** 36 | 37 | As a rule of thumb prefer `.svg` 38 | and `.ico` when the image needs to scale up and down respectively. Preferred 39 | file formats are given, in order of preference, best stick to them. 40 | 41 | - **All branding is optional.** 42 | 43 | While a bit of imagery adds to the aesthetics, 44 | it is not essential. In its absence, everything will gracefully fallback on 45 | textual branding defined in `configuration/`. 46 | 47 | Image specifications 48 | -------------------- 49 | 50 | ================= ================== ================= ============================== 51 | File name Aspect ratio Height in use Formats 52 | ================= ================== ================= ============================== 53 | ``favicon.ico`` square 16, 32, 48 px multisize ``.ico`` only 54 | ``logo.xyz`` square preferred 3.5em *(~49px)* ``.svg``, ``.png``, ``.jpg`` 55 | ``wordmark.xyz`` no restrictions 3.5em *(~49px)* ``.svg``, ``.png``, ``.jpg`` 56 | ================= ================== ================= ============================== 57 | 58 | All images should be provided in 2x size if not supplying in the ``.svg`` format 59 | to ensure that they work well on HiDPI displays. 60 | 61 | For best results, use `RealFaviconGenerator `_ to generate 62 | your ``favicon.ico`` files. 63 | 64 | Branding types 65 | -------------- 66 | 67 | Batteries-included 68 | ++++++++++++++++++ 69 | 70 | The following files are required to brand Omniport with your custom branding. 71 | Defaults will be provided for these images. 72 | 73 | - ``site/``: 74 | 75 | Since Omniport allows you to run multiple sites (such as Intranet 76 | and Internet) from the same portal, we allow you to brand them separately by 77 | loading indexed files. 78 | 79 | Indexing works by suffixing ``_`` to the folder name. So a logo for a 80 | site with site ID 2 should be placed in ``site_2/`` for Omniport to recognise it. 81 | This is optional and you can skip the indexing portion to use the same asset 82 | across your sites. 83 | 84 | Ensure that you brand all your served sites or provide a non-indexed version as 85 | fallback. You may use the provided default Omniport branding for your portal or 86 | *for reference* when designing your own, if designing your own. 87 | 88 | If not redesigning your own icons, be sure to respect the 89 | :doc:`Brand usage guide <../legal/brand_usage_guide/index>`. 90 | 91 | Batteries-not-included 92 | ++++++++++++++++++++++ 93 | 94 | The following files are required to brand Omniport with your custom branding. 95 | No defaults will be provided for these images. 96 | 97 | - ``institute/``: 98 | 99 | Your institutes logo and wordmark should be used here. There are no defaults and 100 | no references for this set of imagery. 101 | 102 | - ``maintainers/``: 103 | 104 | The branding imagery employed by Information Management Group for the Indian 105 | Institute of Technology, Roorkee is available *for reference*. 106 | -------------------------------------------------------------------------------- /docs/source/how_to/create_an_app.rst: -------------------------------------------------------------------------------- 1 | ... create an app? 2 | ================== 3 | 4 | Backend 5 | ------- 6 | 7 | File structure of a typical app is as follows. 8 | 9 | :: 10 | 11 | placement_and_internship 12 | ├── config.yml 13 | ├── LICENSE 14 | ├── README.md 15 | ├── __init__.py 16 | ├── http_urls.py 17 | ├── apps.py 18 | ├── migrations 19 | │   └── __init__.py 20 | ├── models 21 | │   └── __init__.py 22 | ├── static 23 | │   └── assets 24 | │   ├── favicon.ico 25 | │   ├── icon.svg 26 | │   ├── logo.svg 27 | │   └── README.md 28 | └── views 29 | ├── hello_world.py 30 | └── __init__.py 31 | 32 | Look familiar? That's because it is. The structure of the app is the same, with 33 | a few notable exceptions as below. 34 | 35 | ``config.yml`` 36 | ++++++++++++++ 37 | 38 | We need to create, or if it exists, populate the ``config.json`` file with the 39 | internal name, the display name, the URLs and the acceptables as shown in the 40 | example. 41 | 42 | .. code-block:: yaml 43 | 44 | nomenclature: 45 | name: placement_and_internship 46 | verboseName: Placement and internship 47 | description: Build your resume, apply and get placed 48 | baseUrls: 49 | http: placement_and_internship/ 50 | static: placement_and_internship/ 51 | isApi: true 52 | acceptables: 53 | ipAddressRings: 54 | - self 55 | - specifics 56 | - maintainers 57 | - intranet 58 | roles: 59 | - name: Student 60 | activeStatuses: 61 | - IS_ACTIVE 62 | 63 | .. seealso:: 64 | 65 | For more information on ``config.yml`` see :doc:`this 66 | <../references/config_files/app/config_yml>`. 67 | 68 | ``http_urls.py`` 69 | ++++++++++++++++ 70 | 71 | This file is the same old ``urls.py`` of Django, with the name changed in order 72 | to differentiate if from the ``ws_urls.py`` file that configures the URLconf 73 | for WebSockets. 74 | 75 | ``ws_urls.py`` 76 | ++++++++++++++ 77 | 78 | This file is the URLconf for Django Channels that guides requests from 79 | WebSockets. This file needs to exist if your app makes use of realtime 80 | communications. If you define ``ws:`` in your ``baseUrls:`` you must have this 81 | file in your app's root folder. 82 | 83 | ``static/assets/`` 84 | ++++++++++++++++++ 85 | 86 | This folder, with no variations in the directory names, contains various app 87 | assets such as icon, favicon and logo. 88 | 89 | Frontend 90 | -------- 91 | 92 | File structure of a typical app is as follows. 93 | 94 | :: 95 | 96 | placement_and_internship 97 | ├── config.json 98 | ├── LICENSE 99 | ├── README.md 100 | └── src 101 | ├── components 102 | │   └── app.js 103 | ├── css 104 | │   └── app.css 105 | ├── index.js 106 | ├── reducers 107 | │   ├── exampleReducer.js 108 | │   └── index.js 109 | └── urls.js 110 | 111 | Look familiar? That's because it is. The structure of the app is the same, with 112 | a few notable exceptions as below. 113 | 114 | ``config.json`` 115 | +++++++++++++++ 116 | 117 | We need to create, or if it exists, populate the ``config.json`` file with the 118 | internal name, the display name and the URLs as shown in the example. 119 | 120 | .. code-block:: json 121 | 122 | { 123 | "nomenclature": { 124 | "name": "placement_and_internship", 125 | "verboseName": "Placement and Internship" 126 | }, 127 | "baseUrl": "/placement_and_internship", 128 | "source": "placement_and_internship/src/index" 129 | } 130 | 131 | .. seealso:: 132 | 133 | For more information on ``config.json`` see :doc:`this 134 | <../references/config_files/app/config_json>`. 135 | 136 | ``index.js`` 137 | ++++++++++++ 138 | 139 | ``index.js`` plays an important role in connecting your app to ``Omniport``. It 140 | act as a gateway between ``omniport-core`` and your app. 141 | 142 | An ``index.js`` file looks like this. 143 | 144 | .. code-block:: jsx 145 | 146 | import React, { Component } from 'react' 147 | import { Route } from 'react-router-dom' 148 | import App from './components/app' 149 | import { createStore, applyMiddleware } from 'redux' 150 | import { Provider } from 'react-redux' 151 | import thunk from 'redux-thunk' 152 | 153 | import rootReducers from './reducers' 154 | 155 | export default class AppRouter extends Component { 156 | constructor (props) { 157 | super(props) 158 | this.store = createStore(rootReducers, applyMiddleware(thunk)) 159 | } 160 | 161 | render () { 162 | const { match } = this.props 163 | return ( 164 | 165 | 166 | 167 | ) 168 | } 169 | } 170 | 171 | Here ``App`` is the normal react app component from which you can proceed 172 | similar to a normal react app. 173 | 174 | ``urls.js`` 175 | +++++++++++ 176 | 177 | ``urls.js`` contains both navigation URLs for frontend as well as API endpoints 178 | for backend. 179 | 180 | An example of ``urls.js`` can be as follows. 181 | 182 | .. code-block:: jsx 183 | 184 | import appConfig from '../config.json' 185 | 186 | // Frontend URLs 187 | export function urlBaseView () { 188 | return `${appConfig.baseUrl}` 189 | } 190 | 191 | export function urlGroupDetailView (slug) { 192 | return `${urlBaseView()}/${slug}` 193 | } 194 | 195 | export function urlGroupTeam (slug) { 196 | return `${urlGroupDetailView(slug)}/team` 197 | } 198 | 199 | // Backend URLs 200 | export function urlBase () { 201 | return `/api/groups/` 202 | } 203 | 204 | export function urlGroupList () { 205 | return `${urlBase()}group/` 206 | } 207 | 208 | export function urlActiveGroupPost () { 209 | return `${urlBase()}post/` 210 | } 211 | 212 | Automate all of this 213 | -------------------- 214 | 215 | .. note:: 216 | 217 | Even if it's too complicated for you, refer to the ``create/app.sh`` scripts 218 | provided by Omniport for both the 219 | :doc:`backend <../references/scripts/backend/create_app>` 220 | and the 221 | :doc:`frontend <../references/scripts/frontend/create_app>`. 222 | 223 | Profit. 224 | -------------------------------------------------------------------------------- /docs/source/how_to/examine_database.rst: -------------------------------------------------------------------------------- 1 | ... examine database? 2 | ===================== 3 | 4 | While the Django ORM is beautiful in its capabilities and allows you to interact 5 | with the database in wonderfully Pythonic ways, there are always times when you 6 | have to get your hands dirty and enter the belly of the beast known as Postgres. 7 | 8 | That's also simple to do in Omniport. Just enter the following command into the 9 | shell and you'll be dropped into the PostgreSQL prompt where you can issue SQL 10 | queries to your heart's content. 11 | 12 | .. code-block:: console 13 | 14 | [apps omniport-docker]$ docker-compose exec database psql -U -d 15 | 16 | Here and must be replaced with the values of POSTGRES_DB and 17 | POSTGRES_USER respectively, as written in the file ``postgres/database.env``. 18 | 19 | Here on out, refer to the PostgreSQL documentation for help. -------------------------------------------------------------------------------- /docs/source/how_to/index.rst: -------------------------------------------------------------------------------- 1 | How to ... 2 | ========== 3 | 4 | Omniport presents a sea of possibilities to any aspiring developer. It provides 5 | a platform for developing the richest and finest applications that can 6 | 7 | - eventually be added into the portal, under the aegis of the local instance 8 | maintainers. 9 | - use the most trustworthy authentication source for your campus applications. 10 | 11 | However it is natural to face the question of how. 12 | 13 | | *"How can I build my Omniport application?"* 14 | | *"How can I use OAuth2 to provide seamless authentication?"* 15 | 16 | These, and so many more similar questions, are just indicative of the kind of 17 | dilemmas you might face. To make it easy for you, we have compiled a list of 18 | tutorials that you can follow to make your journey as a campus developer more 19 | comfortable. 20 | 21 | .. toctree:: 22 | :caption: Subsections: 23 | :maxdepth: 2 24 | 25 | brand_omniport 26 | create_an_app 27 | use_oauth2 28 | write_logs 29 | read_logs 30 | migrate_database 31 | examine_database 32 | access_app_registry 33 | monitor_health 34 | -------------------------------------------------------------------------------- /docs/source/how_to/migrate_database.rst: -------------------------------------------------------------------------------- 1 | ... migrate database? 2 | ===================== 3 | 4 | Before you can make any use of Omniport, you'll need to migrate the database. 5 | This can be accomplished with the usual ``migrate`` command. from inside the 6 | intranet or Internet server container. 7 | 8 | .. code-block:: python 9 | 10 | [apps omniport-docker]$ docker-compose exec intranet-server bash 11 | docker@intranet-server:/omniport$ python manage.py migrate 12 | 13 | In a regular classic Django setup you could very easily skip and 14 | migrate every installed app automatically. Unfortunately, our use of swappable 15 | models makes that a little complicated. 16 | 17 | .. warning:: 18 | 19 | Because of the same reason as stated above, the use of a shell must be 20 | thoroughly debated and determined beforehand. After the migration, a shell 21 | cannot be inserted or removed without a complete reset of the database. 22 | 23 | You will need to migrate apps individually and in a strictly defined order. This 24 | is as follows. 25 | 26 | #. kernel (will automatically migrate contenttypes, auth, base_auth and shell) 27 | #. auth 28 | #. session_auth 29 | #. sessions 30 | #. open_auth 31 | #. oauth2_provider 32 | #. admin 33 | #. guardian 34 | 35 | After the above have been migrated, you have a fully functional Omniport core. 36 | But that is not all, you'll also have to migrate the following before the 37 | installation can be of any use. 38 | 39 | #. *any remaining services* 40 | #. *any remaining apps* 41 | 42 | At any time during the migration process, run the following command to see what 43 | has been migrated and what is left to be migrated. 44 | 45 | .. code-block:: console 46 | 47 | docker@intranet-server:/omniport$ python manage.py showmigrations 48 | 49 | That's it. Now you have a fully migrated database and are ready to populate it. -------------------------------------------------------------------------------- /docs/source/how_to/monitor_health.rst: -------------------------------------------------------------------------------- 1 | ... monitor health? 2 | =================== 3 | 4 | All Omniport containers (except NGINX, so far) have healthchecks built into them 5 | to provide an easy way to monitor the health of containers in real time. These 6 | healthchecks run at 16 minute intervals. 7 | 8 | The results of the healthchecks can be seen using the ``ps`` command afforded by 9 | Docker Compose. 10 | 11 | .. code-block:: console 12 | 13 | [apps omniport-docker]$ docker-compose ps 14 | 15 | And there you have it. Container health is mentioned in brackets in the 'State' 16 | column. The state can be one of several values. 17 | 18 | :Up (health\: starting): 19 | if the health check was run on an upcoming container 20 | :Up (healthy): 21 | if the health check was run and reported a success 22 | 23 | That's all you need to know to stay updated on the health of your containers! -------------------------------------------------------------------------------- /docs/source/how_to/read_logs.rst: -------------------------------------------------------------------------------- 1 | ... read logs? 2 | ============== 3 | 4 | Reading Omniport logs is just as easy as writing them is. That's largely because 5 | a lot of the work has been done for you out-of-the-box. We're really generous 6 | that way. 7 | 8 | Enter logs container 9 | -------------------- 10 | 11 | From the Omniport Docker root directory, run the script that opens a shell into 12 | the logging volumes. 13 | 14 | .. code-block:: console 15 | 16 | [apps omniport-docker]$ ./scripts/start/logs.sh 17 | 18 | This will drop you into the Docker shell. For more on this script, you can read 19 | the :doc:`script article <../references/scripts/docker/start/logs>`. 20 | 21 | Find the log directory 22 | ---------------------- 23 | 24 | An assortment of events are continuously logged in Omniport. A list of these 25 | events and their corresponding log locations are mentioned here. 26 | 27 | Reverse proxy logs 28 | ++++++++++++++++++ 29 | 30 | :Directory: 31 | /reverse_proxy_logs/ 32 | 33 | NGINX 34 | ..... 35 | 36 | :Subdirectory: 37 | nginx_logs/ 38 | 39 | The following is a map of the sources and log files for NGINX. 40 | 41 | +---------------------+---------------------+ 42 | | Source | Log file | 43 | +=====================+=====================+ 44 | | Intranet access log | intranet-access.log | 45 | +---------------------+---------------------+ 46 | | Intranet error log | intranet-error.log | 47 | +---------------------+---------------------+ 48 | | Internet access log | internet-access.log | 49 | +---------------------+---------------------+ 50 | | Internet error log | internet-error.log | 51 | +---------------------+---------------------+ 52 | 53 | Web server logs 54 | +++++++++++++++ 55 | 56 | :Directory: 57 | /web_server_logs/ 58 | 59 | Gunicorn 60 | ........ 61 | 62 | :Subdirectory: 63 | gunicorn_logs/ 64 | 65 | The following is a map of the sources and log files for Gunicorn. 66 | 67 | +----------------------+----------------+ 68 | | Source | Log file | 69 | +======================+================+ 70 | | Access log | -access.log | 71 | +----------------------+----------------+ 72 | | Error log | -error.log | 73 | +----------------------+----------------+ 74 | | Django log | -django.log | 75 | +----------------------+----------------+ 76 | | Service and app logs | -.log | 77 | +----------------------+----------------+ 78 | 79 | Here must be replaced with **1** or **2** based on the site IDs. For more 80 | information on site IDs, refer to the :doc:`site-level configuration docs 81 | <../references/config_files/project/site_yml>`. 82 | 83 | Also should be the actual name (not verbose name) of the service or app 84 | in question. 85 | 86 | Daphne 87 | ...... 88 | 89 | :Subdirectory: 90 | daphne_logs/ 91 | 92 | The following is a map of the sources and log files for Daphne. This is not 93 | exhaustive because Daphne is used exclusively on ``ws/`` URLs and is not 94 | well-documented itself. 95 | 96 | +----------------------+----------------+ 97 | | Source | Log file | 98 | +======================+================+ 99 | | Access log | -access.log | 100 | +----------------------+----------------+ 101 | 102 | Here must be replaced with **1** or **2** based on the site IDs. For more 103 | information on site IDs, refer to the :doc:`site-level configuration docs 104 | <../references/config_files/project/site_yml>`. 105 | 106 | Supervisor 107 | .......... 108 | 109 | :Subdirectory: 110 | supervisord_logs/ 111 | 112 | The following is a map of the sources and log files for Supervisor. 113 | 114 | +-----------------+-------------------------+ 115 | | Source | Log file | 116 | +=================+=========================+ 117 | | Self | self-.log | 118 | +-----------------+-------------------------+ 119 | | Gunicorn stdout | gunicorn--stdout.log | 120 | +-----------------+-------------------------+ 121 | | Gunicorn stderr | gunicorn--stderr.log | 122 | +-----------------+-------------------------+ 123 | | Daphne stdout | daphne--stdout.log | 124 | +-----------------+-------------------------+ 125 | | Daphne stderr | daphne--stderr.log | 126 | +-----------------+-------------------------+ 127 | 128 | Here must be replaced with **1** or **2** based on the site IDs. For more 129 | information on site IDs, refer to the :doc:`site-level configuration docs 130 | <../references/config_files/project/site_yml>`. 131 | 132 | Tail the log 133 | ------------ 134 | 135 | For real-time monitoring we go back to the classic ``tail`` utility whose 136 | capabilities have withstood the test of time. 137 | 138 | .. code-block:: console 139 | 140 | docker@logs:/$ tail -n -f 141 | 142 | And there you have it. You are now armed with a comprehensive understanding of 143 | where to find logs to troubleshoot any and every error that could hit Omniport. -------------------------------------------------------------------------------- /docs/source/how_to/use_oauth2.rst: -------------------------------------------------------------------------------- 1 | ... use Omniport OAuth2? 2 | ======================== 3 | 4 | The following walkthrough will show you how to integrate Omniport OAuth2 in 5 | your applications. 6 | 7 | Registering your application 8 | ---------------------------- 9 | 10 | Register your app for Omniport OAuth2 by visiting the developer portal on 11 | ``/developer/add``. Here you will be asked a few details about your app. You 12 | have to 13 | 14 | - add your app name, redirect URIs in correct format. 15 | - describe your app in strictly 127 - 511 words. 16 | - select the minimum number of scopes (user information) that you will require 17 | for your app. 18 | - read 19 | :doc:`Omniport developer terms of use <../legal/developer_terms_of_use/>` and 20 | agree to all of the terms therein. 21 | 22 | Click on Add button to proceed. You will be taken to app administration 23 | dashboard. Here you can edit a few things about your app, like branding, team 24 | members and redirect URIs. 25 | 26 | Note down your **client ID** and **client secret key** from the dashboard. 27 | 28 | .. note:: 29 | 30 | Describe your app adequately and truthfuly. Also keep in mind that selecting 31 | as fewer scopes as possible will increase the odds in favour of approval of 32 | your app by the administration. After submitting your app request, your 33 | approval status can be seen and tracked from the developer dashboard. 34 | 35 | .. warning:: 36 | You will be unable to use OAuth2 without said approval. Users will not be able 37 | to access your authorise your app to use their data. 38 | 39 | Authorising the user 40 | -------------------- 41 | 42 | To authorise your users, redirect them to ``/oauth/authorise`` through a ``GET`` 43 | request with the following parameters. 44 | 45 | ========================= ===================================================================== 46 | Parameter Description 47 | ========================= ===================================================================== 48 | **client_id** (required) The client ID you obtained from the dashboard 49 | **redirect_uri** One of the redirect URIs you have registered on the dashboard 50 | **state** Any string that you want the ``REDIRECT_URI`` to receive on success 51 | ========================= ===================================================================== 52 | 53 | .. warning:: 54 | 55 | If the ``redirect_uri`` does not match any of the listed redirect URIs, the 56 | authorisation request will fail and the user will not see an authorisation 57 | screen. 58 | 59 | .. note:: 60 | 61 | For additional information on the query parameters refer to the 62 | `documentation `_ of 63 | the Django OAuth Toolkit PyPI package. 64 | 65 | A sample authorisation request URL could therefore look like the one below. 66 | 67 | :: 68 | 69 | /oauth/authorise/?client_id=MY_CLIENT_ID 70 | <&redirect_uri=REDIRECT_URI> 71 | <&state=RANDOM_STATE_STRING> 72 | 73 | The user experience 74 | ------------------- 75 | 76 | At this point, you’ve forwarded the user to Omniport authorisation page, where 77 | they will be greeted by the following screen (they might need to log in before 78 | they see it). 79 | 80 | .. image:: /_static/gif/oauth.gif 81 | :target: / 82 | :align: center 83 | :alt: OAuth authorisation screen 84 | 85 | Neither you or your application can or need to do anything here; Omniport 86 | deals with the user, receiving the user's intent to approve or disapprove your 87 | app. Based on whether the user approves the app or denies it, the user will be 88 | redirected to ``REDIRECT_URI`` or back to Omniport home. 89 | 90 | Handling the Response from Omniport OAuth2 91 | ------------------------------------------ 92 | 93 | If the user clicks approves the app to access their data on the previous screen, 94 | OAuth2 will redirect the user to the ``REDIRECT_URI`` specified earlier with a code 95 | parameter, any state passed to the authorisation URL will be forwarded to 96 | ``REDIRECT_URI``. 97 | 98 | :: 99 | 100 | REDIRECT_URI?code=AUTHORISATION_CODE 101 | <&state=RANDOM_STATE_STRING> 102 | 103 | This one-time authorisation code has a TTL of 1 minute. So the next step, which 104 | is anyways supposed to be automatic must be done pretty fast. 105 | 106 | Getting the access and refresh token 107 | ------------------------------------ 108 | 109 | Once your application has an authorization 110 | code, it will now need to exchange the authorization code for a pair of access 111 | and refresh tokens from Omniport. 112 | 113 | To get these tokens, you’ll need to make a ``POST`` request to 114 | ``/open_auth/token/`` with the following parameters: 115 | 116 | ============================= =============================================================== 117 | Parameter Description 118 | ============================= =============================================================== 119 | **client_id** (required) The client ID you obtained from the dashboard 120 | **client_secret** (required) The client secret you obtained from the dashboard 121 | **grant_type** (required) ``authorization_code`` as it is 122 | **redirect_uri** (required) One of the redirect URIs you have registered on the dashboard 123 | **code** (required) The authorisation code sent to the REDIRECT_URI 124 | ============================= =============================================================== 125 | 126 | If everything goes right and the request is successful, you’ll receive a 200 127 | response containing a ``JSON`` body like this: 128 | 129 | .. code-block:: json 130 | 131 | { 132 | "access_token": "vqygrcouTuyAYHZLz3rGcZf5FpPd3K", 133 | "expires_in": 36000, 134 | "token_type": "Bearer", 135 | "scope": "read write", 136 | "refresh_token": "BbVJsFL1Ks5LkXDe9ZFUIFvIzXKt9M" 137 | } 138 | 139 | However, if the response is not successful, you’ll receive an error response. 140 | 141 | .. code-block:: json 142 | 143 | { 144 | "error": "some_error_message" 145 | } 146 | 147 | Using the access token 148 | ---------------------- 149 | 150 | Now that you have the access token, you can get the user data by sending a 151 | ``GET`` request to ``/open_auth/get_user_data/`` with the access token in the 152 | header as follows: 153 | 154 | .. code-block:: json 155 | 156 | { 157 | "Authorization": "Bearer vqygrcouTuyAYHZLz3rGcZf5FpPd3K" 158 | } 159 | 160 | where ``vqygrcouTuyAYHZLz3rGcZf5FpPd3K`` is the access token. 161 | 162 | If the access token is valid, then you will receive a 200 response 163 | with a dictionary containing the user's information based on the scopes 164 | of the client app, similar to this: 165 | 166 | .. code-block:: json 167 | 168 | { 169 | "userId": 1234, 170 | "username": "15xxx009", 171 | "person": { 172 | "shortName": "dhruvkb", 173 | "fullName": "Dhruv Kanti Bhanushali", 174 | "roles": [ 175 | { 176 | "role": "Student", 177 | "activeStatus": "ActiveStatus.IS_ACTIVE" 178 | }, 179 | { 180 | "role": "Maintainer", 181 | "activeStatus": "ActiveStatus.IS_ACTIVE" 182 | } 183 | ], 184 | ... 185 | }, 186 | "student": { 187 | "enrolmentNumber": "15xxx009", 188 | ... 189 | }, 190 | "contactInformation": { 191 | "instituteWebmailAddress": "xyz@iitr.ac.in" 192 | ... 193 | } 194 | } 195 | 196 | However, if the access token is invalid, you will receive the following ``401 Unauthorized`` error response. 197 | 198 | .. code-block:: 199 | 200 | { 201 | "detail": "Authentication credentials were not provided." 202 | } 203 | 204 | Generating new access token using refresh token 205 | ------------------------------------ 206 | 207 | The access token has a short lifetime of **36000 seconds**. If it expires, you'll need to generate new 208 | tokens either by re-authenticating the user or using the refresh token. 209 | 210 | To generate these new tokens, you’ll need to make a ``POST`` request to 211 | ``/open_auth/token/`` with the following parameters: 212 | 213 | ============================= =============================================================== 214 | Parameter Description 215 | ============================= =============================================================== 216 | **client_id** (required) The client ID you obtained from the dashboard 217 | **client_secret** (required) The client secret you obtained from the dashboard 218 | **grant_type** (required) ``refresh_token`` as it is 219 | **refresh_token** (required) The refresh token received in exchange of authorization code. 220 | ============================= =============================================================== 221 | 222 | The newly created tokens were successfully generated if you get a 200 response. The "JSON" response body will appear as follows: 223 | 224 | .. code-block:: json 225 | 226 | { 227 | "access_token": "cjlgnpwhfuyAYHZLz3rGcZf5FpPd3K", 228 | "expires_in": 36000, 229 | "token_type": "Bearer", 230 | "scope": "read write", 231 | "refresh_token": "NhdwsFL1Ks5LkXDe9ZFUIFvIzXKt9M" 232 | } 233 | 234 | You will get an error response, though, if the response is unsuccessful. 235 | 236 | .. code-block:: json 237 | 238 | { 239 | "error": "some_error_message" 240 | } 241 | 242 | Logging out the user 243 | ------------------------------------ 244 | 245 | You can revoke the tokens to bar access when the user logs out. 246 | 247 | To revoke the access and refresh token, you’ll need to make a ``POST`` request to ``/open_auth/revoke_token/`` 248 | with the following parameters: 249 | 250 | ============================== =============================================================== 251 | Parameter Description 252 | ============================== =============================================================== 253 | **client_id** (required) The client ID you obtained from the dashboard 254 | **client_secret** (required) The client secret you obtained from the dashboard 255 | **token** (required) The access/refresh token you wish to revoke 256 | **token_type_hint** (required) ``access_token`` or ``refresh_token`` 257 | ============================== =============================================================== 258 | 259 | Future plans 260 | ------------ 261 | 262 | As of now the OAuth2 flow supports only the ``authorisation_code`` grant type 263 | in the flow. This will eventually be expanded to support most if not all of the 264 | multitude of flows backed by the OAuth2 specification. 265 | 266 | Further reading 267 | --------------- 268 | 269 | You should read the `official OAuth docs 270 | `_ for more 271 | theoretical information on OAuth2 and its many loosely-regulated forms. 272 | 273 | For additional information on the parameters refer to the `documentation 274 | `_ of the Django OAuth 275 | Toolkit PyPI package. -------------------------------------------------------------------------------- /docs/source/how_to/write_logs.rst: -------------------------------------------------------------------------------- 1 | ... write logs? 2 | =============== 3 | 4 | A developer's got to write logs. When things break down, when errors pop up and 5 | when something is off, we refer to logs to comprehend what's happening. 6 | 7 | But for there to be logs, one needs to write logging in one's app. Here's how 8 | to do just that. 9 | 10 | Getting a logger 11 | ---------------- 12 | 13 | To write logs, start by getting a logger instance. This can be achieved in one 14 | line of code. 15 | 16 | .. code-block:: python 17 | 18 | import logging 19 | 20 | logger = logging.getLogger(__name__) 21 | 22 | The value of ``__name__`` here is a dot separate path upto the current file. In 23 | a file named ``hello.py`` inside the module ``views`` inside the app 24 | ``application``, it's value is ``application.views.hello``. 25 | 26 | Omniport has been configured to automatically configure loggers and handlers via 27 | Discovery. Each discovered app has a dedicated logger, configured to work with 28 | two handlers: ``console`` (only active during development and debugging) and one 29 | named after the app (only active in production). 30 | 31 | The latter of the two writes logs to file, rotated every midnight keeping the 32 | last 32 days (nearly a month, except 32 = 2\ :sup:`5` which is a cool number). 33 | 34 | Back to the point, all of it happens in the background, like magic, so there's 35 | very little to do on your part. 36 | 37 | Writing logs 38 | ------------ 39 | 40 | Writing logs is easy as well. 41 | 42 | .. code-block:: python 43 | 44 | logger.critical('This is a critical message!!') 45 | logger.error('This is an error message!') 46 | 47 | logger.warning('This is a warning message') 48 | logger.info('This is an info message') 49 | 50 | logger.debug('This is a debug message that no handler will catch') 51 | 52 | That's practically all there is to it. -------------------------------------------------------------------------------- /docs/source/index.rst: -------------------------------------------------------------------------------- 1 | Omniport 2 | ======== 3 | 4 | Omniport is a portal for educational institutes, designed from the ground up to 5 | be extensible, customizable, performant and powerful. 6 | 7 | .. figure:: /_static/site/op_wordmark.png 8 | :target: / 9 | :height: 49px 10 | :align: center 11 | :alt: Omniport wordmark 12 | 13 | The very classy Omniport wordmark, designed by `Kunal Satpal `_ 14 | 15 | Omniport also comes with a powerful collection of apps and is simple enough for 16 | you to be able to write your own. It's legit magic. Pure, unadulterated magic. 17 | 18 | This documentation walks you through the Omniport project. It explains its 19 | philosophy and its features. It explains the technologies involved in the 20 | project and the ways in which this project can make your institute more 21 | technologically equipped than it is. 22 | 23 | It also explains how yo can pitch in and support its continued development and 24 | upgradation. It explains how you can contribute code, design, documentation, 25 | buzz or traffic to the project. 26 | 27 | Lastly but most importantly, it explains what it can do for you and what you can 28 | do with it. 29 | 30 | *Happy development!* 31 | 32 | .. toctree:: 33 | :maxdepth: 2 34 | 35 | introduction/index 36 | structure/index 37 | environments/index 38 | setting_up/index 39 | how_to/index 40 | references/index 41 | legal/index 42 | credits 43 | 44 | Music ♪ 45 | ------- 46 | 47 | If Omniport was a symphony, which it is if you look closely enough, the setup 48 | would be this. 49 | 50 | :Composers: 51 | | `Dhruv Bhanushali `_ 52 | | `Praduman Goyal `_ 53 | :Orchestra: 54 | | `Information Management Group `_, 55 | | `IIT Roorkee `_ 56 | -------------------------------------------------------------------------------- /docs/source/introduction/features.rst: -------------------------------------------------------------------------------- 1 | Features 2 | ======== 3 | 4 | Omniport prides itself on its impressive and rich feature set. This includes the 5 | following non-exhaustive list. 6 | 7 | Code quality 8 | ------------ 9 | 10 | - **Idiomatic Python (Django) and JavaScript (React)** 11 | 12 | The entire codebase is written keeping in mind all the philosophies of 13 | Python and Django, class-based views and all as well as JavaScript and React, 14 | class-based components and all. 15 | 16 | - **PEP8 compliant** 17 | 18 | All the postulates of PEP8 have been satisfied, from the sane rules to the 19 | preposterous 80 character limit. 20 | 21 | - **StandardJS compliant** 22 | 23 | All the postulates of Standard have been satisfied, from the sane rules to the 24 | preposterous no semicolon rule. 25 | 26 | - **Completely documented** 27 | 28 | Even the most basic and obvious functions and classes have been documented 29 | amply, as this documentation testifies. 30 | 31 | Cutting-edge 32 | ------------ 33 | 34 | - **Modern technological stack** 35 | 36 | A consistent JSON API by Django REST framework on the backend powers a 37 | single-page React application on the frontend. 38 | 39 | - **Cutting-edge technology** 40 | 41 | Hope the devs are OK with bleeding because Omniport rolls with the latest 42 | in technology as evident from the stack. 43 | 44 | - **Containers** 45 | 46 | Docker containers ensure an easy set up and also the peace of mind that 47 | there will never be surprises in production. 48 | 49 | Ideals 50 | ------ 51 | 52 | - **Flexibility** 53 | 54 | The entire project consists of mix-and-match, plug-and-play, 55 | load-and-forget components that work independently but better together. 56 | 57 | - **Power** 58 | 59 | Almost any and every feature that you could possibly think of, and then 60 | some, have been baked in and well integrated. 61 | 62 | - **Minimalism** 63 | 64 | The entire project is very minimal and is totally devoid of bloat or 65 | unwanted software. We call it lean. 66 | 67 | - **Simplicity** 68 | 69 | Almost the entire project can be configured via external YAML and ENV files 70 | without touching a single line of code. 71 | 72 | - **Open-source** 73 | 74 | From the tech stack to the dependencies, Omniport is built on open-source. It 75 | only makes sense to give back to the wonderful community. 76 | -------------------------------------------------------------------------------- /docs/source/introduction/index.rst: -------------------------------------------------------------------------------- 1 | Introduction 2 | ============ 3 | 4 | Omniport, as mentioned countless times, is a portal designed to make the lives 5 | of every stakeholder in an educational institute easier. From the students 6 | to the administration, Omniport is a simple way to usher your institute into 7 | the digital age. 8 | 9 | Read on to know what Omniport is all about. 10 | 11 | .. toctree:: 12 | :caption: Subsections: 13 | 14 | philosophy 15 | features 16 | the_stack -------------------------------------------------------------------------------- /docs/source/introduction/philosophy.rst: -------------------------------------------------------------------------------- 1 | Philosophy 2 | ========== 3 | 4 | When we set out to build Omniport, we had a bunch of things in mind. Vaguely 5 | speaking, it had to be epic and had to blow everyone's mind off. 6 | 7 | After a lot of thinking, some clarity. It had to be poetic. It had to evoke in 8 | the readers a love that they never thought they could experience again, a love 9 | so powerful it would compel them to cheat on their language of preference with 10 | Python, to switch to Django from PHP (or even Ruby on Rails, for that matter). 11 | On the frontend, there never was an real contender to React anyway. 12 | 13 | The zen of Omniport 14 | ------------------- 15 | 16 | In a fashion similar to Python's, here is a zen poem that somewhat guides the 17 | decisions behind Omniport. 18 | 19 | | **Don't repeat yourself.** 20 | Ever. Ever. Oh wait, my bad. Sorry. 21 | | **Focus on the essential.** 22 | Everything else, like this sentence, is irrelevant. 23 | | **Bike-shedding is the best way to annihilate time.** 24 | Let's discuss button colours. 25 | | **Roles are just temporary hats people wear.** 26 | Apps put personae on roles. 27 | | **Generalised is better than hard-coded.** 28 | Customisable is better than generalised. 29 | | **Development should be exciting.** 30 | Deployment should not. 31 | 32 | Significance 33 | ------------ 34 | 35 | The zen of Omniport, in addition to PEP8, StandardJS, and our own code style, is 36 | the driving force behind our development. Any pull request, even one of the 37 | smallest ones, that takes the code towards a state with higher compliance with 38 | the above zen shall be considered worthy of merge. -------------------------------------------------------------------------------- /docs/source/introduction/the_stack.rst: -------------------------------------------------------------------------------- 1 | The stack 2 | ========= 3 | 4 | Unless otherwise specified, Omniport runs on the latest versions of all the 5 | components in the stack. This means that there is no LTS version or long-term 6 | release and Omniport is always a rolling distribution. 7 | 8 | +-----------------------+-----------------------+-----------------------+ 9 | | Sphere | Sub-sphere | Technology | 10 | +=======================+=======================+=======================+ 11 | | **Orchestration** | *Containers* | Docker | 12 | +-----------------------+-----------------------+-----------------------+ 13 | | **NoSQL databases** | *Sessions* | Redis | 14 | + +-----------------------+-----------------------+ 15 | | | *Communications* | Redis | 16 | + +-----------------------+-----------------------+ 17 | | | *Channels* | Redis | 18 | + +-----------------------+-----------------------+ 19 | | | *Temporary app* | Redis | 20 | + +-----------------------+-----------------------+ 21 | | | *GUI* | Redis Commander | 22 | +-----------------------+-----------------------+-----------------------+ 23 | | **SQL database** | *Application* | PostgreSQL | 24 | + +-----------------------+-----------------------+ 25 | | | *Library* | Psycopg2 | 26 | +-----------------------+-----------------------+-----------------------+ 27 | | **Cache** | *Application* | Memcached | 28 | +-----------------------+-----------------------+-----------------------+ 29 | | **Message broker** | *Application* | RabbitMQ | 30 | + +-----------------------+-----------------------+ 31 | | | *Library* | Celery | 32 | +-----------------------+-----------------------+-----------------------+ 33 | | **Reverse proxy** | *Application* | NGINX | 34 | +-----------------------+-----------------------+-----------------------+ 35 | | **Backend** | *Language* | Python | 36 | + +-----------------------+-----------------------+ 37 | | | *Framework* | Django | 38 | + +-----------------------+-----------------------+ 39 | | | *WSGI server* | Gunicorn | 40 | + +-----------------------+-----------------------+ 41 | | | *ASGI server* | Daphne | 42 | +-----------------------+-----------------------+-----------------------+ 43 | | **Frontend** | *Language* | JavaScript | 44 | + +-----------------------+-----------------------+ 45 | | | *Framework* | React | 46 | + +-----------------------+-----------------------+ 47 | | | *Transpiler* | Babel | 48 | + +-----------------------+-----------------------+ 49 | | | *Bundler* | Webpack | 50 | +-----------------------+-----------------------+-----------------------+ 51 | 52 | - Tier I (no dependencies on other infrastructure) 53 | 54 | - Message broker 55 | - Channel layer 56 | - Session store 57 | - Notification store 58 | - Application store 59 | - Database 60 | - Cache 61 | 62 | - Tier II (depend on and wait for Tier I to be ready) 63 | 64 | - Intranet server 65 | - Internet server 66 | - Redis GUI 67 | 68 | - Tier III (depend on and wait for Tier II to be ready) 69 | 70 | - Reverse proxy 71 | -------------------------------------------------------------------------------- /docs/source/legal/brand_usage_guide/index.rst: -------------------------------------------------------------------------------- 1 | Brand usage guide 2 | ================= 3 | 4 | This document guides on the use of the logos and brand imagery of both Omniport 5 | and the Information Management Group. 6 | 7 | All branding assets are available on GitHub. Feel free to use them when 8 | referring to Omniport or to IMG. Your use of these branding assets is subject 9 | to a few basic rules. 10 | 11 | Read on to understand what these rules are. 12 | 13 | .. toctree:: 14 | :maxdepth: 2 15 | 16 | omniport 17 | information_management_group -------------------------------------------------------------------------------- /docs/source/legal/brand_usage_guide/information_management_group.rst: -------------------------------------------------------------------------------- 1 | Information Management Group 2 | ============================ 3 | 4 | Typography 5 | ---------- 6 | 7 | The font used in the logotype is Bauhaus. 8 | 9 | Textual use 10 | ----------- 11 | 12 | In all texts, the name must be typed as Information Management Group or IMG. If 13 | using the logotype, the name must be stylised as information management group. 14 | 15 | Logo usage 16 | ---------- 17 | 18 | .. note:: 19 | 20 | All ``em`` units are on a ``16px`` baseline. 21 | 22 | .. figure:: /_static/maintainers/img_logo.png 23 | :figwidth: 100% 24 | :height: 48px 25 | :align: center 26 | :alt: Information Management Group logo 27 | 28 | Information Management Group logo at ``3em`` 29 | 30 | .. figure:: /_static/maintainers/img_wordmark.png 31 | :figwidth: 100% 32 | :height: 48px 33 | :align: center 34 | :alt: Information Management Group wordmark 35 | 36 | Information Management Group wordmark at ``3em`` 37 | 38 | Clear spacing 39 | +++++++++++++ 40 | 41 | To maintain logo sovereignty, we require the logo to have a minimum spacing 42 | of ``1em`` on all sides at height of ``3em`` around it. 43 | 44 | Size 45 | ++++ 46 | 47 | To maintain logo legibility the logo should never be scaled lower than 48 | ``1.5em``.This may vary but you have to use your sensibilities. 49 | 50 | Proportions 51 | +++++++++++ 52 | 53 | The logo must always be scaled so as to maintain the proportions and aspect 54 | ratio. That's usually achieved by using the ``Shift`` key. 55 | 56 | Background 57 | ++++++++++ 58 | 59 | The logo must always be used on a background where it can stand out. Extremely 60 | detailed and colourful backgrounds are not recommended. Only in the cases where 61 | your background has a palette similar to the logo, you are to use our grayscale 62 | variant. 63 | 64 | Alterations 65 | +++++++++++ 66 | 67 | You are not to alter the logo in terms of color, shape, shadows, borders, 68 | typeface or tilt. Our designers put a lot of love into it. Respect that. 69 | -------------------------------------------------------------------------------- /docs/source/legal/brand_usage_guide/omniport.rst: -------------------------------------------------------------------------------- 1 | Omniport 2 | ======== 3 | 4 | Typography 5 | ---------- 6 | 7 | The font used in the logotype is Raleway. 8 | 9 | Textual use 10 | ----------- 11 | 12 | In all texts, the name must be typed as Omniport. If using the logotype, the 13 | name must be stylised as omni:port. 14 | 15 | Logo usage 16 | ---------- 17 | 18 | .. note:: 19 | 20 | All ``em`` units are on a ``14px`` baseline. 21 | 22 | .. figure:: /_static/site/op_logo.png 23 | :figwidth: 100% 24 | :height: 49px 25 | :align: center 26 | :alt: Omniport logo 27 | 28 | Omniport logo at ``3.5em`` 29 | 30 | .. figure:: /_static/site/op_wordmark.png 31 | :figwidth: 100% 32 | :height: 49px 33 | :align: center 34 | :alt: Omniport wordmark 35 | 36 | Omniport wordmark at ``3.5em`` 37 | 38 | Clear spacing 39 | +++++++++++++ 40 | 41 | To maintain logo sovereignty, we require the logo to have a minimum spacing 42 | of ``1em`` on all sides at height of ``3.5em`` around it. 43 | 44 | Size 45 | ++++ 46 | 47 | To maintain logo legibility the logo should never be scaled lower than 48 | ``1.75em``. This may vary but you have to use your sensibilities. 49 | 50 | Proportions 51 | +++++++++++ 52 | 53 | The logo must always be scaled so as to maintain the proportions and aspect 54 | ratio. That's usually achieved by using the ``Shift`` key. 55 | 56 | Background 57 | ++++++++++ 58 | 59 | The logo must always be used on a background where it can stand out. Extremely 60 | detailed and colourful backgrounds are not recommended. Only in the cases where 61 | your background has a palette similar to the logo, you are to use our grayscale 62 | variant. 63 | 64 | Alterations 65 | +++++++++++ 66 | 67 | You are not to alter the logo in terms of color, shape, shadows, borders, 68 | typeface or tilt. Our designers put a lot of love into it. Respect that. 69 | -------------------------------------------------------------------------------- /docs/source/legal/index.rst: -------------------------------------------------------------------------------- 1 | Legal 2 | ===== 3 | 4 | The use of Omniport as a user, a developer and/or as a local instance maintainer 5 | is bound by a number of rules. This section is devoted to explicitly outlining 6 | these terms. 7 | 8 | Do note that above and beyond all these rules is a rule of ethics that we are 9 | all bound by as developers, sharing code and knowledge in the fair market that 10 | is open-source. 11 | 12 | .. toctree:: 13 | :maxdepth: 2 14 | 15 | privacy_policy 16 | developer_terms_of_use 17 | brand_usage_guide/index 18 | open_source -------------------------------------------------------------------------------- /docs/source/legal/open_source.rst: -------------------------------------------------------------------------------- 1 | Open-source 2 | =========== 3 | 4 | Omniport is a product of, runs on, and therefore is, open-source. All aspects 5 | of Omniport, *including this documentation for some reason*, are licensed under 6 | the GNU licenses. 7 | 8 | Omniport ❤️ FOSS 9 | 10 | GNU General Public License version 3 11 | ------------------------------------ 12 | 13 | .. figure:: /_static/licenses/gnu_gplv3.png 14 | :figwidth: 100% 15 | :height: 51px 16 | :align: center 17 | :alt: GNU GPLv3 logo 18 | 19 | All code is licensed under GNU GPLv3. 20 | 21 | All code pertaining to Omniport, including but not limited to its core, its 22 | services and apps ecosystem and snippets thereof is licensed under the GNU 23 | General Public License or GPL. The license can be read in its entirety on the 24 | `GPL page on the GNU website `_. 25 | 26 | GNU Free Documentation License 27 | ------------------------------ 28 | 29 | .. figure:: /_static/licenses/gnu_fdl.png 30 | :figwidth: 100% 31 | :height: 44px 32 | :align: center 33 | :alt: GNU FDL logo 34 | 35 | All documentation is licensed under GNU FDL. 36 | 37 | All documentation pertaining to Omniport, including but not limited to this 38 | manual, excerpts thereof and other technical articles, is licensed under the GNU 39 | Free Documentation License or FDL. The license can be read in its entirety on 40 | the `FDL page on the GNU website `_. 41 | 42 | Other licenses 43 | -------------- 44 | 45 | We don't really understand how license cascading works but we sure do hope that 46 | Omniport does not violate the licenses of any of its dependencies. All 47 | dependencies of Omniport retain their individual licenses and Omniport does not 48 | in any way overrule the licensing of any of its dependencies, or dependencies 49 | thereof. 50 | 51 | If you get how licensing and the cascading of licensing works, feel free to get 52 | in touch. If Omniport is in violation of any terms of its dependencies' 53 | licenses, please bring this to our notice. We'll be happy to resolve it. -------------------------------------------------------------------------------- /docs/source/legal/privacy_policy.rst: -------------------------------------------------------------------------------- 1 | Privacy policy 2 | ============== 3 | 4 | The privacy policy of Omniport is still being drafted. Please be patient. -------------------------------------------------------------------------------- /docs/source/references/config_files/app/config_json.rst: -------------------------------------------------------------------------------- 1 | ``config.json`` on the frontend 2 | =============================== 3 | 4 | Purposes 5 | -------- 6 | 7 | ``config.json`` is one important pillar of Omniport's plug-and-play architecture. 8 | It primarily serves the following three purposes. 9 | 10 | These configuration files are used to generate ``omniport\core\configs.json`` 11 | and ``omniport\core\primarySidebarConfigs.json`` which can be used in your apps. 12 | 13 | Nomenclature 14 | ++++++++++++ 15 | 16 | The nomenclature part of the config file is used to define the internal and 17 | display name of the app, which in turn, defines app nomenclature all around the 18 | code. It requires the ``nomenclature`` key to be defined in ``config.json``. 19 | 20 | :nomenclature: 21 | | Nomenclature related fields of an app. 22 | | ``{object}`` which has the following subkeys 23 | 24 | :name: 25 | | The name that is used internally to refer to an app. 26 | | ``string`` 27 | 28 | :verboseName: 29 | | The display name of the app with spaces and proper punctuation. 30 | | ``string`` 31 | 32 | Dynamic routes 33 | ++++++++++++++ 34 | 35 | ``omniport/core/configs.json`` created during build using ``discovery.js`` is 36 | used to create dynamic ``Route`` component which act as an entry point in 37 | Omniport for the service or app. It requires two keys in config i.e. ``baseUrl`` 38 | and ``source``. 39 | 40 | :baseUrl: 41 | | The URL on which app has to be rendered. 42 | | ``string`` 43 | :source: 44 | | The source to the ``index.js`` file of the app relative to the ``omniport`` 45 | directory. 46 | | ``string`` 47 | 48 | Sidebar configuration 49 | +++++++++++++++++++++ 50 | 51 | .. note:: 52 | 53 | This section only applies to services. 54 | 55 | ``discovery.js`` also creates ``omniport/core/primarySidebarConfigs.json`` using 56 | config files in sub-folders of services. This ``primarySidebarConfigs.json``, as 57 | the name suggests is used to create the sidebar the appears in Omniport core. 58 | This functionality allows Omniport to pin some of services to the sidebar at a 59 | position determined by its priority. 60 | 61 | :primarySidebar: 62 | | primarySidebar related fields of a service. 63 | | ``{object}`` which has the following subkeys. 64 | 65 | :icon: 66 | | The name of the icon from the collection provided by 67 | `Semantic UI `_. 68 | | ``string`` 69 | :priority: 70 | | Defines the placement of the button in the sidebar. 71 | | Services with higher priority appear higher in the sidebar. 72 | | If not provided, it is assumed ~infinite. 73 | | If two services have the same priority, they are sorted lexicographically. 74 | | ``integer`` 75 | 76 | Examples 77 | -------- 78 | 79 | Service 80 | +++++++ 81 | 82 | An example ``config.json`` for a service **having its button** in sidebar can be as 83 | follows. 84 | 85 | .. code-block:: json 86 | 87 | { 88 | "nomenclature": { 89 | "name": "developer", 90 | "verboseName": "Developer" 91 | }, 92 | "baseUrl": "/developer", 93 | "source": "developer/src/index", 94 | "primarySidebar": { 95 | "icon": "code", 96 | "priority": 6 97 | } 98 | } 99 | 100 | ----- 101 | 102 | An example ``config.json`` for a service, which **doesn't require its button** 103 | in sidebar can be as follows. 104 | 105 | .. code-block:: json 106 | 107 | { 108 | "nomenclature": { 109 | "name": "auth", 110 | "verboseName": "Auth" 111 | }, 112 | "baseUrl": "/auth", 113 | "source": "auth/src/index" 114 | } 115 | 116 | App 117 | +++ 118 | 119 | An example ``config.json`` for an app can be as follows. 120 | 121 | .. code-block:: json 122 | 123 | { 124 | "nomenclature": { 125 | "name": "placement_and_internship", 126 | "verboseName": "Placement and Internship" 127 | }, 128 | "baseUrl": "/placement_and_internship", 129 | "source": "placement_and_internship/src/index" 130 | } 131 | -------------------------------------------------------------------------------- /docs/source/references/config_files/app/config_yml.rst: -------------------------------------------------------------------------------- 1 | ``config.yml`` on the backend 2 | ============================= 3 | 4 | Purposes 5 | -------- 6 | 7 | ``config.yml`` is the crux of Omniport's plug-and-play architecture. It 8 | primarily serves the following purposes. 9 | 10 | These configurations are processed by the modules ``discovery`` and 11 | ``configuration`` and their processed data can be accessed as follows. 12 | 13 | .. code-block:: python 14 | 15 | from django.conf import settings 16 | 17 | DISCOVERY = settings.DISCOVERY 18 | 19 | ... # Do something with DISCOVERY 20 | 21 | This ``DISCOVERY`` object of ``class Discovery`` contains the fields 22 | ``service_configuration_map`` and ``app_configuration_map`` which can be used in 23 | your apps. 24 | 25 | Nomenclature 26 | ++++++++++++ 27 | 28 | The nomenclature part of the config file is used to define the internal and 29 | display name of the app, which in turn, defines the app nomenclature all around 30 | the code. It requires the ``nomenclature`` key to be defined in ``config.yml``. 31 | 32 | :nomenclature: 33 | | Nomenclature related fields of an app 34 | | ``{object}`` which has the following subkeys 35 | 36 | :name: 37 | | The name that is used internally to refer to an app 38 | | ``string`` 39 | 40 | :verboseName: 41 | | The display name of the app with spaces and proper punctuation 42 | | ``string`` 43 | 44 | Description 45 | +++++++++++ 46 | 47 | This is the short app description that populates a number of places where the 48 | app description is shown such as on the ``apps/`` page of service ``apps``. 49 | 50 | :description: 51 | | A brief description of the app 52 | | ``string`` 53 | 54 | Is API 55 | ++++++ 56 | 57 | This boolean field toggles whether the root URL of the app must be at ``/`` or 58 | at ``/api/``. For all modern apps, this field must be set to ``true``. 59 | 60 | Only legacy apps or special apps that need to run from the root URL path must 61 | set this field to false. 62 | 63 | :isApi: 64 | | Decides whether the app is an API or not 65 | | ``boolean`` set to ``true`` 66 | 67 | Acceptables 68 | +++++++++++ 69 | 70 | .. note:: 71 | 72 | This section only applies to apps. 73 | 74 | The modules ``discovery`` and ``configuration`` while processing the config 75 | files also determine the various target demographics for any given app. The 76 | ``acceptables`` key defines just that. The filters can be applied on the basis 77 | of user roles, their corresponding active statuses and the IP address of the 78 | request's origin. 79 | 80 | This means that different users, having different roles, coming from different 81 | IP address rings will be able to see different apps. 82 | 83 | :acceptables: 84 | | The filters deciding the target demographic of an app 85 | | ``{object}`` which has the following subkeys 86 | 87 | :ipAddressRings: 88 | | The list of strings naming the IP address rings this app will serve 89 | | Should be a subset of ``ipAddressRings`` defined in ``base.yml``. 90 | | ``[string]`` 91 | 92 | :roles: 93 | | The roles this app will serve 94 | | ``[{object}]`` where each has the following subkeys 95 | 96 | :name: 97 | | The name of any allowed role 98 | | Should be one of the roles defined in the ``kernel`` module. 99 | | ``string`` such as ``'Student'`` or ``'FacultyMember'`` 100 | 101 | :activeStatuses: 102 | | The active statuses this app will serve 103 | | Should be one of the following. 104 | | ``IS_ACTIVE`` 105 | | ``IS_INACTIVE`` 106 | | ``HAS_BEEN_ACTIVE`` 107 | | ``WILL_BE_ACTIVE`` 108 | | ``[string]`` where each string is one of the above values. 109 | 110 | Examples 111 | -------- 112 | 113 | Service 114 | +++++++ 115 | 116 | An example ``config.yml`` for a service can be as follows. 117 | 118 | .. code-block:: yaml 119 | 120 | nomenclature: 121 | name: apps 122 | verboseName: Apps 123 | description: Find all the apps that make up Omniport 124 | baseUrls: 125 | http: apps/ 126 | isApi: true 127 | 128 | App 129 | +++ 130 | 131 | An example ``config.yml`` for an app that allows active maintainers to reset 132 | people's passwords from within their workplace can be as follows. 133 | 134 | .. code-block:: yaml 135 | 136 | nomenclature: 137 | name: alohomora 138 | verboseName: Alohomora 139 | description: Reset passwords, no-questions asked 140 | baseUrls: 141 | http: alohomora/ 142 | static: alohomora/ 143 | acceptables: 144 | ipAddressRings: 145 | - self 146 | - specifics 147 | - maintainers 148 | roles: 149 | - name: Maintainer 150 | activeStatuses: 151 | - IS_ACTIVE 152 | isApi: true 153 | 154 | ----- 155 | 156 | An example ``config.yml`` targeting alumni, and alumnae, living anywhere in the 157 | world can be as follows. 158 | 159 | .. code-block:: yaml 160 | 161 | nomenclature: 162 | name: alumni_connect 163 | verboseName: Alumni connect 164 | description: Talk to alumni and learn from their experience 165 | baseUrls: 166 | http: alumni_connect/ 167 | static: alumni_connect/ 168 | acceptables: 169 | roles: 170 | - name: Student 171 | activeStatuses: 172 | - HAS_BEEN_ACTIVE 173 | isApi: true 174 | 175 | -------------------------------------------------------------------------------- /docs/source/references/config_files/app/index.rst: -------------------------------------------------------------------------------- 1 | App configuration 2 | ================= 3 | 4 | App configuration files are one file each on the backend and frontend that 5 | collectively make up the customisation framework on the app level. 6 | 7 | Read on to find the various aspects of an app that you can customise. 8 | 9 | .. toctree:: 10 | :caption: Subsections: 11 | :maxdepth: 2 12 | 13 | config_yml 14 | config_json -------------------------------------------------------------------------------- /docs/source/references/config_files/index.rst: -------------------------------------------------------------------------------- 1 | Configuration files 2 | =================== 3 | 4 | Configuration files are the heart and soul of Omniport. At the core of 5 | Omniport's flexibility and customisability is a set of configuration files which 6 | are either convenient YAML files on the backend or natively parseable JSON files 7 | on the frontend. 8 | 9 | Read on to know more about these assortment of files and the various aspects of 10 | Omniport they control in order to tweak Omniport exactly to your needs. 11 | 12 | .. toctree:: 13 | :caption: Subsections: 14 | :maxdepth: 2 15 | 16 | project/index 17 | app/index -------------------------------------------------------------------------------- /docs/source/references/config_files/project/base_yml.rst: -------------------------------------------------------------------------------- 1 | ``base.yml`` on the backend 2 | =========================== 3 | 4 | Purposes 5 | -------- 6 | 7 | ``base.yml`` is the top-level of customisation that can be achieved with 8 | Omniport. The values specified here determine a lot of things about how Omniport 9 | behaves and responds. 10 | 11 | Branding 12 | ++++++++ 13 | 14 | The branding part of the config file is used to define the branding of the 15 | Omniport project, mainly the textual aspect of branding. It requires the 16 | ``branding`` key to be defined in ``base.yml``. 17 | 18 | :branding: 19 | | Branding related fields of the project 20 | | ``{object}`` which has the following subkeys 21 | 22 | :institute: 23 | | Attributes pertaining to the brand of the institute hosting the portal 24 | | ``{object}`` which has the following subkeys 25 | 26 | :acronym: 27 | | Acronyms of institutes which have long names 28 | | ``string`` 29 | 30 | :name: 31 | | The full name of the institute 32 | | ``string`` 33 | 34 | :homePage: 35 | | The URL to the home page of the institute on the web 36 | | ``string`` 37 | 38 | :maintainers: 39 | | Attributes pertaining to the brand of the maintainers behind the portal 40 | | ``{object}`` which has the following subkeys 41 | 42 | :acronym: 43 | | Acronyms of maintainer groups which have long names 44 | | ``string`` 45 | 46 | :name: 47 | | The full name of the maintainer group 48 | | ``string`` 49 | 50 | :homePage: 51 | | The URL to the home page of the maintainer group on the web 52 | | ``string`` 53 | 54 | Internationalisation 55 | ++++++++++++++++++++ 56 | 57 | The internationalisation part of the config file is simply to customise the 58 | language and timezone of the project. 59 | 60 | :i18n: 61 | | Internationalisation related fields of the project 62 | | ``{object}`` which has the following subkeys 63 | 64 | :languageCode: 65 | | The languge code of the portal 66 | | ``string`` 67 | 68 | :timeZone: 69 | | The languge code of the portal 70 | | ``string`` 71 | 72 | Secrets 73 | +++++++ 74 | 75 | Secrets pertaining to the Omniport project, such as passwords, client IDs and 76 | most importantly the Django secret key go here. 77 | 78 | :secrets: 79 | | Secrets of the Omniport project 80 | | ``{object}`` which has the following subkeys 81 | 82 | :secretKey: 83 | | The Django secret key of the project 84 | | ``string`` 85 | 86 | Services 87 | ++++++++ 88 | 89 | As Omniport depends on a lot of services for optimum functioning, we made a 90 | Docker project to make the setup easy. If you use the Docker project, a lot of 91 | these settings have to be their default values as shown in the 92 | ``base_stencil.yml`` file. If you have tweaked them, fill these sections out. 93 | 94 | :services: 95 | | Credentials to connect to all Omniport dependencies 96 | | ``{object}`` which has the following subkeys 97 | 98 | :database: 99 | | Attributes pertaining to database service 100 | | ``{object}`` which has the following subkeys 101 | 102 | :host: 103 | | The IP/name of the host machine or container running this service 104 | | ``string`` 105 | 106 | :port: 107 | | The port on which the service can be reached 108 | | ``integer`` 109 | 110 | :user: 111 | | The username that can be used to log in to the service 112 | | ``string`` 113 | 114 | :password: 115 | | The password for the given user 116 | | ``string`` 117 | 118 | :name: 119 | | The name of the database to use 120 | | ``string`` 121 | 122 | :messageBroker: 123 | | Attributes pertaining to message broker service 124 | | ``{object}`` which has the following subkeys 125 | 126 | :host: 127 | | The IP/name of the host machine or container running this service 128 | | ``string`` 129 | 130 | :port: 131 | | The port on which the service can be reached 132 | | ``integer`` 133 | 134 | :user: 135 | | The username that can be used to log in to the service 136 | | ``string`` 137 | 138 | :password: 139 | | The password for the given user 140 | | ``string`` 141 | 142 | :channelLayer: 143 | | Attributes pertaining to Redis container supporting Django Channels 144 | | ``{object}`` which has the following subkeys 145 | 146 | :host: 147 | | The IP/name of the host machine or container running this service 148 | | ``string`` 149 | 150 | :port: 151 | | The port on which the service can be reached 152 | | ``integer`` 153 | 154 | :sessionStore: 155 | | Attributes pertaining to Redis container storing sessions 156 | | ``{object}`` which has the following subkeys 157 | 158 | :host: 159 | | The IP/name of the host machine or container running this service 160 | | ``string`` 161 | 162 | :port: 163 | | The port on which the service can be reached 164 | | ``integer`` 165 | 166 | :communicationStore: 167 | | Attributes pertaining to Redis container storing communications 168 | | ``{object}`` which has the following subkeys 169 | 170 | :host: 171 | | The IP/name of the host machine or container running this service 172 | | ``string`` 173 | 174 | :port: 175 | | The port on which the service can be reached 176 | | ``integer`` 177 | 178 | :verificationStore: 179 | | Attributes pertaining to Redis container storing verifications 180 | | ``{object}`` which has the following subkeys 181 | 182 | :host: 183 | | The IP/name of the host machine or container running this service 184 | | ``string`` 185 | 186 | :port: 187 | | The port on which the service can be reached 188 | | ``integer`` 189 | 190 | :notificationStore: 191 | | Attributes pertaining to Redis container storing notifications 192 | | ``{object}`` which has the following subkeys 193 | 194 | :host: 195 | | The IP/name of the host machine or container running this service 196 | | ``string`` 197 | 198 | :port: 199 | | The port on which the service can be reached 200 | | ``integer`` 201 | 202 | :applicationStore: 203 | | Attributes pertaining to Redis container storing data for omniport 204 | | applications which are temporary in nature 205 | | ``{object}`` which has the following subkeys 206 | 207 | :host: 208 | | The IP/name of the host machine or container running this service 209 | | ``string`` 210 | 211 | :port: 212 | | The port on which the service can be reached 213 | | ``string`` 214 | 215 | :cache: 216 | | Attributes pertaining to the Memcached cache 217 | | ``{object}`` which has the following subkeys 218 | 219 | :host: 220 | | The IP/name of the host machine or container running this service 221 | | ``string`` 222 | 223 | :port: 224 | | The port on which the service can be reached 225 | | ``integer`` 226 | 227 | Integrations 228 | ++++++++++++++++ 229 | 230 | Useful applications that can connect to Django, like `Sentry 231 | `_, can be integrated into the project. 232 | 233 | Emails 234 | ++++++++++++++++ 235 | 236 | The emails part of the config file is used to define settings for sending 237 | emails from your project. 238 | 239 | :emails: 240 | | Email configurations for your project 241 | | ``{object}`` which has the following subkeys 242 | 243 | :emailBackend: 244 | | The backend used for sending emails 245 | | ``string`` 246 | 247 | :emailHost: 248 | | The email service provider used 249 | | ``string`` 250 | 251 | :emailUseTls: 252 | | Whether an email uses a TLS connection or not 253 | | ``boolean`` 254 | 255 | :emailPort: 256 | | The port used by smtp server 257 | | ``integer`` 258 | 259 | :emailHostUser: 260 | | The email address from which all emails will be sent 261 | | ``string`` 262 | 263 | :emailHostPassword: 264 | | The password of the host's email account 265 | | ``string`` 266 | 267 | IP address rings 268 | ++++++++++++++++ 269 | 270 | Omniport being the web portal serves a number of clients on different levels of 271 | the network. There is the server itself, a close cluster of servers working 272 | together, certain cabinet computers that can connect to the server, the lab of 273 | the maintainer group, the intranet and then the Internet at large. 274 | 275 | These clients can be arranged into rings, where the innermost rings have the 276 | highest priority in terms of privilege to access certain APIs and resources. 277 | 278 | These rings are described here, in the ``ipAddressRings`` key. 279 | 280 | :ipAddressRings: 281 | | ``[{object}]`` each of which has the following subkeys 282 | 283 | :name: 284 | | The name of this IP address ring, the identifier for this ring 285 | | ``string`` 286 | 287 | :patterns: 288 | | The regex of the IP pattern that falls in the level 289 | | ``[string]`` 290 | 291 | Examples 292 | -------- 293 | 294 | A fully equipped ``base.yml`` file, with all settings populated looks quite like 295 | this. 296 | 297 | .. code-block:: yaml 298 | 299 | branding: 300 | institute: 301 | acronym: IIT-R 302 | name: Indian Institute of Technology Roorkee 303 | homePage: https://iitr.ac.in/ 304 | maintainers: 305 | acronym: IMG 306 | name: Information Management Group 307 | homePage: https://channeli.in/img/ 308 | i18n: 309 | languageCode: en-gb 310 | timeZone: Asia/Kolkata 311 | secrets: 312 | secretKey: '2)@2klj=@a(*o9kyt7u^!g4jbqrqo3$ju^o_g6n*lh-d$$#zdy' 313 | services: 314 | database: 315 | host: database 316 | port: 5432 317 | user: omniport_user 318 | password: omniport_password 319 | name: omniport_database 320 | channelLayer: 321 | host: channel-layer 322 | port: 6379 323 | sessionStore: 324 | host: session-store 325 | port: 6379 326 | communicationStore: 327 | host: communication-store 328 | port: 6379 329 | verificationStore: 330 | host: verification-store 331 | port: 6379 332 | notificationStore: 333 | host: notification-store 334 | port: 6379 335 | applicationStore: 336 | host: application-store 337 | port: 6379 338 | cache: 339 | host: cache 340 | port: 11211 341 | messageBroker: 342 | host: message-broker 343 | port: 5672 344 | user: omniport_user 345 | password: omniport_password 346 | emails: 347 | emailBackend: 'django.core.mail.backends.smtp.EmailBackend' 348 | emailHost: 'smtp.example.com' 349 | emailUseTls: True 350 | emailPort: 587 351 | emailHostUser: 'no-reply@omniport.com' 352 | emailHostPassword: 'img@password' 353 | ipAddressRings: 354 | - name: self 355 | patterns: 356 | - '^172\.18\.0\.1$' 357 | - name: specifics 358 | patterns: 359 | - '^172\.25\.55\.101$' 360 | - '^172\.25\.55\.219$' 361 | - name: maintainers 362 | patterns: 363 | - '^172\.25\.55\.\d{1}$' 364 | - name: intranet 365 | patterns: 366 | - '.*' 367 | - name: internet 368 | patterns: 369 | - '.*' 370 | -------------------------------------------------------------------------------- /docs/source/references/config_files/project/index.rst: -------------------------------------------------------------------------------- 1 | Project configuration 2 | ===================== 3 | 4 | Omniport allows for a lot of customisability on the project level. In fact, 5 | almost everything about Omniport, including the name, can be changed without 6 | writing or editing a single line of code. We take great pride in this creation 7 | of ours and are always adding more and more items that can be customised 8 | externally. 9 | 10 | Read on to find the various aspects of the Omniport project that you can 11 | customise. 12 | 13 | .. toctree:: 14 | :caption: Subsections: 15 | :maxdepth: 2 16 | 17 | base_yml 18 | site_yml 19 | -------------------------------------------------------------------------------- /docs/source/references/config_files/project/site_yml.rst: -------------------------------------------------------------------------------- 1 | ``site_.yml`` on the backend 2 | ================================ 3 | 4 | Purposes 5 | -------- 6 | 7 | ``site_.yml`` is cascaded onto base-level customisation on a per-site basis. 8 | The values specified here determine a lot of things about how each sub-site of 9 | Omniport behaves and responds. 10 | 11 | You can override the values defined in :doc:`the base config file `. 12 | In addition, there are certain configuration knobs that make sense to be defined 13 | on a site-level, which are explained below. 14 | 15 | Site 16 | ++++ 17 | 18 | Every site in Omniport can be individually customised. 19 | 20 | .. note:: 21 | 22 | So far Omniport has support only for two sites. Work is ongoing to expand this 23 | to as many sites as needed. 24 | 25 | Omniport allows you to customise the name, description as well as the debugging 26 | status of every site in the project. This is accomplished by the ``site`` key in 27 | the config file. 28 | 29 | :site: 30 | | The set of fields for branding a site 31 | | ``{object}`` which has the following subkeys 32 | 33 | :id: 34 | | The unique ID of the site 35 | | ``number`` where 0, 1, 2 denote development, intranet and Internet sites 36 | 37 | :nomenclature: 38 | | The nomenclature pertaining to the site 39 | | ``{object}`` which has the following subkeys 40 | 41 | :name: 42 | | The code name of the site 43 | | ``string`` 44 | 45 | :verboseName: 46 | | The displayed name of the site 47 | | ``string`` 48 | 49 | :debug: 50 | | Whether to display debug info, should be ``false`` on production sites 51 | | ``boolean`` 52 | 53 | :description: 54 | | The description of the site, as an aid to help developers find their way 55 | | ``string`` 56 | 57 | Allowances 58 | ---------- 59 | 60 | Allowances determine what parts of Omniport each site is allowed to access. 61 | Fields such as the names of apps that are allowed on the site and the hostnames 62 | that the site should respond to go here. This section also determines the 63 | network rings each site is allowed on. 64 | 65 | :allowances: 66 | | The set of allowed entities for any given site 67 | | ``{object}`` which has the following subkeys 68 | 69 | :hosts: 70 | | List of domain names that this site is responsible for serving 71 | | ``[string]`` 72 | 73 | :apps: 74 | | List of app names that this site exposes to the users 75 | | ``[string]`` 76 | 77 | :ipAddressRings: 78 | | List of network rings that are served by the site 79 | | These names are ring names from :doc:`the base config file ` 80 | | ``[string]`` 81 | 82 | Examples 83 | -------- 84 | 85 | A site-level configuration for a typical development site ``site_0.yml`` looks 86 | like this. 87 | 88 | .. code-block:: yaml 89 | 90 | site: 91 | id: 0 92 | nomenclature: 93 | name: development 94 | verboseName: Omniport Dev 95 | debug: true 96 | description: Development site for Omniport 97 | allowances: 98 | apps: __all__ 99 | ipAddressRings: 100 | - self 101 | - specifics 102 | - administrators 103 | - maintainers 104 | - intranet 105 | - internet 106 | 107 | A site-level configuration for a typical production site, more specifically the 108 | Intranet site ``site_1.yml`` looks like this. 109 | 110 | .. code-block:: yaml 111 | 112 | site: 113 | id: 1 114 | nomenclature: 115 | name: intranet 116 | verboseName: Omniport Intranet 117 | debug: true 118 | description: Intranet site for Omniport 119 | allowances: 120 | hosts: 121 | - omniport.intranet 122 | - intranet.channeli.in 123 | ipAddressRings: 124 | - intranet 125 | - maintainers 126 | - specifics 127 | -------------------------------------------------------------------------------- /docs/source/references/formula_one/components/app_footer.rst: -------------------------------------------------------------------------------- 1 | App footer 2 | ========== 3 | 4 | The *app footer* is always attached to the bottom of the screen and shows 5 | copyright and maintainer information. The footer is also some the coolest code 6 | in the entirety of Omniport's frontend. 7 | 8 | Props 9 | ----- 10 | 11 | #. ``creators`` 12 | 13 | :Type: 14 | :: 15 | 16 | [{ 17 | name: string, 18 | role: string, 19 | 20 | }] 21 | 22 | <> denotes optional field 23 | 24 | :Default: 25 | **\*required** 26 | :Description: 27 | | the creators who deserve credit for their app in the footer 28 | 29 | Example usage 30 | ------------- 31 | 32 | .. code-block:: javascript 33 | 34 | import { AppFooter } from 'formula_one' 35 | 36 | Importing ``AppFooter`` from ``formula_one`` 37 | 38 | .. code-block:: javascript 39 | 40 | const creators = [ 41 | { 42 | name: 'Dhruv Bhanushali', 43 | role: 'Backend developer', 44 | link: 'https://dhruvkb.github.io/' 45 | }, 46 | { 47 | name: 'Praduman Goyal', 48 | role: 'Frontend developer', 49 | link: 'https://pradumangoyal.github.io/' 50 | } 51 | ] 52 | 53 | Defining an array of objects to pass in ``creators`` 54 | 55 | .. code-block:: jsx 56 | 57 | 58 | 59 | Using ``AppFooter``, passing creators list 60 | -------------------------------------------------------------------------------- /docs/source/references/formula_one/components/app_header.rst: -------------------------------------------------------------------------------- 1 | App header 2 | ========== 3 | 4 | The *app header* is always attached to the top of the app and shows information 5 | about the app or site such as its logo, name and user information. 6 | 7 | Props 8 | ----- 9 | 10 | #. ``mode`` 11 | 12 | :Type: 13 | ``enum (string)`` 14 | :Default: 15 | ``site`` 16 | :Description: 17 | | defines if ``AppHeader`` should display app-related branding or 18 | site-related branding 19 | | **Enums:** ``site``, ``app`` 20 | 21 | #. ``appName`` 22 | 23 | :Type: 24 | ``string`` 25 | :Conditions for use: 26 | prop ``mode`` has value ``app`` 27 | :Default: 28 | **\*required** 29 | :Description: 30 | | used to get corresponding assets and app ``baseUrl`` from backend as 31 | well as frontend configs 32 | | Note: **NOT** ``appVerboseName`` 33 | 34 | #. ``sidebarButton`` 35 | 36 | :Type: 37 | ``Boolean`` 38 | :Default: 39 | ``false`` 40 | :Description: 41 | | whether to display sidebar button to the left of the logo 42 | 43 | #. ``sideBarVisibility`` 44 | 45 | :Type: 46 | ``Boolean`` 47 | :Conditions for use: 48 | prop ``sideBarButton`` has value ``true`` 49 | :Default: 50 | ``false`` 51 | :Description: 52 | | whether the sidebar is opened (visible, ``true``) or closed (hidden, 53 | ``false``) 54 | 55 | #. ``onSidebarClick`` 56 | 57 | :Type: 58 | ``function()`` 59 | :Conditions for use: 60 | prop ``sideBarButton`` has value ``true`` 61 | :Default: 62 | ``null`` 63 | :Description: 64 | | the function that will be called when sidebar button is clicked 65 | 66 | #. ``hamburgerOptions`` 67 | 68 | :Type: 69 | ``[string]`` 70 | :Conditions for use: 71 | prop ``sideBarButton`` has value ``true`` 72 | :Default: 73 | .. code-block:: javascript 74 | 75 | [ 76 | 'hamburger--minus', 77 | 'hamburger--spin', 78 | 'hamburger--squeeze' 79 | ] 80 | 81 | :Description: 82 | | types of hamburger animations 83 | | Accepts any subset of the default list 84 | | For more information, `click here `_ 85 | 86 | #. ``userDropdown`` 87 | 88 | :Type: 89 | ``Boolean`` 90 | :Default: 91 | ``false`` 92 | :Description: 93 | | whether to display sign in button or user details and notification bell 94 | | Displays institute logo, wordmark or name depending on availability 95 | 96 | #. ``middle`` 97 | 98 | :Type: 99 | ```` 100 | :Default: 101 | ``null`` 102 | :Description: 103 | | element, if any, to be rendered in the middle of the header 104 | 105 | #. ``right`` 106 | 107 | :Type: 108 | ```` 109 | :Default: 110 | ``null`` 111 | :Description: 112 | | element, if any, to be rendered on the right side of the header 113 | 114 | Example usage 115 | ------------- 116 | 117 | .. code-block:: javascript 118 | 119 | import { AppHeader } from 'formula_one' 120 | 121 | Importing ``AppHeader`` from ``formula_one`` 122 | 123 | .. code-block:: javascript 124 | 125 | const hamburgerOptions = [ 126 | 'hamburger--minus', 127 | 'hamburger--spin' 128 | ] 129 | 130 | Defining an array of strings to pass in ``hamburgerOptions`` 131 | 132 | .. code-block:: jsx 133 | 134 | 143 | 144 | Using ``AppHeader`` in ``app`` mode 145 | 146 | It will render page title, favicon, app name and app logo by querying the 147 | backend and handling all possible cases to render the best possible assets with 148 | a user dropdown or 'Login' button based on whether a user is logged in. 149 | 150 | .. code-block:: jsx 151 | 152 | 156 | 157 | Using ``AppHeader`` in ``site`` mode 158 | 159 | It will render site page title, site favicon, site name and site logo by 160 | querying the backend and handling all possible cases to render the best possible 161 | assets with a user dropdown or 'Login' button based on whether a user is logged 162 | in. .. code-block:: jsx 163 | 164 | 165 | 166 | Using ``AppHeader`` with absolutely no props 167 | 168 | It will render the header in ``site`` mode and the institute logo in place of 169 | the user dropdown. 170 | -------------------------------------------------------------------------------- /docs/source/references/formula_one/components/app_main.rst: -------------------------------------------------------------------------------- 1 | App main 2 | ======== 3 | 4 | ```` is a wrapper around the container in between your ```` 5 | and ```` which applies some default style to the app. 6 | 7 | Example usage 8 | ------------- 9 | 10 | .. code-block:: javascript 11 | 12 | import { AppMain } from 'formula_one' 13 | 14 | import style from '../css/app.css' 15 | 16 | Importing ``AppMain`` from ``formula_one`` 17 | 18 | .. code-block:: jsx 19 | 20 | 21 | 22 |
23 | 24 | ... 25 | 26 |
27 | 28 | 29 | 30 | Using ``AppMain`` in an app 31 | -------------------------------------------------------------------------------- /docs/source/references/formula_one/components/custom_cropper.rst: -------------------------------------------------------------------------------- 1 | Custom cropper 2 | ============== 3 | 4 | The *custom cropper* component is an exact copy of the ```` component 5 | that we had to be included separately to apply styles on it. This is due to our 6 | CSS loading process which uses a hashed ``styleName`` prop instead of 7 | ``className`` like standard React. 8 | 9 | Props 10 | ----- 11 | 12 | Refer to `react-image-crop `_ 13 | for all information. 14 | 15 | Example usage 16 | ------------- 17 | 18 | .. code-block:: javascript 19 | 20 | import { CustomCropper } from 'formula_one' 21 | 22 | Importing ``CustomCropper`` from ``formula_one`` 23 | 24 | Refer to `react-image-crop `_ 25 | for all information. 26 | -------------------------------------------------------------------------------- /docs/source/references/formula_one/components/default_dp.rst: -------------------------------------------------------------------------------- 1 | Default DP 2 | ========== 3 | 4 | The *default DP* component displays the first letter of the prop ``name`` in the 5 | shape of circle with the theme colour as background. It can be used whenever 6 | display image is not provided by user. 7 | 8 | Props 9 | ----- 10 | 11 | #. ``name`` 12 | 13 | :Type: 14 | ``string`` 15 | :Default: 16 | **\*required** 17 | :Description: 18 | | the string whose first letter will be shown in the component 19 | 20 | #. ``size`` 21 | 22 | :Type: 23 | ``string`` 24 | :Default: 25 | ``'1.5em'`` 26 | :Description: 27 | | the ``font-size`` property of the letter 28 | 29 | Example usage 30 | ------------- 31 | 32 | .. code-block:: javascript 33 | 34 | import { DefaultDP } from 'formula_one' 35 | 36 | Importing ``DefaultDP`` from ``formula_one`` 37 | 38 | .. code-block:: jsx 39 | 40 | 41 | 42 | Using ``DefaultDP`` passing name and size 43 | -------------------------------------------------------------------------------- /docs/source/references/formula_one/components/index.rst: -------------------------------------------------------------------------------- 1 | Components 2 | ========== 3 | 4 | Components make React apps what they are. Modular and reusable, they make 5 | frontend development easy. "What's better than components?", you ask? Components 6 | that are ready-made for your development joy! 7 | 8 | Formula 1 provides a number of commonly used components so that your experience 9 | building Omniport apps is as easy as possible. They also eliminate the need to 10 | rewrite components for everything as well ensure that the apps look and feel 11 | consistent with the core as well as each other. 12 | 13 | Read on to know what these components are, what they do, how you can use them 14 | and how the props you pass to them determine how they look and behave. 15 | 16 | .. toctree:: 17 | :caption: Subsections: 18 | 19 | app_header 20 | app_main 21 | app_footer 22 | default_dp 23 | user_card 24 | tile_card 25 | tiles 26 | maintainer_view 27 | non_maintainer_view 28 | masonry_layout 29 | custom_cropper 30 | no_match -------------------------------------------------------------------------------- /docs/source/references/formula_one/components/maintainer_view.rst: -------------------------------------------------------------------------------- 1 | Maintainer view 2 | =============== 3 | 4 | ``MaintainerView`` is a component that wraps components which are meant to be 5 | viewed only by maintainers with special permissions. 6 | 7 | Props 8 | ----- 9 | 10 | #. ``which`` 11 | 12 | :Type: 13 | ``string`` 14 | :Default: 15 | **\*required** 16 | :Description: 17 | | the permission that the user, who must be a maintainer, is supposed to 18 | have 19 | 20 | Example usage 21 | ------------- 22 | 23 | .. code-block:: javascript 24 | 25 | import { MaintainerView } from 'formula_one' 26 | 27 | Importing ``MaintainerView`` from ``formula_one`` 28 | 29 | .. code-block:: jsx 30 | 31 | 32 | ... 33 | 34 | 35 | Using ``MaintainerView``, passing prop ``which`` 36 | -------------------------------------------------------------------------------- /docs/source/references/formula_one/components/masonry_layout.rst: -------------------------------------------------------------------------------- 1 | Masonry layout 2 | ============== 3 | 4 | Masonry layouts are those that display staggered grids where cells may be of 5 | variable heights. This component is a wrapper around the similar components so 6 | that all the children are positioned in a way that the columns have the minimum 7 | difference between their bottom ends. 8 | 9 | Props 10 | ----- 11 | 12 | #. ``children`` 13 | 14 | :Type: 15 | :: 16 | 17 | [ 18 | 22 | ] 23 | :Default: 24 | **\*required** 25 | :Usage: 26 | This prop differs from standard usage. See below. 27 | :Description: 28 | | the list of elements that is to be shown in a masonry layout 29 | 30 | 31 | #. ``columns`` 32 | 33 | :Type: 34 | ``number`` 35 | :Default: 36 | ``2`` 37 | :Description: 38 | | number of columns into which the list of elements is to be divided 39 | 40 | #. ``gap`` 41 | 42 | :Type: 43 | ``number`` 44 | :Default: 45 | ``10`` 46 | :Description: 47 | | gutter in between the columns of the layout 48 | 49 | Example usage 50 | ------------- 51 | 52 | .. code-block:: javascript 53 | 54 | import { MasonryLayout } from 'formula_one' 55 | 56 | Importing ``MasonryLayout`` from ``formula_one`` 57 | 58 | .. code-block:: jsx 59 | 60 | 61 | {feedList.map(feed => { 62 | return ( 63 | 68 | ) 69 | })} 70 | 71 | 72 | Using ``MasonryLayout``, by passing number of columns and gap between them 73 | 74 | .. note:: 75 | 76 | ``children`` is a special prop that must be passed as actual children in the 77 | React shadow DOM. Notice here that ``children`` actually refers to the ``map`` 78 | on ``feedList`` returning a list of ``FeedCard`` nodes. 79 | -------------------------------------------------------------------------------- /docs/source/references/formula_one/components/no_match.rst: -------------------------------------------------------------------------------- 1 | No match 2 | ======== 3 | 4 | The ```` component is a very beautiful full page 404 component with its 5 | own header and footer and is mobile responsive. 6 | 7 | Props 8 | ----- 9 | 10 | There are absolutely none! 11 | 12 | Example usage 13 | ------------- 14 | 15 | .. code-block:: javascript 16 | 17 | import { NoMatch } from 'formula_one' 18 | 19 | Importing ``NoMatch`` from ``formula_one`` 20 | 21 | .. code-block:: jsx 22 | 23 | 24 | 25 | Using ``NoMatch`` in main routes 26 | 27 | .. code-block:: jsx 28 | 29 | 30 | 31 | An app can redirect to main 404 when there is no path route matched. 32 | 33 | .. note:: 34 | 35 | The standard way to use it is to redirect to it. Using it within one's header 36 | and footer can unleash a world of ugly and nasty. 37 | -------------------------------------------------------------------------------- /docs/source/references/formula_one/components/non_maintainer_view.rst: -------------------------------------------------------------------------------- 1 | Non-maintainer view 2 | =================== 3 | 4 | ```` is a component that wraps components which are 5 | strictly useless for maintainers if they have certain permissions. 6 | 7 | Props 8 | ----- 9 | 10 | #. ``which`` 11 | 12 | :Type: 13 | ``string`` 14 | :Default: 15 | **\*required** 16 | :Description: 17 | | the permission that the user, who must not be a maintainer, or is 18 | supposed not to have 19 | 20 | Example usage 21 | ------------- 22 | 23 | .. code-block:: javascript 24 | 25 | import { NonMaintainerView } from 'formula_one' 26 | 27 | Importing ``NonMaintainerView`` from ``formula_one`` 28 | 29 | .. code-block:: jsx 30 | 31 | 32 | ... 33 | 34 | 35 | Using ``NonMaintainerView`` passing prop ``which`` 36 | -------------------------------------------------------------------------------- /docs/source/references/formula_one/components/tile_card.rst: -------------------------------------------------------------------------------- 1 | Tile card 2 | ========== 3 | 4 | A *tile card* is a component that shows information about one unit of many 5 | similar units in an organised way, in an aesthetic card. 6 | 7 | Props 8 | ----- 9 | 10 | #. ``name`` 11 | 12 | :Type: 13 | ``string`` 14 | :Default: 15 | **\*required** 16 | :Description: 17 | | the heading to be used in the card 18 | 19 | #. ``desc`` 20 | 21 | :Type: 22 | ``string`` 23 | :Default: 24 | **\*required** 25 | :Description: 26 | | the description that is shown below the heading 27 | 28 | #. ``imageUrl`` 29 | 30 | :Type: 31 | ``string`` 32 | :Default: 33 | ``iconName``, see below 34 | :Description: 35 | | the associated image to be display in the card 36 | 37 | #. ``iconName`` 38 | 39 | :Type: 40 | ``enum (string)`` 41 | :Default: 42 | ``group`` 43 | :Description: 44 | | the icon to display in case an image URL is not passed in the props 45 | | **Enums**: For a comprehensive collection of valid inputs, refer to the 46 | `icon list `_. 47 | 48 | Example usage 49 | ------------- 50 | 51 | .. code-block:: javascript 52 | 53 | import { TileCard } from 'formula_one' 54 | 55 | Importing ``TileCard`` from ``formula_one`` 56 | 57 | .. code-block:: jsx 58 | 59 | 65 | 66 | Using ``TileCard``, passing all the props 67 | -------------------------------------------------------------------------------- /docs/source/references/formula_one/components/tiles.rst: -------------------------------------------------------------------------------- 1 | Tiles 2 | ===== 3 | 4 | Tiles are grids of tile cards. 5 | 6 | Props 7 | ----- 8 | 9 | #. ``tiles`` 10 | 11 | :Type: 12 | :: 13 | 14 | [{ 15 | name: string, 16 | desc: string, 17 | iconName: string, 18 | imageUrl: string, 19 | link: link 20 | }] 21 | 22 | :Default: 23 | **\*required** 24 | :Description: 25 | Refer to the props for :doc:`the tile card component `, except 26 | for ``link``. 27 | 28 | :link: 29 | Defines URL to which corresponding ``TileCard`` should point. 30 | 31 | Example usage 32 | ------------- 33 | 34 | .. code-block:: javascript 35 | 36 | import { Tiles } from 'formula_one' 37 | 38 | Importing ``Tiles`` from ``formula_one`` 39 | 40 | .. code-block:: javascript 41 | 42 | const tiles = [{ 43 | name: 'Alohomora', 44 | desc: 'Reset passwords, no-questions asked', 45 | imageUrl: '/path/to/image.jpg', 46 | iconName: 'cube', 47 | link: '/alohomora' 48 | }] 49 | 50 | Defining an array of objects to pass in ``tiles`` 51 | 52 | .. code-block:: jsx 53 | 54 | 57 | 58 | Using ``Tiles``, passing all the props 59 | -------------------------------------------------------------------------------- /docs/source/references/formula_one/components/user_card.rst: -------------------------------------------------------------------------------- 1 | User card 2 | ========= 3 | 4 | A user card is a component which displays the user's information in an 5 | organised way, in an aesthetic card. 6 | 7 | Props 8 | ----- 9 | 10 | #. ``image`` 11 | 12 | :Type: 13 | ``string`` 14 | :Default: 15 | ``null`` 16 | :Description: 17 | | the source to pass in the image tag's ``src`` attribute 18 | 19 | #. ``name`` 20 | 21 | :Type: 22 | ``string`` 23 | :Default: 24 | **\*required** 25 | :Description: 26 | | the name of a user, used as heading in the card as well as the prop for 27 | :doc:`the default DP component ` 28 | 29 | #. ``size`` 30 | 31 | :Type: 32 | ``string`` 33 | :Default: 34 | ``'1.5em'`` 35 | :Description: 36 | | directly passed as a prop to :doc:`the default DP component 37 | ` 38 | 39 | #. ``username`` 40 | 41 | :Type: 42 | ``string`` 43 | :Default: 44 | ``''`` 45 | :Description: 46 | | the sub-heading for the user card 47 | 48 | #. ``roles`` 49 | 50 | :Type: 51 | ``[string]`` 52 | :Default: 53 | ``''`` 54 | :Description: 55 | | an array of role names as strings, that are joined with ``', '`` 56 | 57 | #. ``right`` 58 | 59 | :Type: 60 | ```` 61 | :Default: 62 | ``null`` 63 | :Description: 64 | | the element to be shown on the right side of the component 65 | | This is generally used to pass icons like 'cross', 'close' or 'check'. 66 | 67 | Example usage 68 | ------------- 69 | 70 | .. code-block:: javascript 71 | 72 | import { UserCard } from 'formula_one' 73 | 74 | Importing ``UserCard`` from ``formula_one`` 75 | 76 | .. code-block:: javascript 77 | 78 | const roles = ['Student', 'Frontend developer'] 79 | 80 | Defining an array of strings to pass in ``roles`` 81 | 82 | .. code-block:: jsx 83 | 84 | } 91 | /> 92 | 93 | Using ``UserCard``, passing all the props 94 | -------------------------------------------------------------------------------- /docs/source/references/formula_one/functions/app_details.rst: -------------------------------------------------------------------------------- 1 | App details 2 | =========== 3 | 4 | ``appDetails()`` is a function which returns the config object stored at the 5 | frontend of the requested app according to their ``appName`` (**not** 6 | ``appDisplayName``) which is generally of the form ``placement_and_internship``. 7 | 8 | Signature 9 | --------- 10 | 11 | .. code-block:: javascript 12 | 13 | function appDetails('placement_and_internship') { 14 | ... 15 | return { 16 | present: {bool}, 17 | details: {object} 18 | } 19 | } 20 | 21 | Parameters 22 | ---------- 23 | 24 | #. ``appName`` 25 | 26 | :Type: 27 | ``string`` 28 | :Default: 29 | **\*required** 30 | :Description: 31 | the app whose config object is required (**not** ``appDisplayName``) 32 | 33 | Return 34 | ------ 35 | 36 | :Type: 37 | ``{object}`` 38 | :Data: 39 | Object containing ``present`` and ``details`` 40 | 41 | :present: 42 | ``bool`` that specifies whether the app exists 43 | :details: 44 | App config object defined in ``config.json`` of the app 45 | 46 | Examples 47 | -------- 48 | 49 | .. code-block:: javascript 50 | 51 | import { appDetails } from 'formula_one' 52 | 53 | Importing ``appDetails()`` from ``formula_one`` 54 | 55 | .. code-block:: javascript 56 | 57 | > appDetails('placement_and_internship') 58 | { 59 | present: true, 60 | details: { 61 | nomenclature: { 62 | name: "placement_and_internship", 63 | verboseName: "Placement and Internship" 64 | }, 65 | baseUrl: "/placement_and_internship", 66 | source: "placement_and_internship/src/index" 67 | } 68 | } 69 | 70 | Using ``appDetails()`` to get config of an app named 71 | ``placement_and_internship`` -------------------------------------------------------------------------------- /docs/source/references/formula_one/functions/common_apps.rst: -------------------------------------------------------------------------------- 1 | Common apps 2 | =========== 3 | 4 | ``commonApps()`` is a function which returns the list of apps obtained by the 5 | intersection of two lists, one being the API list obtained by requesting on 6 | ``apps/app/`` and one being set in ``config.json`` at frontend. 7 | 8 | Signature 9 | --------- 10 | 11 | .. code-block:: javascript 12 | 13 | function commonApps(apiList) { 14 | ... 15 | return commonList 16 | } 17 | 18 | Parameters 19 | ---------- 20 | 21 | #. ``apiList`` 22 | 23 | :Type: 24 | ``[object]`` 25 | :Default: 26 | **required** 27 | :Description: 28 | the array of **app objects** obtained by requesting ``apps/app/`` 29 | 30 | .. code-block:: json 31 | 32 | [ 33 | { 34 | "nomenclature": { 35 | "name": "one", 36 | "verboseName": "One" 37 | }, 38 | "baseUrls": { 39 | "http": "one/", 40 | "ws": null, 41 | "static": "one/" 42 | }, 43 | "assets": { 44 | "favicon": "assets/favicon.ico", 45 | "icon": null, 46 | "logo": "assets/logo.svg" 47 | }, 48 | "description": "App number one" 49 | }, 50 | { 51 | "nomenclature": { 52 | "name": "two", 53 | "verboseName": "Two" 54 | }, 55 | "baseUrls": { 56 | "http": "two/", 57 | "ws": null, 58 | "static": "two/" 59 | }, 60 | "assets": { 61 | "favicon": "assets/favicon.ico", 62 | "icon": "assets/icon.svg", 63 | "logo": "assets/logo.svg" 64 | }, 65 | "description": "App number two" 66 | } 67 | ] 68 | 69 | Return 70 | ------ 71 | 72 | :Type: 73 | ``[object]`` 74 | :Data: 75 | intersection of the two list with the object in the following form 76 | 77 | .. code-block:: json 78 | 79 | { 80 | "assets": { 81 | "favicon": "assets/favicon.ico", 82 | "icon": "assets/icon.svg", 83 | "logo": "assets/logo.svg" 84 | }, 85 | "baseUrl": "/one", 86 | "baseUrls": { 87 | "http": "one/", 88 | "ws": null, 89 | "static": "one/" 90 | }, 91 | "description": "App number one", 92 | "nomenclature": { 93 | "name": "one", 94 | "verboseName": "One" 95 | }, 96 | "source": "one/src/index" 97 | } 98 | 99 | Examples 100 | -------- 101 | 102 | .. code-block:: javascript 103 | 104 | import { commonApps } from 'formula_one' 105 | 106 | Importing ``commonApps()`` from ``formula_one`` 107 | 108 | .. code-block:: javascript 109 | 110 | commonApps(apiList) 111 | 112 | Using ``commonApps()``, returns an array of object of type described above -------------------------------------------------------------------------------- /docs/source/references/formula_one/functions/get_cookie.rst: -------------------------------------------------------------------------------- 1 | Get cookie 2 | ========== 3 | 4 | ``getCookie()`` is a function which makes consuming cookies *a piece of cake*. 5 | It returns the value of the cookie corresponding to name passed to it as 6 | parameter ``cname``. 7 | 8 | Signature 9 | --------- 10 | 11 | .. code-block:: javascript 12 | 13 | function getCookie(cname) { 14 | ... 15 | return value 16 | } 17 | 18 | Parameters 19 | ---------- 20 | 21 | #. ``cname`` 22 | 23 | :Type: 24 | ``string`` 25 | :Default: 26 | **\*required** 27 | :Description: 28 | the name of the cookie whose value is being retrieved 29 | 30 | Return 31 | ------ 32 | 33 | :Type: 34 | ``string`` 35 | :Data: 36 | - value of the cookie whose name is ``cname`` 37 | - ``null`` if the specified cookie is not found 38 | 39 | Examples 40 | -------- 41 | 42 | .. code-block:: javascript 43 | 44 | import { getCookie } from 'formula_one' 45 | 46 | Importing ``getCookie()`` from ``formula_one``. 47 | 48 | .. code-block:: javascript 49 | 50 | > getCookie('csrftoken') 51 | '4OgZaiZcwEHAAeqnzqrn2jFubHe7IemgS07ZJJ0CltuQD3e0MSHIKaAtqeBb7HhD' 52 | 53 | Using ``getCookie()`` to read the cookie named 'csrftoken'. -------------------------------------------------------------------------------- /docs/source/references/formula_one/functions/get_theme.rst: -------------------------------------------------------------------------------- 1 | Get theme 2 | ========= 3 | 4 | ``getTheme()`` is at the heart of ``Omniport`` themes. It returns the current 5 | theme colour out of available Semantic colours. 6 | 7 | Signature 8 | --------- 9 | 10 | .. code-block:: javascript 11 | 12 | function getTheme() { 13 | ... 14 | return theme 15 | } 16 | 17 | Return 18 | ------ 19 | 20 | :Type: 21 | ``string`` 22 | :Data: 23 | - can be passed directly to ``Semantic UI`` components 24 | - returns currently active theme colour as ``string`` 25 | - returns ``'blue'`` if no colour is set and also sets theme colour to 26 | ``'blue'`` 27 | - **Enums:** ``red``, ``orange``, ``yellow``, ``olive``, ``green``, 28 | ``teal``, ``blue``, ``violet``, ``purple``, ``pink``, ``black`` 29 | 30 | Examples 31 | -------- 32 | 33 | .. code-block:: javascript 34 | 35 | import { getTheme } from 'formula_one' 36 | 37 | Importing ``getTheme()`` from ``formula_one`` 38 | 39 | .. code-block:: javascript 40 | 41 | > getTheme() 42 | 'orange' 43 | 44 | Using ``getTheme()`` to get currently selected theme 45 | -------------------------------------------------------------------------------- /docs/source/references/formula_one/functions/get_theme_object.rst: -------------------------------------------------------------------------------- 1 | Get theme object 2 | ================ 3 | 4 | ``getThemeObject()`` is the function that returns colour description object of 5 | currently selected theme. 6 | 7 | Signature 8 | --------- 9 | 10 | .. code-block:: javascript 11 | 12 | function getThemeObject() { 13 | ... 14 | return themeObject 15 | } 16 | 17 | Return 18 | ------ 19 | 20 | :Type: 21 | ``{object}`` 22 | 23 | .. code-block:: javascript 24 | 25 | { 26 | name: {string}, 27 | verboseName: {string}, 28 | description: {string}, 29 | hexCode: {string} 30 | } 31 | 32 | 33 | :Data: 34 | - returns an object describing active theme colour 35 | - returns the object corresponding to the colour ``'blue'`` if no colour is 36 | set and also sets theme colour to ``'blue'`` 37 | - can be used when active theme is to be passed to JSX elements' ``style`` 38 | 39 | Examples 40 | -------- 41 | 42 | .. code-block:: javascript 43 | 44 | import { getThemeObject } from 'formula_one' 45 | 46 | Importing ``getThemeObject()`` from ``formula_one`` 47 | 48 | .. code-block:: javascript 49 | 50 | > getThemeObject() 51 | { 52 | name: "orange", 53 | verboseName: "Maverick Orange", 54 | description: "Unorthodox and chaotic", 55 | hexCode: "#f2711c" 56 | } 57 | 58 | Using ``getThemeObject()`` to get current selected theme object 59 | -------------------------------------------------------------------------------- /docs/source/references/formula_one/functions/if_role.rst: -------------------------------------------------------------------------------- 1 | If role 2 | ======= 3 | 4 | ``ifRole()`` is a function which returns the status of a role corresponding to a 5 | passed array of a user's roles. 6 | 7 | Signature 8 | --------- 9 | 10 | .. code-block:: javascript 11 | 12 | function ifRole(roles, role) { 13 | ... 14 | return status 15 | } 16 | 17 | Parameters 18 | ---------- 19 | 20 | #. ``roles`` 21 | 22 | :Type: 23 | ``[object]`` 24 | :Default: 25 | **\*required** 26 | :Description: 27 | the array of **role objects** obtained by requesting ``who_am_i/`` 28 | 29 | .. code-block:: json 30 | 31 | [ 32 | { 33 | "role": "Student", 34 | "activeStatus": "ActiveStatus.IS_ACTIVE" 35 | }, 36 | { 37 | "role": "Maintainer", 38 | "activeStatus": "ActiveStatus.IS_ACTIVE" 39 | } 40 | ] 41 | 42 | #. ``role`` 43 | 44 | :Type: 45 | ``string`` 46 | :Default: 47 | **\*required** 48 | :Description: 49 | the role whose existence is being checked 50 | 51 | Return 52 | ------ 53 | 54 | :Type: 55 | ``enum`` (``string``) 56 | :Data: 57 | - ``NOT_ROLE`` if required role is not matched with any role in the array. 58 | - **Enums:** ``IS_ACTIVE``, ``HAS_BEEN_ACTIVE``, ``WILL_BE_ACTIVE``, 59 | ``NOT_ROLE`` 60 | 61 | Examples 62 | -------- 63 | 64 | .. code-block:: javascript 65 | 66 | import { ifRole } from 'formula_one' 67 | 68 | Importing ``ifRole()`` from ``formula_one`` 69 | 70 | .. code-block:: javascript 71 | 72 | > const roles = [ 73 | { 74 | "role": "Student", 75 | "activeStatus": "ActiveStatus.IS_ACTIVE" 76 | }, 77 | { 78 | "role": "Maintainer", 79 | "activeStatus": "ActiveStatus.IS_ACTIVE" 80 | } 81 | ] 82 | 83 | > ifRole(roles, 'Maintainer') 84 | 'IS_ACTIVE' 85 | 86 | > ifRole(roles, 'Faculty') 87 | 'NOT_ROLE' 88 | 89 | Using ``ifRole()`` to get the status of various role of a person -------------------------------------------------------------------------------- /docs/source/references/formula_one/functions/index.rst: -------------------------------------------------------------------------------- 1 | Functions 2 | ========= 3 | 4 | Formula 1 provides a number of commonly used functions out-of-the-box so that 5 | developers may share them and not have to reinvent the wheel. Another sweet 6 | advantage is that advancements to the metaphorical wheel can be reaped by all 7 | users automatically. 8 | 9 | .. toctree:: 10 | :caption: Subsections: 11 | 12 | get_cookie 13 | if_role 14 | common_apps 15 | app_details 16 | get_theme 17 | get_theme_object 18 | -------------------------------------------------------------------------------- /docs/source/references/formula_one/index.rst: -------------------------------------------------------------------------------- 1 | Formula 1 2 | ========= 3 | 4 | Formula 1 is a collection of compound components and frequently-used functions 5 | that aims to make it easier to develop apps for Omniport. 6 | 7 | By pre-preparing these components and functions, Formula one makes it supremely 8 | fast and extremely easy to develop apps that look great and integrate cohesively 9 | with the rest of the platform. 10 | 11 | Read more about the offerings of Formula 1 in these documents. 12 | 13 | .. toctree:: 14 | :caption: Subsections: 15 | :maxdepth: 2 16 | 17 | components/index 18 | functions/index 19 | urls -------------------------------------------------------------------------------- /docs/source/references/formula_one/urls.rst: -------------------------------------------------------------------------------- 1 | URLs 2 | ==== 3 | 4 | ``urls.js`` is a file in ``formula_one`` that contains some URL functions that 5 | could be potentially useful in making API calls to various endpoints. 6 | 7 | You can check read and go through the entire file on `GitHub 8 | `_. 9 | 10 | Usage 11 | ----- 12 | 13 | .. code-block:: javascript 14 | 15 | import { urlAppBranding } from 'formula_one' 16 | 17 | Importing one of the URLs from ``formula_one`` 18 | 19 | .. code-block:: javascript 20 | 21 | > urlAppBranding('placement_and_internship') 22 | '/api/apps/app/placement_and_internship/' 23 | 24 | Using one of the URLs from ``formula_one`` -------------------------------------------------------------------------------- /docs/source/references/index.rst: -------------------------------------------------------------------------------- 1 | References 2 | ========== 3 | 4 | Omniport provides a huge ocean of ready-to-use components and functions and 5 | classes. It's natural to feel lost every once in a while. And when you are lost, 6 | references are what will guide you from one built-in feature to the next. 7 | 8 | These features of Omniport that are intended to make lives of developers' easier 9 | have been documented here. The documents here are not meant for sysadmins or 10 | users of the software but rather explain, in painful detail, the various aspects 11 | of Omniport that developers would want to incorporate into their apps. 12 | 13 | .. warning:: 14 | 15 | These guides are *volatile* and are *bound to change* as we update Omniport. 16 | 17 | The nature of Omniport's rolling-release development cycle prevents us from 18 | versioning these documents. 19 | 20 | .. toctree:: 21 | :caption: Subsections: 22 | :maxdepth: 2 23 | 24 | formula_one/index 25 | scripts/index 26 | config_files/index 27 | -------------------------------------------------------------------------------- /docs/source/references/scripts/backend/clone/everything.rst: -------------------------------------------------------------------------------- 1 | Everything 2 | ========== 3 | 4 | This script clones all the necessary services, as well as the shell for IIT 5 | Roorkee (with the developer's consent), in their appropriate directories in the 6 | ``omniport-backend`` repository. 7 | 8 | Usage 9 | ----- 10 | 11 | .. code-block:: console 12 | 13 | [dev omniport-backend]$ ./scripts/clone/everything.sh 14 | 15 | You will be asked if you wish to install the IIT Roorkee shell. You can approve 16 | the installation with :kbd:`Y` if you are an IIT Roorkee resident or otherwise 17 | wish to experience the customisation Omniport allows. You can deny this 18 | installation with any other key, primarily :kbd:`N`. 19 | -------------------------------------------------------------------------------- /docs/source/references/scripts/backend/clone/index.rst: -------------------------------------------------------------------------------- 1 | Clone scripts 2 | ============= 3 | 4 | Cloning the numerous services and packages required by Omniport is not easy. Or, 5 | should I say, *was* not easy. Now that cloning scripts have been written setting 6 | up Omniport backend is child's play. 7 | 8 | Read on to learn how you can use these clone scripts to remove the effort from 9 | setting up the codebase. 10 | 11 | .. toctree:: 12 | :caption: Subsections: 13 | :maxdepth: 2 14 | 15 | everything 16 | services 17 | shell 18 | -------------------------------------------------------------------------------- /docs/source/references/scripts/backend/clone/services.rst: -------------------------------------------------------------------------------- 1 | Services 2 | ======== 3 | 4 | This script clones all the necessary services in the ``omniport/services`` 5 | directory of the ``omniport-backend`` repository. 6 | 7 | Usage 8 | ----- 9 | 10 | .. code-block:: console 11 | 12 | [dev omniport-backend]$ ./scripts/clone/services.sh 13 | -------------------------------------------------------------------------------- /docs/source/references/scripts/backend/clone/shell.rst: -------------------------------------------------------------------------------- 1 | Formula 1 2 | ========= 3 | 4 | This script clones the IIT Roorkee shell in the ``omniport/`` directory of the 5 | ``omniport-backend`` repository. 6 | 7 | Usage 8 | ----- 9 | 10 | .. code-block:: console 11 | 12 | [dev omniport-backend]$ ./scripts/clone/shell.sh 13 | -------------------------------------------------------------------------------- /docs/source/references/scripts/backend/create_app.rst: -------------------------------------------------------------------------------- 1 | Create app 2 | ========== 3 | 4 | .. note:: 5 | 6 | After you have an up and running API make sure to create a React app for the 7 | frontend of the project. 8 | 9 | Although creating a new app on ``omniport-backend`` is really easy, the main 10 | reason being that the process of creating one and the file structure are both 11 | pretty much identical to a normal Django app, we have provided a convenient 12 | method to make this process effortless for the developer. 13 | 14 | Usage 15 | ----- 16 | 17 | .. code-block:: console 18 | 19 | [dev omniport-backend]$ ./scripts/create/app.sh 20 | 21 | You are asked for the name of your app that you have to provide in lower case 22 | letters, separating words with spaces. For example, for an app named 'Placement 23 | and internship' you must enter 24 | 25 | .. code-block:: text 26 | 27 | placement and internship 28 | 29 | That's about it! It clones a pre-defined `template from GitHub 30 | `_, makes 31 | necessary replacements with the app name you have provided and creates a new 32 | folder in the ``omniport/apps/`` folder. 33 | 34 | Restarting the server will make Discovery aware of your new project. The 35 | root URL of your newly created API can be deduced by replacing spaces in the 36 | app name you provided with underscores, ``_``. This is, needless to say, 37 | customisable via the ``config.yml`` file. 38 | 39 | You should be greeted with a JSON API, greeting you on your success. 40 | -------------------------------------------------------------------------------- /docs/source/references/scripts/backend/index.rst: -------------------------------------------------------------------------------- 1 | Backend scripts 2 | =============== 3 | 4 | The backend codebase of Omniport comes loaded with a bunch of scripts to help 5 | you get all the services you need up and running as well as to get started with 6 | your app. 7 | 8 | .. toctree:: 9 | :caption: Subsections: 10 | :maxdepth: 2 11 | 12 | clone/index 13 | start_django 14 | create_app -------------------------------------------------------------------------------- /docs/source/references/scripts/backend/start_django.rst: -------------------------------------------------------------------------------- 1 | Start Django 2 | ============ 3 | 4 | .. note:: 5 | 6 | This process requires the Django container to have been built beforehand. If 7 | that is not the case, read :doc:`how to build the Omniport Django container 8 | <../docker/build/django>`. 9 | 10 | This script starts a Django container with the code mounted in it making it easy 11 | to deploy the development version of the app in a container and pre-configure it 12 | to find the service containers and connect to them. 13 | 14 | Usage 15 | ----- 16 | 17 | .. code-block:: console 18 | 19 | [dev omniport-frontend]$ ./scripts/start/django.sh 20 | 21 | Flags 22 | ----- 23 | 24 | :-p: 25 | | The port to which the Django developer server must bind 26 | | ``number`` 27 | -------------------------------------------------------------------------------- /docs/source/references/scripts/docker/build/django.rst: -------------------------------------------------------------------------------- 1 | Django 2 | ====== 3 | 4 | This script builds the Django container that is responsible for operating the 5 | API powering Omniport. 6 | 7 | .. code-block:: console 8 | 9 | [apps omniport-docker]$ ./scripts/build/django.sh 10 | 11 | You will get the choice regarding the installation of developer tools. Affirm 12 | with a :kbd:`Y` if you are going to be using the image for debugging, else 13 | decline with any other character, primarily :kbd:`N`. If you are unsure, press 14 | :kbd:`Y`, although this is not the default for image size concerns. 15 | -------------------------------------------------------------------------------- /docs/source/references/scripts/docker/build/index.rst: -------------------------------------------------------------------------------- 1 | Build scripts 2 | ============= 3 | 4 | These scripts pertain to the process of building images for various services 5 | involved in the project. 6 | 7 | .. toctree:: 8 | :caption: Subsections: 9 | :maxdepth: 2 10 | 11 | postgres 12 | rabbitmq 13 | nginx 14 | django 15 | react -------------------------------------------------------------------------------- /docs/source/references/scripts/docker/build/nginx.rst: -------------------------------------------------------------------------------- 1 | NGINX 2 | ===== 3 | 4 | This script builds the NGINX container that is responsible for operating the 5 | reverse proxy to the API, that also serves all our static and media files. 6 | 7 | .. code-block:: console 8 | 9 | [apps omniport-docker]$ ./scripts/build/nginx.sh 10 | 11 | You will get the choice regarding the recreation of NGINX configuration files. 12 | Affirm with a :kbd:`Y` if you intend to rewrite them, else decline with any 13 | other character, primarily :kbd:`N`. 14 | 15 | .. warning:: 16 | 17 | If this is your first time building the container, choose :kbd:`Y`. Choosing 18 | :kbd:`N` can have adverse unwanted consequences. 19 | 20 | If you choose to recreate the configuration files, you will have to answer a 21 | questionnaire. Enter the domain names that you want to refer to the intranet and Internet 22 | sites of the project. 23 | 24 | For example, at IIT Roorkee, the hostnames for Omniport are ``channeli.in`` and 25 | ``channeli.iitr.ac.in`` from inside and outside the campus respectively. 26 | 27 | Also choose whether to enable SSL with a :kbd:`Y` if you have SSL certificates 28 | or with a :kbd:`N` if you don't. The configuration files will be regenerated and 29 | the image built. 30 | -------------------------------------------------------------------------------- /docs/source/references/scripts/docker/build/postgres.rst: -------------------------------------------------------------------------------- 1 | PostgreSQL 2 | ========== 3 | 4 | This script builds the PostgreSQL container that acts as the primary database for 5 | all Omniport apps and services. 6 | 7 | .. code-block:: console 8 | 9 | [apps omniport-docker]$ ./scripts/build/postgres.sh 10 | 11 | You will get the choice regarding the recreation of the database environment 12 | file. Affirm with a :kbd:`Y` if you intend to rewrite it, else decline with any 13 | other character, primarily :kbd:`N`. 14 | 15 | .. warning:: 16 | 17 | If this is your first time building the container, choose :kbd:`Y`. Choosing 18 | :kbd:`N` can have adverse unwanted consequences. 19 | 20 | If you choose to recreate the environment file, you will have to answer a 21 | questionnaire. Enter a database name, a username and a password for the 22 | database. 23 | 24 | Remember to populate this database name, username and password in the 25 | :doc:`Django project-level configuration file 26 | <../../../config_files/project/base_yml>`. -------------------------------------------------------------------------------- /docs/source/references/scripts/docker/build/rabbitmq.rst: -------------------------------------------------------------------------------- 1 | RabbitMQ 2 | ======== 3 | 4 | This script builds the RabbitMQ container that acts as the message-broker for 5 | all Omniport apps and services. 6 | 7 | .. code-block:: console 8 | 9 | [apps omniport-docker]$ ./scripts/build/rabbitmq.sh 10 | 11 | You will get the choice regarding the recreation of the message broker 12 | environment file. Affirm with a :kbd:`Y` if you intend to rewrite it, else 13 | decline with any other character, primarily :kbd:`N`. 14 | 15 | .. warning:: 16 | 17 | If this is your first time building the container, choose :kbd:`Y`. Choosing 18 | :kbd:`N` can have adverse unwanted consequences. 19 | 20 | If you choose to recreate the environment file, you will have to answer a 21 | questionnaire. Enter a username and a password for the message broker. 22 | 23 | Remember to populate this username and password in the :doc:`Django project-level 24 | configuration file <../../../config_files/project/base_yml>`. -------------------------------------------------------------------------------- /docs/source/references/scripts/docker/build/react.rst: -------------------------------------------------------------------------------- 1 | React 2 | ===== 3 | 4 | This script builds the React container that is responsible for operating the 5 | frontend powering Omniport. 6 | 7 | .. code-block:: console 8 | 9 | [apps omniport-docker]$ ./scripts/build/react.sh 10 | 11 | You will get the choice regarding the installation of developer tools. Affirm 12 | with a :kbd:`Y` if you are going to be using the image for debugging, else 13 | decline with any other character, primarily :kbd:`N`. If you are unsure, press 14 | :kbd:`Y`, although this is not the default for image size concerns. 15 | -------------------------------------------------------------------------------- /docs/source/references/scripts/docker/clone/backend.rst: -------------------------------------------------------------------------------- 1 | Backend 2 | ======= 3 | 4 | ``clone/backend.sh`` sets up ``omniport-backend`` inside the ``codebase/`` 5 | folder with the ``services`` required at the backend. 6 | 7 | .. warning:: 8 | 9 | Running this script will remove any existing ``omniport-backend/`` folder 10 | inside the ``codebase/`` directory. 11 | 12 | Usage 13 | ----- 14 | 15 | .. code-block:: console 16 | 17 | [apps omniport-docker]$ ./scripts/clone/backend.sh 18 | 19 | Working 20 | ------- 21 | 22 | The script clones the repository ``omniport-backend`` and then defers the 23 | cloning process to the ``scripts/clone/everything.sh`` :doc:`script 24 | <../../backend/clone/everything>` in that repository. 25 | -------------------------------------------------------------------------------- /docs/source/references/scripts/docker/clone/everything.rst: -------------------------------------------------------------------------------- 1 | Everything 2 | ========== 3 | 4 | ``clone/everything.sh`` aims to set up whole Omniport codebase in one command 5 | with the basic services that Omniport expects to run smoothly on both the 6 | frontend as well as the backend. 7 | 8 | The script takes you through the steps of cloning the codebase. 9 | 10 | .. warning:: 11 | 12 | Running this script will remove any existing ``codebase/`` folder in the root 13 | directory. 14 | 15 | Usage 16 | ----- 17 | 18 | .. code-block:: console 19 | 20 | [apps omniport-docker]$ ./scripts/clone/everything.sh 21 | 22 | Working 23 | ------- 24 | 25 | Basically, all this script does is call two sub-scripts which in turn clone the 26 | :doc:`backend ` and :doc:`frontend ` codebases. 27 | -------------------------------------------------------------------------------- /docs/source/references/scripts/docker/clone/frontend.rst: -------------------------------------------------------------------------------- 1 | Frontend 2 | ======== 3 | 4 | ``clone/frontend.sh`` sets up ``omniport-frontend`` inside the ``codebase/`` 5 | folder with the ``services`` required at the frontend. 6 | 7 | .. warning:: 8 | 9 | Running this script will remove any existing ``omniport-frontend/`` folder 10 | inside the ``codebase/`` directory. 11 | 12 | Usage 13 | ----- 14 | 15 | .. code-block:: console 16 | 17 | [apps omniport-docker]$ ./scripts/clone/frontend.sh 18 | 19 | Working 20 | ------- 21 | 22 | The script clones the repository ``omniport-frontend`` and then defers the 23 | cloning process to the ``scripts/clone/everything.sh`` :doc:`script 24 | <../../frontend/clone/everything>` in that repository. 25 | -------------------------------------------------------------------------------- /docs/source/references/scripts/docker/clone/index.rst: -------------------------------------------------------------------------------- 1 | Clone scripts 2 | ============= 3 | 4 | These scripts pertain to the process of cloning various repositories from GitHub 5 | and setting up the codebase on the local machine. 6 | 7 | .. toctree:: 8 | :caption: Subsections: 9 | :maxdepth: 2 10 | 11 | everything 12 | backend 13 | frontend 14 | -------------------------------------------------------------------------------- /docs/source/references/scripts/docker/index.rst: -------------------------------------------------------------------------------- 1 | Docker scripts 2 | ============== 3 | 4 | The Docker distribution of Omniport comes loaded with a bunch of scripts to help 5 | you smoothly get your own instance of the portal up and running with minimal 6 | hassle, as little pain as can be caused, negligible to zero need for cursing, no 7 | crying or banging your head in anguish. 8 | 9 | .. toctree:: 10 | :caption: Subsections: 11 | :maxdepth: 2 12 | 13 | clone/index 14 | build/index 15 | start/index 16 | -------------------------------------------------------------------------------- /docs/source/references/scripts/docker/start/development.rst: -------------------------------------------------------------------------------- 1 | Development 2 | =========== 3 | 4 | This script starts all containers that are required to set up the Omniport 5 | development environment as outlined in :doc:`development environment <../../../../environments/development>`. 6 | 7 | .. code-block:: console 8 | 9 | [apps omniport-docker]$ ./scripts/start/development.sh 10 | 11 | This will start all shared containers required for the functioning of the 12 | development Django containers. 13 | -------------------------------------------------------------------------------- /docs/source/references/scripts/docker/start/index.rst: -------------------------------------------------------------------------------- 1 | Start scripts 2 | ============= 3 | 4 | These scripts pertain to the process of cloning various repositories from GitHub 5 | and setting up the codebase on the local machine. 6 | 7 | .. toctree:: 8 | :caption: Subsections: 9 | :maxdepth: 2 10 | 11 | development 12 | logs 13 | -------------------------------------------------------------------------------- /docs/source/references/scripts/docker/start/logs.rst: -------------------------------------------------------------------------------- 1 | Logs 2 | ==== 3 | 4 | This script starts the Bash container needed for examining the logs generated 5 | by various services in production. 6 | 7 | .. code-block:: console 8 | 9 | [apps omniport-docker]$ ./scripts/start/logs.sh 10 | 11 | This will drop you into a familiar but foreign Bash shell. Executing ``ls`` here 12 | reveals the log directories. 13 | 14 | .. code-block:: console 15 | 16 | # ls 17 | reverse_proxy_logs 18 | web_server_logs 19 | ... 20 | 21 | The ``web_server_logs`` directory further contains three directories. 22 | 23 | .. code-block:: console 24 | 25 | # cd web_server_logs 26 | # ls 27 | daphne_logs 28 | gunicorn_logs 29 | supervisord_logs 30 | ... 31 | 32 | All these directories contains various logs that can be examined. The container 33 | also supports the ``tail`` binary fortunately enabling you to tail and detect 34 | errors. 35 | 36 | For explanations regarding the directory and file structure, refer to the 37 | :doc:`guide on how to read logs<../../../../how_to/read_logs>`. -------------------------------------------------------------------------------- /docs/source/references/scripts/frontend/build_frontend.rst: -------------------------------------------------------------------------------- 1 | Build frontend 2 | ============== 3 | 4 | .. note:: 5 | 6 | This process requires the React container to have been built beforehand. If 7 | that is not the case, read :doc:`how to build the Omniport React container 8 | <../docker/build/react>`. 9 | 10 | This scripts builds the production React app from the frontend codebase and places 11 | the built files in a folder named ``build/``. 12 | 13 | Usage 14 | ----- 15 | 16 | .. code-block:: console 17 | 18 | [dev omniport-frontend]$ ./scripts/build/frontend.sh -------------------------------------------------------------------------------- /docs/source/references/scripts/frontend/clone/everything.rst: -------------------------------------------------------------------------------- 1 | Everything 2 | ========== 3 | 4 | This script clones all the necessary services, as well as Formula 1, in their 5 | appropriate directories in the ``omniport-frontend`` repository. 6 | 7 | Usage 8 | ----- 9 | 10 | .. code-block:: console 11 | 12 | [dev omniport-frontend]$ ./scripts/clone/everything.sh 13 | 14 | -------------------------------------------------------------------------------- /docs/source/references/scripts/frontend/clone/formula_one.rst: -------------------------------------------------------------------------------- 1 | Formula 1 2 | ========= 3 | 4 | This script clones Formula 1 in the ``omniport/`` directory of the 5 | ``omniport-frontend`` repository. 6 | 7 | Usage 8 | ----- 9 | 10 | .. code-block:: console 11 | 12 | [dev omniport-frontend]$ ./scripts/clone/formula_one.sh 13 | -------------------------------------------------------------------------------- /docs/source/references/scripts/frontend/clone/index.rst: -------------------------------------------------------------------------------- 1 | Clone scripts 2 | ============= 3 | 4 | Cloning the numerous services and packages required by Omniport is not easy. Or, 5 | should I say, *was* not easy. Now that cloning scripts have been written setting 6 | up Omniport frontend is child's play. 7 | 8 | Read on to learn how you can use these clone scripts to remove the effort from 9 | setting up the codebase. 10 | 11 | .. toctree:: 12 | :caption: Subsections: 13 | :maxdepth: 2 14 | 15 | everything 16 | services 17 | formula_one 18 | -------------------------------------------------------------------------------- /docs/source/references/scripts/frontend/clone/services.rst: -------------------------------------------------------------------------------- 1 | Services 2 | ======== 3 | 4 | This script clones all the necessary services in the ``omniport/services`` 5 | directory of the ``omniport-frontend`` repository. 6 | 7 | Usage 8 | ----- 9 | 10 | .. code-block:: console 11 | 12 | [dev omniport-frontend]$ ./scripts/clone/services.sh 13 | -------------------------------------------------------------------------------- /docs/source/references/scripts/frontend/create_app.rst: -------------------------------------------------------------------------------- 1 | Create app 2 | ========== 3 | 4 | .. note:: 5 | 6 | Make sure you have the corresponding backend ready before you start the 7 | frontend to avoid any nasty surprises. 8 | 9 | Although creating a new app on ``omniport-frontend`` is really easy, the main 10 | reason being that the process of creating one and the file structure are both 11 | pretty much identical to a normal React app, we have provided a convenient 12 | method to make this process effortless for the developer. 13 | 14 | Usage 15 | ----- 16 | 17 | .. code-block:: console 18 | 19 | [dev omniport-frontend]$ ./scripts/create/app.sh 20 | 21 | You are asked for the name of your app that you have to provide in lower case 22 | letters, separating words with spaces. For example, for an app named 'Placement 23 | and internship' you must enter 24 | 25 | .. code-block:: text 26 | 27 | placement and internship 28 | 29 | That's about it! It clones a pre-defined `template from GitHub 30 | `_, makes 31 | necessary replacements with the app name you have provided and creates a new 32 | folder in the ``omniport/apps/`` folder. 33 | 34 | Restarting the server will make Discovery aware of your new project. The 35 | root URL of your newly created app can be deduced by replacing spaces in the 36 | app name you provided with underscores, ``_``. This is, needless to say, 37 | customisable via the ``config.json`` file. 38 | 39 | You should be greeted with a pleasant homepage. -------------------------------------------------------------------------------- /docs/source/references/scripts/frontend/index.rst: -------------------------------------------------------------------------------- 1 | Frontend scripts 2 | ================ 3 | 4 | The frontend codebase of Omniport comes loaded with a bunch of scripts to help 5 | you get all the services you need up and running as well as to get started with 6 | your app. Finally when it's all done, you can build your frontend and push it 7 | to the NGINX container for deployment. 8 | 9 | .. toctree:: 10 | :caption: Subsections: 11 | :maxdepth: 2 12 | 13 | clone/index 14 | start_react 15 | create_app 16 | build_frontend 17 | 18 | -------------------------------------------------------------------------------- /docs/source/references/scripts/frontend/start_react.rst: -------------------------------------------------------------------------------- 1 | Start React 2 | =========== 3 | 4 | .. note:: 5 | 6 | This process requires the React container to have been built beforehand. If 7 | that is not the case, read :doc:`how to build the Omniport React container 8 | <../docker/build/react>`. 9 | 10 | This script starts a React container with the code mounted in it making it easy 11 | to deploy the development version of the app in a container and pre-configure it 12 | to find the API container and connect to it. 13 | 14 | Usage 15 | ----- 16 | 17 | .. code-block:: console 18 | 19 | [dev omniport-frontend]$ ./scripts/start/react.sh -d 20 | 21 | Flags 22 | ----- 23 | 24 | :-d: 25 | | The Django port where the API is up and running 26 | | ``number``, **required** 27 | 28 | :-p: 29 | | The port to which the React developer server must bind 30 | | ``number`` 31 | -------------------------------------------------------------------------------- /docs/source/references/scripts/index.rst: -------------------------------------------------------------------------------- 1 | Scripts 2 | ======= 3 | 4 | Omniport comes with a number of Bash scripts to perform a number of actions. 5 | From setting up the entire Omniport codebase to starting an app, everything that 6 | can be scripted will be scripted. That's the Omniport way of things! 7 | 8 | Read more about the scripts to know about their function, their customisation 9 | flags and options. 10 | 11 | .. toctree:: 12 | :caption: Subsections: 13 | :maxdepth: 2 14 | 15 | docker/index 16 | backend/index 17 | frontend/index 18 | -------------------------------------------------------------------------------- /docs/source/setting_up/development.rst: -------------------------------------------------------------------------------- 1 | Development 2 | =========== 3 | 4 | With everything set up, the flows diverge. This is how to develop for Omniport. 5 | 6 | Sysadmin 7 | -------- 8 | 9 | As ``apps``, enter ``omniport-docker/``. Set up all the shared services. 10 | 11 | .. code-block:: console 12 | 13 | [apps omniport-docker]$ ./scripts/start/development.sh 14 | 15 | This should start all shared services such as the database and message-broker. 16 | Being heavy and all, every developer shares these services. 17 | 18 | To enter the container for any service, execute this command. 19 | 20 | .. code-block:: console 21 | 22 | [apps omniport-docker]$ docker-compose exec bash 23 | 24 | .. note:: 25 | 26 | Most Omniport services are built off of Debian and have ``bash`` installed. In 27 | case, you face trouble, try running ``sh`` instead. 28 | 29 | Go as a developer and migrate the services. 30 | 31 | Relax. 32 | 33 | Developer 34 | --------- 35 | 36 | As ``dev1``, clone the following. 37 | 38 | - ``omniport-backend`` 39 | - ``omniport-frontend`` 40 | - all services on the backend and frontend 41 | - your apps on the backend and frontend 42 | 43 | Then from ``omniport-backend/``, start your development server. 44 | 45 | .. code-block:: console 46 | 47 | [dev1 omniport-backend]$ ./scripts/start/django.sh 48 | 49 | Note the port that you are assigned Let's call it ````. 50 | 51 | Then from ``omniport-frontend/``, start your development server. 52 | 53 | .. code-block:: console 54 | 55 | [dev1 omniport-frontend]$ ./scripts/start/react.sh -d 56 | 57 | Visit these ports from your browser and you should be able to see your app. 58 | Changing code in either codebase will automatically reload the servers. 59 | 60 | To enter the container for any server, execute this command. 61 | 62 | .. code-block:: console 63 | 64 | [dev1 anywhere]$ docker exec -ti sh 65 | 66 | .. note:: 67 | 68 | Some services, namely those built off of Debian, have ``bash`` installed. Most 69 | don't. So the best way to go about it is to execute ``sh`` and once in the 70 | container, execute ``bash``. 71 | 72 | From time to time, you will have to enter the Django container to make and run 73 | migrations, collect static files and do the occasional housekeeping. You should 74 | migrate only your own apps. Apps migrated by ``dev2`` should not be migrated by 75 | ``dev1``. In most sane cases, this situation will never even arise. 76 | 77 | Have fun! 78 | -------------------------------------------------------------------------------- /docs/source/setting_up/docker.rst: -------------------------------------------------------------------------------- 1 | Docker 2 | ====== 3 | 4 | Once you have configured the server, it's time to install the Docker CE suite on 5 | it. Setting up Docker is easy. Since that is beyond the scope of the 6 | documentation, please refer to the Docker documentation for instructions 7 | pertaining to your operating system. 8 | 9 | Do note that installing Docker alone will not suffice, you will also need to 10 | install Docker Compose. 11 | 12 | .. note:: 13 | 14 | The Docker 15 | `documentation `_ 16 | contains the links on install Docker and Docker Compose on your system of 17 | choice. 18 | 19 | Start and enable Docker 20 | ----------------------- 21 | 22 | After you have installed Docker and Docker Compose on your machine, you will 23 | need to make some configuration changes. 24 | 25 | Docker has been installed but the daemon is neither running nor has been set to 26 | run automatically on a reboot. You can accomplish these changes as follows. 27 | 28 | .. code-block:: console 29 | 30 | [apps ~]$ sudo systemctl start docker 31 | [apps ~]$ sudo systemctl enable docker 32 | 33 | Groups 34 | ------ 35 | 36 | The Docker daemon process ``dockerd`` is only accessible to users that are a 37 | part of the Docker group. 38 | 39 | Remember ``apps`` from :doc:`Environments <../environments/index>` and 40 | :doc:`server configuration `? So ``apps`` must a member of 41 | the group ``docker``, which is automatically created when Docker is first 42 | installed. 43 | 44 | .. code-block:: console 45 | 46 | [apps ~]$ sudo usermod -aG docker apps 47 | 48 | Also in a development environment, your developers must also be members of the 49 | group. 50 | 51 | .. code-block:: console 52 | 53 | [apps ~]$ sudo usermod -aG docker dev1 54 | [apps ~]$ sudo usermod -aG docker dev2 55 | 56 | You will need to restart your user sessions, and in my personal experience in 57 | some cases, even restart your computer, after this. 58 | 59 | User namespaces 60 | --------------- 61 | 62 | User namespaces are a way to limit the surface area of the Docker sandbox in 63 | the event of a security breach. Basically user namespaces map ``root`` in the 64 | Docker sandbox to another UID on the host, thereby stripping away all rights of 65 | the root user in a container to cause damage to the host. 66 | 67 | .. warning:: 68 | 69 | While user namespaces are very cool and good, we at IMG have run into a number 70 | of intermittent and irregularly occurring issues when running Omniport under a 71 | namespace. This step is therefore advised only for people who know what they 72 | are doing. 73 | 74 | To enable namespaces, elevate your privileges, open the file 75 | ``/etc/docker/daemon.json`` and type in the following lines. 76 | 77 | .. code-block:: json 78 | 79 | { 80 | "userns-remap": "apps" 81 | } 82 | 83 | If you decided to go with an alternative name for the main user, replace 84 | ``apps`` with the username of that user. 85 | 86 | You will need to restart the Docker daemon after this change. 87 | 88 | .. code-block:: console 89 | 90 | $ sudo systemctl restart docker 91 | -------------------------------------------------------------------------------- /docs/source/setting_up/index.rst: -------------------------------------------------------------------------------- 1 | Setting up 2 | ========== 3 | 4 | Getting started with Omniport is easy, especially when going with the Docker 5 | route. There are a few steps that are common to both enviroments after which 6 | the two flows diverge a bit. Effectively, thanks to Docker and some smart 7 | development, we are able to reuse the same code and containers, with minuscule 8 | changes, on development and production machines. 9 | 10 | We'll try to comprehensively cover all scenarios but know that we will have to 11 | restrict ourselves to the two out-of-the-box flows only. 12 | 13 | Read on to understand how you can set up Omniport Docker on your own computers, 14 | development servers and production servers. 15 | 16 | .. toctree:: 17 | :caption: Subsections: 18 | 19 | server_configuration 20 | docker 21 | omniport_docker 22 | development 23 | production 24 | omniport_docs -------------------------------------------------------------------------------- /docs/source/setting_up/omniport_docker.rst: -------------------------------------------------------------------------------- 1 | Omniport Docker 2 | =============== 3 | 4 | Clone Omniport Docker from 5 | `GitHub `_ 6 | and enter the directory. 7 | 8 | Inside the directory ``omniport-docker/`` you must clone the codebase of 9 | Omniport, namely the backend and the frontend. Enter the ``codebase/`` directory 10 | and then clone both ``omniport-backend`` and ``omniport-frontend`` repositories 11 | from GitHub. 12 | 13 | .. note:: 14 | 15 | You may use the 16 | :doc:`clone codebase script <../references/scripts/docker/clone/everything>` 17 | to accomplish the same goal. 18 | 19 | Configuring the environment 20 | --------------------------- 21 | 22 | RabbitMQ 23 | ++++++++ 24 | 25 | In ``rabbitmq/``, copy ``message_broker_stencil.env`` to ``message_broker.env`` 26 | and populate the environment variables. These will be used when the queue is set 27 | up so choose a strong password. 28 | 29 | You will need to provide these values in the Django configuration, so remember 30 | them. 31 | 32 | PostgreSQL 33 | ++++++++++ 34 | 35 | In ``postgres/``, copy ``database_stencil.env`` to ``database.env`` and populate 36 | the environment variables. These will be used when the database management 37 | system is set up so choose a strong password. 38 | 39 | You will need to provide these values in the Django configuration, so remember 40 | them. 41 | 42 | Django 43 | ++++++ 44 | 45 | Django configuration works at two levels: 46 | 47 | - base-level configuration 48 | - site-level configuration 49 | 50 | Enter ``codebase/omniport-backend/configuration/``. 51 | 52 | Base-level configuration 53 | ~~~~~~~~~~~~~~~~~~~~~~~~ 54 | 55 | Copy ``base_stencil.yml`` to ``base.yml`` and populate all the variables there. 56 | If you need help, refer to the :doc:`documentation on this file 57 | <../references/config_files/project/base_yml>`. 58 | 59 | Site-level configuration 60 | ~~~~~~~~~~~~~~~~~~~~~~~~ 61 | 62 | In ``sites/``, copy ``site_stencil.yml`` to 63 | 64 | - ``site_0.yml`` in development 65 | - ``site_1.yml`` and ``site_2.yml`` in production 66 | 67 | and populate all the variables there. If you need help, refer to the 68 | :doc:`documentation on this file <../references/config_files/project/site_yml>`. 69 | 70 | NGINX 71 | +++++ 72 | 73 | There is no configuration file to write here. Just keep the domain names for 74 | the Intranet site and the Internet site at hand. If you have SSL enabled, which 75 | you absolutely should because it enhances security and is absolutely free, place 76 | your 77 | 78 | - certificate named ``omniport.crt`` 79 | - private key named ``omniport.key`` 80 | 81 | in the directory ``cert/``. 82 | 83 | Also, if you choose the SSL route, remember to answer 'yes' for HTTPS in the 84 | NGINX image build script. 85 | 86 | Build the Dockerfiles 87 | --------------------- 88 | 89 | There are quite a few images to be built which, thanks to Omniport's liberal use 90 | of scripts, translates to executing just as many shell commands. All these 91 | scripts are interactive, which means you will be asked questions, whose answers 92 | will determine the end result of the operation. 93 | 94 | Maybe one day we will write a script that runs these scripts. 95 | 96 | .. code-block:: console 97 | 98 | [apps omniport-docker]$ ./scripts/build/django.sh 99 | [apps omniport-docker]$ ./scripts/build/react.sh 100 | [apps omniport-docker]$ ./scripts/build/nginx.sh 101 | [apps omniport-docker]$ ./scripts/build/memcached.sh 102 | [apps omniport-docker]$ ./scripts/build/rabbitmq.sh 103 | [apps omniport-docker]$ ./scripts/build/postgres.sh 104 | [apps omniport-docker]$ ./scripts/build/redis.sh 105 | 106 | That's all. Omniport Docker is ready to roll. 107 | -------------------------------------------------------------------------------- /docs/source/setting_up/omniport_docs.rst: -------------------------------------------------------------------------------- 1 | Omniport Docs 2 | ============= 3 | 4 | .. note:: 5 | 6 | You must have ``Python 3.8`` and ``pipenv`` installed before you can set 7 | up the documentation locally. 8 | 9 | #. Install the project dependencies. 10 | 11 | .. code-block:: console 12 | 13 | $ pipenv install --skip-lock 14 | 15 | Omit the flag ``--skip-lock`` if you want the latest packages. Keep in mind 16 | that the project has been tested on the versions of the packages specified 17 | in the ``Pipfile.lock`` so its compatibilty with the latest packages might 18 | not be assured. 19 | 20 | #. Start the ``pipenv`` virtual environment via running the following command. 21 | Or you can prefix the commands for starting the server or for building docs 22 | using ``pipenv run``. 23 | 24 | .. code-block:: console 25 | 26 | $ pipenv shell 27 | 28 | #. To start the development server, run the following commands inside ``/docs``. 29 | This will automatically re-build your changes as you make them. 30 | 31 | .. code-block:: console 32 | 33 | $ make dev 34 | 35 | Pass extra flags like port (default: 8000) by suffixing 36 | ``SPHINXDEVOPTS="-p 8080"`` with the above command. 37 | 38 | #. Build the documentation into HTML pages by running the following command 39 | inside ``/docs``. 40 | 41 | .. code-block:: console 42 | 43 | $ make html 44 | 45 | This will create the ``docs/build`` directory. You can preview it using one 46 | of Python's module called ``http.server``. 47 | 48 | #. To build the documentation into some other format, refer to ``make help`` 49 | command for all the options available. 50 | 51 | Cannot start the virtual environment? 52 | ------------------------------------- 53 | 54 | If you keep getting the following error when you try to run ``pipenv shell``: 55 | 56 | .. code-block:: none 57 | 58 | Shell for UNKNOWN_VIRTUAL_ENVIRONMENT already activated. 59 | No action taken to avoid nested environments. 60 | 61 | Run ``exit`` to resolve the issue. You will be able to start the virtual 62 | environment now. 63 | -------------------------------------------------------------------------------- /docs/source/setting_up/production.rst: -------------------------------------------------------------------------------- 1 | Production 2 | ========== 3 | 4 | With everything set up, the flows diverge. This is how to deploy Omniport. 5 | 6 | As ``apps``, enter ``omniport-docker/codebase/omniport-frontend``. Build the 7 | frontend for NGINX to serve. 8 | 9 | .. code-block:: console 10 | 11 | [apps omniport-docker]$ ./scripts/build/frontend.sh 12 | 13 | This should build your React app and place it a folder for NGINX to serve. 14 | 15 | Then just start all services using Docker Compose. 16 | 17 | .. code-block:: console 18 | 19 | [apps omniport-docker]$ docker-compose up -d 20 | 21 | You should be able to access your app on the domains you specified in NGINX, 22 | provided you have the DNS routing properly set up. 23 | 24 | To enter the container for any service, execute this command. 25 | 26 | .. code-block:: console 27 | 28 | [apps omniport-docker]$ docker-compose exec sh 29 | 30 | .. note:: 31 | 32 | Some services, namely those built off of Debian, have ``bash`` installed. Most 33 | don't. So the best way to go about it is to execute ``sh`` and once in the 34 | container, execute ``bash``. 35 | 36 | From time to time, you will have to enter the Django container to make and run 37 | migrations, collect static files and do the occasional housekeeping. 38 | 39 | Relax. -------------------------------------------------------------------------------- /docs/source/setting_up/server_configuration.rst: -------------------------------------------------------------------------------- 1 | Server configuration 2 | ==================== 3 | 4 | To start up, use a fresh installation of your favourite operating system. This 5 | could be any flavour of Linux, such as Ubuntu, Fedora or RHEL, to name a few. 6 | 7 | Ports 8 | ----- 9 | 10 | Ensure that no other services are running on the ports specified below, 11 | especially those marked with an asterisk. 12 | 13 | =============== ===================== 14 | Port Designated use 15 | =============== ===================== 16 | 80* NGINX http 17 | 443* NGINX https 18 | 5432 PostgreSQL 19 | 5672 RabbitMQ 20 | 15672* RabbitMQ management 21 | 11211 Memcached 22 | 6379 Redis 23 | 8000 Gunicorn 24 | 8001 Daphne 25 | 8081* Redis Commander 26 | 60000 - 60031 Django development 27 | 61000 - 61031 React development 28 | =============== ===================== 29 | 30 | In the most common scenarios, 80 and 443 will be occupied on a fresh install 31 | of a server distribution like RHEL or Ubuntu Server. Stop Apache2 and prevent 32 | it from automatically starting up again. 33 | 34 | .. code-block:: console 35 | 36 | [apps ~]$ sudo systemctl stop apache2 37 | [apps ~]$ sudo systemctl disable apache2 38 | 39 | Users 40 | ----- 41 | 42 | Set up a user other than ``root`` to build and manage the containers. Name him 43 | ``apps`` or whatever you fancy. 44 | 45 | In case of a development setup, make user accounts for all your developers, one 46 | per person. Let's assume you have two ``dev1`` and ``dev2``. They also get 47 | their own directories at ``/home/dev1/`` and ``/home/dev2/``. 48 | 49 | .. code-block:: console 50 | 51 | [dev1 ~]$ whoami 52 | dev1 53 | [dev1 ~]$ pwd 54 | /home/dev1 55 | 56 | .. code-block:: console 57 | 58 | [dev2 ~]$ whoami 59 | dev2 60 | [dev2 ~]$ pwd 61 | /home/dev2 62 | 63 | -------------------------------------------------------------------------------- /docs/source/structure/architecture.rst: -------------------------------------------------------------------------------- 1 | Architecture 2 | ============ 3 | 4 | We, the developers of Omniport, pride ourselves on Omniport's architecture. It 5 | is a smart blend of automation and explicitness. We strive to make Omniport as 6 | automated as possible to reduce the amount of code a person has to write to set 7 | it up and extend it, but at the same time not be too *magical* for an ordinary 8 | person to understand, in detail, its functionality. 9 | 10 | Omniport, at its very core, contains a distinction between apps and services. 11 | Apps and services are all Django applications, there is but an ideological 12 | difference between the two categories. 13 | 14 | Services 15 | -------- 16 | 17 | Services are Django apps that provide critical functionality. Services may 18 | depend on other services and on the core. A service may not depend on an app. 19 | Services may depend on other services, which is strongly encouraged because it 20 | leads to a cohesive system. 21 | 22 | All services must be installed for Omniport to function properly. Services 23 | cannot be chosen at will. Services do not contain any form of filtering based 24 | on user roles, corresponding active statuses, or IP addresses. 25 | 26 | Services, and services only, may appear in the Omniport sidebar. The subset of 27 | services that appear in the sidebar are defined by their ``config.json`` file on 28 | the frontend. 29 | 30 | .. seealso:: 31 | 32 | More on frontend configuration files 33 | :doc:`here <../references/config_files/app/config_json>`. 34 | 35 | For an example, consider the service 'Developer', which is used by developers to 36 | develop OAuth2 based applications on Omniport. 37 | 38 | Services are cloned into ``services/`` directories inside the src directory 39 | (``omniport/``) in both the backend and frontend codebases. 40 | 41 | Since there is no mix-and-match capability in Omniport services, the process 42 | of cloning services has been merged with the cloning of the codebases 43 | using the ``clone_codebase.sh`` script provided by ``omniport-docker``. 44 | 45 | .. seealso:: 46 | 47 | More on the ``clone-codebase.sh`` script 48 | :doc:`here <../references/scripts/docker/clone/everything>`. 49 | 50 | Apps 51 | ---- 52 | 53 | Apps are extensions to Omniport that provide new functionality. Apps may depend 54 | on other apps, which is strongly discouraged because it may lead to crashes when 55 | dependencies are forgotten, or on services, which is strongly encouraged because 56 | it leads to a cohesive system. 57 | 58 | Apps can be plugged into the Omniport system as and if needed or wanted. Apps 59 | can be chosen at will. 60 | 61 | All apps can choose their target demographic on the basis of roles and 62 | corresponding active statuses. These filters can be configured in the 63 | ``config.yml`` file on the backend. This leads to every user seeing a set of 64 | apps on the backend. 65 | 66 | .. seealso:: 67 | 68 | More on backend configuration files 69 | :doc:`here <../references/config_files/app/config_yml>`. 70 | 71 | .. math:: 72 | 73 | A = \{\text{apps allowed to a user based on role, active status and orgin IP address}\} 74 | 75 | Then there is a set of apps whose frontend has been installed in the frontend 76 | architecture. This leads to a second set of apps common to every user. 77 | 78 | .. math:: 79 | 80 | B = \{\text{all apps installed on the frontend}\} 81 | 82 | The net set of apps that any user sees is the intersection of both these sets. 83 | 84 | .. math:: 85 | 86 | Result = A \cap B 87 | 88 | Apps are cloned into ``apps/`` directories inside the src directory 89 | (``omniport/``) in both the backend and frontend codebases. 90 | 91 | Dependencies 92 | ------------ 93 | 94 | :: 95 | 96 | service ---may depend on--> core 97 | service ---may depend on--> service 98 | app ---may depend on--> core 99 | app ---may depend on--> service 100 | -------------------------------------------------------------------------------- /docs/source/structure/folder_structure.rst: -------------------------------------------------------------------------------- 1 | Folder structure 2 | ================ 3 | 4 | Omniport follows this outline of folder configuration. Omniport Docker houses 5 | both sides of the codebase in a ``codebase/`` folder. 6 | 7 | :: 8 | 9 | omniport-docker 10 | ├── docker-compose.yml 11 | ├── scripts 12 | │ └── ... 13 | ├── django 14 | │ ├── Dockerfile 15 | │   └── ... 16 | ├── react 17 | │ ├── Dockerfile 18 | │   └── ... 19 | ├── nginx 20 | │ ├── Dockerfile 21 | │   └── ... 22 | └── codebase 23 | ├── omniport-backend 24 | │   ├── scripts 25 | │   │ └── ... 26 | │   ├── omniport 27 | │ │ ├── core 28 | │ │ ├── shell* 29 | │ │ ├── services 30 | │ │ ├── apps 31 | │   │ └── ... 32 | │ └── ... 33 | └── omniport-frontend 34 |    ├── scripts 35 |    │ └── ... 36 |    ├── omniport 37 | │ ├── core 38 | │ ├── formula_one 39 | │ ├── services 40 | │ ├── apps 41 |    │ └── ... 42 | └── ... -------------------------------------------------------------------------------- /docs/source/structure/index.rst: -------------------------------------------------------------------------------- 1 | Structure 2 | ========= 3 | 4 | To keep the code clean and keep the repository histories from mangling with 5 | each other, each distinct component of Omniport lives in its own repository, 6 | free from the scaffolding and core codebases, yet dependent on them for 7 | functioning. 8 | 9 | Read on to learn more about the structure of Omniport. 10 | 11 | .. toctree:: 12 | :caption: Subsections: 13 | 14 | repositories 15 | folder_structure 16 | architecture -------------------------------------------------------------------------------- /docs/source/structure/repositories.rst: -------------------------------------------------------------------------------- 1 | Repositories 2 | ============ 3 | 4 | Omniport is not a single repository. The entire project is made up 5 | of dozens of distinct, yet interconnected parts, most of which have their own 6 | repositories under the `IMGIITRoorkee `_ 7 | GitHub organisation page. This means that cloning the Omniport project is not 8 | one operation but many. 9 | 10 | The essential ones of these repositories are explained here. 11 | 12 | Infrastructure 13 | -------------- 14 | 15 | This repository contains the code that drives the Omniport infrastructure. 16 | That means that all ``Dockerfiles``, environment variables and build scripts 17 | are kept in this repository. 18 | 19 | .. image:: https://img.shields.io/badge/omniport-infrastructure-red.svg?style=flat-square 20 | :target: https://github.com/IMGIITRoorkee/omniport-docker/ 21 | 22 | .. image:: https://img.shields.io/github/license/IMGIITRoorkee/omniport-docker.svg?style=flat-square&logo=github&logoColor=white 23 | :target: https://github.com/IMGIITRoorkee/omniport-docker/ 24 | 25 | .. image:: https://img.shields.io/github/last-commit/IMGIITRoorkee/omniport-docker.svg?style=flat-square&logo=docker&logoColor=white 26 | :target: https://github.com/IMGIITRoorkee/omniport-docker/ 27 | 28 | Codebase 29 | -------- 30 | 31 | Omniport backend 32 | ++++++++++++++++ 33 | 34 | This repository contains the code of the Omniport backend architecture, 35 | written in Django on Python. This includes all the core functionality of 36 | the project and is extensible in terms of choosing your own set of apps to 37 | run on it. 38 | 39 | This backend can be customised and branded according to your own wishes. 40 | All configuration and branding lies in directories outside the code so that 41 | you do not have to know development to set the project up. 42 | 43 | .. image:: https://img.shields.io/badge/omniport-backend-orange.svg?style=flat-square 44 | :target: https://github.com/IMGIITRoorkee/omniport-backend/ 45 | 46 | .. image:: https://img.shields.io/github/license/IMGIITRoorkee/omniport-backend.svg?style=flat-square&logo=github&logoColor=white 47 | :target: https://github.com/IMGIITRoorkee/omniport-backend/ 48 | 49 | .. image:: https://img.shields.io/github/last-commit/IMGIITRoorkee/omniport-backend.svg?style=flat-square&logo=django&logoColor=white 50 | :target: https://github.com/IMGIITRoorkee/omniport-backend/ 51 | 52 | Omniport frontend 53 | +++++++++++++++++ 54 | 55 | This repository contains the code of the Omniport frontend architecture, 56 | written in React on JavaScript. This includes all the core functionality of 57 | the project and can be extended with apps, that are independent of the 58 | backend. 59 | 60 | This frontend takes all the customisations from the backend and is therefore 61 | totally branding-ready and tweakable. All changes on the backend are 62 | reflected here with very little to almost no effort. 63 | 64 | .. image:: https://img.shields.io/badge/omniport-frontend-yellow.svg?style=flat-square 65 | :target: https://github.com/IMGIITRoorkee/omniport-frontend/ 66 | 67 | .. image:: https://img.shields.io/github/license/IMGIITRoorkee/omniport-frontend.svg?style=flat-square&logo=github&logoColor=white 68 | :target: https://github.com/IMGIITRoorkee/omniport-frontend/ 69 | 70 | .. image:: https://img.shields.io/github/last-commit/IMGIITRoorkee/omniport-frontend.svg?style=flat-square&logo=react&logoColor=white 71 | :target: https://github.com/IMGIITRoorkee/omniport-frontend/ 72 | 73 | Shell 74 | ----- 75 | 76 | As we previously mentioned, Omniport is a portal that is epically generic. 77 | Any institute around the world, from Fiji to Fiji the other way, can set it 78 | up and get going. 79 | 80 | But if your institute has the technical know-how that a group like IMG 81 | provides IIT Roorkee, you can easily *swap* out models in the ``kernel`` 82 | module of ``omniport-backend`` with your own. You can also *switch* out the 83 | serializers in the ``kernel`` module with your own. 84 | 85 | This swap and switch functionality can be made use of to develop shells for 86 | the backend as we have made one for our institute. You are free to refer to 87 | it to make your own, or run the fully functional, unshelled versions of the 88 | software. 89 | 90 | .. image:: https://img.shields.io/badge/omniport-shell-blue.svg?style=flat-square 91 | :target: https://github.com/IMGIITRoorkee/omniport-shell/ 92 | 93 | .. image:: https://img.shields.io/github/license/IMGIITRoorkee/omniport-shell.svg?style=flat-square&logo=github&logoColor=white 94 | :target: https://github.com/IMGIITRoorkee/omniport-shell/ 95 | 96 | .. image:: https://img.shields.io/github/last-commit/IMGIITRoorkee/omniport-shell.svg?style=flat-square&logo=django&logoColor=white 97 | :target: https://github.com/IMGIITRoorkee/omniport-shell/ 98 | 99 | .. note:: 100 | 101 | Other than the shell for **Indian Institute of Technology, Roorkee**, any 102 | shells made for Omniport are not under the purview of Information Management 103 | Group. 104 | 105 | IMG couldn't possibly take responsibility for the upkeep, maintenance or 106 | upgradation of any random shells made by any random developers for any random 107 | institutes of any random country. 108 | 109 | Sub-components 110 | -------------- 111 | 112 | Apart from these repositories are Omniport itself, there are a huge number of 113 | repostories that are a part of Omniport. These are apps and services. 114 | 115 | Every single one of Omniport's many apps and services resides in its own 116 | repository. They follow a naming convention as follows. 117 | 118 | - ``omniport-service-`` and ``omniport-frontend-`` 119 | - ``omniport-app-`` and ``omniport-frontend-`` 120 | 121 | Totalled, these repositories number in the fifties. But since these are on an 122 | open architecture, there is total democracy and freedom regarding who can create 123 | apps and what those apps can provide. This number has no upper limit. -------------------------------------------------------------------------------- /readme-assets/maintainers/wordmark.svg: -------------------------------------------------------------------------------- 1 | img_wordmark -------------------------------------------------------------------------------- /readme-assets/site/wordmark.svg: -------------------------------------------------------------------------------- 1 | op_wordmark -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | alabaster==0.7.12 2 | argh==0.26.2 3 | Babel==2.8.0 4 | certifi==2020.6.20 5 | chardet==3.0.4 6 | docutils==0.16 7 | idna==2.10 8 | imagesize==1.2.0 9 | Jinja2==2.11.2 10 | jsx-lexer==0.0.8 11 | livereload==2.6.2 12 | MarkupSafe==1.1.1 13 | packaging==20.4 14 | pathtools==0.1.2 15 | port-for==0.3.1 16 | Pygments==2.6.1 17 | pyparsing==2.4.7 18 | pytz==2020.1 19 | PyYAML==5.3.1 20 | requests==2.24.0 21 | six==1.15.0 22 | snowballstemmer==2.0.0 23 | Sphinx==3.1.1 24 | sphinx-autobuild==0.7.1 25 | sphinxcontrib-applehelp==1.0.2 26 | sphinxcontrib-devhelp==1.0.2 27 | sphinxcontrib-htmlhelp==1.0.3 28 | sphinxcontrib-jsmath==1.0.1 29 | sphinxcontrib-qthelp==1.0.3 30 | sphinxcontrib-serializinghtml==1.1.4 31 | tornado==6.0.4 32 | urllib3==1.25.9 33 | watchdog==0.10.3 34 | --------------------------------------------------------------------------------