Upgrading a Lino production site

This document gives generic instructions for upgrading a Lino production site to a new version. This procedure is suitable for smaller sites with one contact person. See Installing a preview site for are more sophisticated approach on sites with many users.

  • Go to your project directory:

    $ go myproject

    See go if you don’t know that command.

  • Activate the python environment (we usually have a shell alias a which expands to . env/bin/activate):

    $ a
  • Stop any services that might want to write to the database (web server, supervisor):

    $ sudo service apache2 stop
    $ sudo service supervisor stop

    NB: there is no need to stop nginx at the beginning of the upgrade. But we will restart it later after collectstatic (which is needed to make sure that static files get out of the cache).

  • Run make_snapshot.sh to make a snapshot of your database:

    $ ./make_snapshot.sh

    See Making a snapshot of a Lino database for details.

  • Make sure that the snapshot is correctly done by looking at the timestamp of the snapshot.zip file:

    $ ls -l snapshot.zip
  • Run pull.sh to update the source code:

    $ pull.sh
  • Restore the snapshot:

    $ python manage.py run snapshot/restore.py

    Make sure that it ends with something like:

    Done manage.py run snapshot/restore.py (PID 20651)
  • You might want to skip this step if you are sure that there is no change in the database structure. You can run restore.py also “just in case”, it doesn’t do any harm when there were no changes in the database structure. Running restore.py just in case does no harm, but it can take much time for a bigger database. After all this command drops all database tables, re-creates them, and then fills every single data row into it. So instead of running restore.py “just in case” you might prefer check whether you need to run it:

    $ python manage.py dump2py -o t
    $ diff snapshot/restore.py t/restore.py

    That is, you make a second temporary snapshot (which takes much less time than restoring it) and then compare their restore.py files. If nothing has changed (i.e. diff gives no output), then you don’t need to run the restore.py.

    In case the restore.py gives error messages, you need to ask support from the application developer because it’s their job to specify the details of what happens during the data migration by providing migrators.

  • Run the install command to install any new Python dependencies if needed:

    $ python manage.py install

    You can skip this step when you know that there were no new Python dependencies.

  • If the site uses lino.modlib.elastic, run the buildindexes command:

    $ python manage.py buildindexes

    This step can be skipped if there were no changes in the database schema.

  • Run the collectstatic command:

    $ python manage.py collectstatic

    This step can be skipped if there were no changes in the static files.

  • During restore from backup we may encounter messages like “Deferred CheckListItem #2 (‘CheckListItem object (2)’) : {‘ticket’: [‘Ticket instance with id 3762 does not exist.’]}”. Such “Deferred…” messages are normal during the restore process. No problem as long as it continues “Trying to save X deferred objects”. Problem is only when it ends with saying “Abandoned with X unsaved objects”.

  • Start the web server and supervisor:

    $ sudo service apache2 start  # apache
    $ sudo service nginx restart # nginx
    $ sudo service supervisor start
  • Sign in to the site and look whether everything seems okay.