okfn.org

This is the Django/Django CMS project that runs http://okfn.org.

When do I need to modify this?

http://okfn.org/ runs on Django CMS.

Most of the contents are provided via plugins and our communication person is currently responsible to edit the content or add new stuff to the site. It is the idea, and the goal of the development that all content is dinamically handled by plugins. This means that we are aiming to have templates with placeholders instead of text. So, if you need to modify content, probably you can already do it using Django CMS built in capabilities.

If we need to make global styling or data model changes, then we need to edit the code in this repo.

Prerequisites and assumptions

You must have the following installed:

• Python 3.10
• Node JS 16

The /Dockerfile (used for staging/production) and the requirements file (built with pip-tools) in this repo shows you the application dependencies.

Development

Database

It is possible to run the app with no database content. If databaset settings are not set, we fall back to a blank SQLite database (defined in the .env.base file) so this step can be skipped for a minimal case.

To run with a database, you will need a local Postgres server.

• Get a dump of the database (we store them as *.sql in Google Cloud Storage)
• Create a local database sudo -u postgres createdb okfn
• Populate it sudo -u postgres psql okfn < file=/path/to/dump.sql or sudo -u postgres pg_restore -d okfn path/to/dump.dump

Running the application

Cherry-pick environment variables from .env.example you'd like to set and add it to the .env file. If no env vars are set, we will fall back to default .env.base file.

If running with Postgres, you will need to set:

DB_ENGINE=django.db.backends.postgresql_psycopg2
DB_NAME=okfn
DB_USER=user
DB_PASSWORD=pass
DB_HOST=localhost
DB_PORT=5432

Prepare the app:

Make sure to have the correct node version:

nvm install 16
nvm use 16

Create a Python 3.10 local environment (e.g. python3.10 -m venv ~/okf-website-env)

pip install -r requirements.txt
pip install -r requirements.dev.txt
npm install
python manage.py migrate
python manage.py update_index

Start the server:

python manage.py runserver

Another option is to use Docker.

docker build -t okfn .
docker run -d -p 8888:80 okfn

File uploads

Because this is a CMS project, a lot of the site content is created via the web UI. This means a lot of the images on the site are file uploads. In staging and production, the uploaded files are hosted on Google Cloud Storage.

If you want to get all production/staging media files you can download them from Google Cloud Storage and put them in a local media directory (MEDIA_ROOT from settings).

Note: A dump of the production database will require all the media files of production. Same for staging.

Frontend

CSS

Currently we are using Tailwind, PostCSS as our CSS stack. Please check the documentation to get a sense of how it works: Installing Tailwind CSS as a PostCSS plugin

The css build is done by PostCSS and the configuration files for it are tailwind.config.cjs and postcss.config.cjs.

Running npm run build will compile our main styles.css file and place it in static/css/styles.css. (It then will be collected by Django when building the Dockerfile)

Remember: Tailwind CSS works by scanning all of our HTML files, JavaScript components, and any other templates for class names to generate styles.css. If you ar adding new files, make sure to update the content field tailwind.config.cjs. (If required)

Javascript

We have some minimal Javascript features in the website. Our dependencies are in js/vendor/* and our main script in js/main.js.

Backend (Django and django-cms)

New plugins for blocks of content are located on foundation/okfplugins.

1. Create a folder on foundation/okfplugins having:

• admin.py: used on Django Admin interface
• cms_plugin.py: configuration to appear on the Django CMS content editor sidebar
• templates/: the django template files (access the plugin variable defined on models.py with instance.VARIABLE)
• models.py: the model for the plugin object on the database

You can copy a simple plugin as heading or just_text and change the files above. If you do that don't forge to delete the migration files inside migrations/, except by init.py.

2. Add the plugin to foundation/settings.py (INSTALLED_APPS setting).

3. Run python manage.py makemigrations after you create the models.py.

4. Run the migration to change the database with python manage.py migrate

5. Start the server with python manage.py runserver

References for new design and components

• Components: https://ishigami.github.io/okfn_front/components
• More components: https://ishigami.github.io/okfn_front/components-2.html
• Homepage: https://ishigami.github.io/okfn_front/
• Source: https://github.com/ishigami/okfn_front

Deployment

Production deployment is based on this Dockerfile. When we want to deploy, we just push to main branch (or develop branch for staging environment).

For more info read this doc.

Dependency Management

Dependencies are managed with pip-tools. Add new packages to requirements.in / requirements.dev.in and compile requirements.txt / requirements.dev.txt with pip-compile.

You can run pip list --outdated to see outdated packages.

Changelog

All changes must be documented at the CHANGELOG file