Enable Sites Framework

HELIPORT requires Django’s sites framework to be enabled. The site framework allows us to make use of certain builtin features such as generation of sitemaps and RSS/Atom feeds. Earlier versions of HELIPORT did not require and thus did not enable this framework. The allauth framework which HELIPORT uses for authentication changes its database migrations depending on whether the sites framework is enabled. When upgrading to HELIPORT versions newer than 0.7.0, this can lead to database migration issues during the heliport-cli migrate command:

django.db.migrations.exceptions.InconsistentMigrationHistory: Migration socialaccount.0001_initial is applied before its dependency sites.0001_initial on database 'default'.

As of allauth version 65, only its first migration causes an issue for HELIPORT. This guide explains how to fix these inconsistencies manually.

Prerequisites

This guide only applies when upgrading HELIPORT instances with HELIPORT version 0.7.0 or older. Newer installations do not run into this issue.

In order to follow this guide, you need to figure out where the allauth library within your installation stores its migrations. The following code snippet can be run within a Python interpreter (heliport-cli shell) to print out the correct path. Make sure this path exists and note it down for later.

from pathlib import Path
from allauth import socialaccount

migrations = Path(socialaccount.__file__).parent / "migrations"
print(migrations)

The upgrade procedure also requires you to manually run some SQL code to generate a missing database table and some indices during the process. To figure out the exact SQL commands for your database, you can use the differences between the outputs of heliport-cli sqlmigrate socialaccount 0001 of the old and new HELIPORT versions (i.e. with the sites framework disabled and enabled). The following Python snippet can be used from within the Python interpreter (heliport-cli shell). As an example, the SQL commands for an SQLite database are shown:

from django.db import connection

with connection.cursor() as cursor:
    cursor.execute("""CREATE TABLE "socialaccount_socialapp_sites" ("id" integer NOT NULL PRIMARY KEY AUTOINCREMENT, "socialapp_id" integer NOT NULL REFERENCES "socialaccount_socialapp" ("id") DEFERRABLE INITIALLY DEFERRED, "site_id" integer NOT NULL REFERENCES "django_site" ("id") DEFERRABLE INITIALLY DEFERRED);""")
    cursor.execute("""CREATE UNIQUE INDEX "socialaccount_socialapp_sites_socialapp_id_site_id_71a9a768_uniq" ON "socialaccount_socialapp_sites" ("socialapp_id", "site_id");""")
    cursor.execute("""CREATE INDEX "socialaccount_socialapp_sites_socialapp_id_97fb6e7d" ON "socialaccount_socialapp_sites" ("socialapp_id");""")
    cursor.execute("""CREATE INDEX "socialaccount_socialapp_sites_site_id_2579dee5" ON "socialaccount_socialapp_sites" ("site_id");""")

HELIPORT does not use these tables, they can be left empty.

Upgrade Process

  1. Shut down all HELIPORT services (HELIPORT application server and workers).

  2. Install the newest version of the code. Note that in the settings module, the sites framework is enabled (i.e. django.contrib.sites is in INSTALLED_APPS, and SITE_ID is set to 1).

  3. Find the socialaccount migration scripts (see code above to find them) and move them to a backup location, e.g. mv migrations migrations.bak.

  4. Run the migration scripts for the site framework: heliport-cli migrate sites.

  5. Create the table (see SQL code above).

  6. Restore the socialaccount migration scripts, e.g. mv migrations.bak migrations.

  7. Run the deployment script as usual.

  8. Finally, navigate to the admin interface at /admin/sites/site/1/change/ and configure the domain name and display name of your HELIPORT instance. Example: heliport.example.com and HELIPORT at Example Institution.