Portability Map

A way to search a content repository of portability solutions

PortMap is an open-source Django project that hosts structured query access to a content repository of portability solutions.

PortMap pulls articles on portability solutions from the portability-articles repository, which is where volunteers can contribute content.

The articles are organized by topic, data type, source and destination, and cached in a PostgreSQL DB. The DB also captures query data so we can learn what users most need to find.

Dependency management is by the process recommended in "Boost Your Django DX" and in Adam Johnson's blog posts: use pip, venv, and requirements.txt. For dev requirements, also use pip to install ipython...

PortMap's original project organization is from Sidewinder, a django starter project template, which set us up with:

environment variables (and the 'environ' package) instead of juggling multiple configuration files
Use HTMX for modern frontends
Use django-allauth to provide email-based and 3rd party authentication.
Have a custom User model for ultimate flexibility
auto reloading, debugging and profiling tools, linters and formatters
Log anything you want with structured logging
Execute automated tests using the best testing library pytest
Write test fixtures efficiently using factoryboy and Faker

Local development

First time setup

You will need Python 3 and pip (python -m ensurepip --upgrade). PortMap also requires a PostgreSQL database for storing artices; create one locally named "portmap" and start it.

Get the private key file from @lisad for accessing the GitHub API. This should not be checked into git, so please don't put it in this repository!
Make a copy of .env-example and name it .env. This is where your local configuration will be stored; it's not checked into git.
In your new .env file, change DJ_DATABASE_CONN_STRING to point to your local PostgreSQL database.
Also in your .env file, change GITHUB_PRIVATE_KEY_PEM_FILE=<path to the key file from step 1>.
Install dependencies with pip.

python -m pip install -r requirements.txt

Note: This may fail if you're missing external dependencies; you'll need to inspect the output and install whatever is missing (e.g. python3-devel, gcc, libpq-devel)

Initialize your PostgreSQL database.

./manage.py migrate

Create a superuser for yourself for accessing the database management portal.

./manage.py createsuperuser

Start the server. By default it will listen for requests at http://localhost:8000

./manage.py runserver

To populate your local database with articles from https://github.com/dtinit/portability-articles, go to https://localhost:8000/dj-admin and enter your superuser credentials from step 7. Click on "Articles" (under "Core"), and then press the "Populate Articles" button in the top right.
(Optional step for running tests locally) Install playwright dependencies.

playwright install

Frontend

Frontend dev tools like ESLint are delivered via npm, which is included with Node.js. To use the tools locally, you'll need to:

Install Node.js.
Run npm install wherever you cloned this repository to.

Linting with ESLint

You can run the linter by executing npm run lint. If there are no issues, there won't be any output.

To get linting feedback in your code editor, check here to find an ESLint integration or instructions for your editor. The configuration file is named .eslintrc.json, but your editor will probably find it for you.

Formatting with Prettier

You can format JavaScript and CSS files with npm run format.

To enable formatting from your code editor, check here for instructions for your editor. The configuration file is named .prettierrc, but your editor will probably find it for you.

Testing

Make sure playwright is installed (playwright install), then run pytest to run both unit and end-to-end tests.

Deployments

Deployments to production are triggered automatically by updates to the main branch, or when this repository receives a "content update" notification from https://github.com/dtinit/portability-articles. You can observe the status of deployments here.