Board Resolution Information System (BRIS)
How to setup a local development server?
If you're looking to install this site on a deployment environment immediately (you don't intend to develop), follow this guide instead.
Python and Django
- Download Python 3.10.
- (IMPORTANT) Use these steps to install your Python!
- Check Add to PATH.
- Click Custom Install.
- Click Next.
- Check Install for All Users.
- IMPORTANT! Change install location to
C:\Python310
only! Remove the Program Files. - Install and done.
- Install pipenv.
pip install pipenv
- Clone this repository and open the folder in Visual Studio Code. Using the terminal within
vscode
(CTRL + `
), run the following to install required Python packages:
pipenv install
- Comment out
'mod_wsgi.server'
in board_resolution_is/settings.py:
INSTALLED_APPS = [
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
# For Deployment
# 'mod_wsgi.server',
...
]
NOTE: To always activate the virtual environment created by pipenv
in every terminal of vscode
, follow the instructions here.
PostgreSQL Database
Database Name: db_board_resolution_is
- Install PostgreSQL.
- NOTE: Remember your password!
- 14.2 (Latest)
- Create a database by:
- Run
psql
. On Windows, search forpsql
. - Enter your password.
- Run
CREATE DATABASE db_board_resolution_is;
- Take note of the semicolon.
- Verify if database is created by entering
\l
inpsql
.
- Run
Set Environment Variables
Setup environment variables in your PC / server:
PSQL_PASSWORD
= Your password set when installing PostgreSQL.BRIS_SECRET
= Run this command in acmd
and get the value:
py -c "import secrets; print(secrets.token_hex(64))"
BRIS_DEBUG
=True
(set this toTrue
for local development only. If you're already deploying/installing, you should remove this environment variable)NPM_BIN_PATH
= See this
Optional environment variables:
PSQL_BRIS_DBNAME
= Name of your DB in PostgreSQL (default:db_board_resolution_is
)PSQL_USER
= User in psql (default:postgres
)PSQL_HOST
= IP Address where database is located (default:127.0.0.1
)PSQL_PORT
= Port that PostgreSQL runs on (default:5432
)
Note: You need to restart vscode
or the web server (if deployed) to fetch/refresh the new environment variables.
Password Reset via Email using Gmail App Passwords
For password reset using email, you need to add a Gmail Account with 2FA enabled. Add an App Password, and take note of the password. Then assign the following environment variables:
BRIS_EMAIL_USERNAME
- Your Gmail Account (email address).BRIS_EMAIL_PASSWORD
- The generated App Password.
Note: If you changed your password on Google, all App Passwords are revoked and you'll need to generate one (and replace the environment variable).
Generate Database Tables
- Go to root folder of project.
- (venv) Run
py manage.py migrate
.
TailwindCSS (Front-end CSS Framework)
- Install node.js first.
- We need to tell django where the npm is installed if it cannot find it. On a cmd (Windows), run:
where npm
Copy the full file path with the npm.cmd
. Then add it to an environment variable with the name:
NPM_BIN_PATH
= C:\...\nodejs\npm.cmd
py manage.py tailwind install
Read more here.
Use VSCode Tailwind CSS IntelliSense extension for previews.
VS Marketplace Link: https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss
Tesseract OCR
Tesseract OCR is used to detect the text content of the images uploaded. To install:
- Download an installer of the Tesseract binaries: https://tesseract-ocr.github.io/tessdoc/Home.html#binaries. Follow the installer steps.
- For Windows: Add the install location to
PATH
environment variable (Default:C:\
)
Setup Python Interpreter (For automatic activation of virtual environment)
Install the Python Extension in VSCode.
Then, we can setup the VSCode Terminal (CTRL + `
) to always activate our virtualenv, where our required packages are installed. Use CTRL + SHIFT + P
and search for Python: Select Interpreter
. Select the one created at the earlier step (pipenv shell
).
After doing so, everytime we open a terminal in VSCode, we should see the name of virtualenv in the beginning of each line, like so:
(board_resolution_is) C:\Users\...\board_resolution_is>
Run the local server
Run the following:
py manage.py runserver
py manage.py tailwind start
This will run a local server and setup TailwindCSS hot-reload. Open the web app using the link shown.
NOTE: If os.environ
throws a KeyError, and you already made sure you set the environment variables, restart the cmd (or vscode) because this variables are not loaded on old console sessions.
Load Mock Data
To install mock data (resolutions and certificates only, no images), run the following:
py manage.py loaddata .\etc\MOCK_DATA.json
Important Contribution Notes
Auto-formatting in VSCode
When you're using Alt + Shift + F
to automatically beautify / format the code, make sure that you use Beautify instead of Prettier. Prettier breaks the templating language by forcing multiple lines into a single one.
- Open an HTML file.
- Open the command palette
CTRL + SHIFT + P
Format Document With...
Configure Default Formatter...
- Select
Beautify
How to Deploy?
Prepare the packages and files first.
Collect all Static Files:
In the venv (pipenv shell
to activate), run:
py manage.py tailwind build
py manage.py collectstatic
Update requirements.txt and Installing Packages Globally
- Activate venv:
pipenv shell
- Generate requirements.txt:
pipenv requirements > requirements.txt
- Exit venv! (type
exit
in cmd). Use regular cmd on project folder. Install packages globally on server:pip install -r requirements.txt
Update settings.py
When deploying, remove the BRIS_DEBUG
environment variable!
For Windows
We have two options for Windows, a pure Python web server, or using mod_wsgi:
- Deployment guide using Apache HTTP Server and mod_wsgi (Recommended, Tested).
- Deployment guide using waitress + whitenoise + nssm
- Pure Python
- Heroku compatible but cannot store user-uploaded files (see this for reason).
- DO NOT USE this yet! Serving media files is still a problem for internal use apps.