Installing a preview site

This document explains why and how to set up and use a preview site to manage releases on bigger Lino production sites. See also Upgrading a Lino production site for one-step upgrades on smaller sites. See Data migrations à la Lino for technical background information.

General infrastructure

A preview site is a separate Lino site with its own subdomain, its own project directory, Python environment and database. But that data is just a mirror of another site, usually the production site.

A same site operator will have a a series of sites, one in "production" state and maybe another in "preview" state. Every site has its "life cycle" : it typically starts as a "preview" site, then becomes the "production" site, and maybe afterwards remains alive for some time as the "old" site.

Remember that virtual environments cannot change their name. So please give your project directories neutral names like "mdg1", "mdg2", "mdg3". Do not call them not "preview", "old", "new", "testing" or "prod".

Setting up a preview site

When the site operator asks for an upgrade, you start by setting up a new preview site.

  • Copy the current production project directory to a new directory:

    $ df -h
    $ cp -a afoo bfoo
    
  • In the afoo directory run:

    $ python manage.py dump2py snapshot2preview
    

    Create a file restore2preview.py in the production snapshot as a copy of the restore.py file.

  • In the bfoo directory:

  • Let the log directory point to a different directory:

    $ rm log
    $ mkdir /var/log/lino/bfoo
    $ ln -s /var/log/lino/bfoo log
    
  • Have a look at all the following files in the preview project and replace afoo with bfoo where needed:

    settings.py, manage.py wsgi.py pull.sh make_snapshot.sh initdb_from_prod.sh etc

  • Remove the env directory in the copy and create a new one with virtualenv. Activate the new env. Run pull.sh to update repositories. Install Lino from repositories.

  • Create the new database in mysql or pg

  • Run pull.sh

  • Run collectstatic

  • Run initdb_from_prod.sh and adapt restore2preview.py where needed.

  • Add a vhost to make the preview site accessible to end-users

  • Setup a web page for release notes which serves as a roadmap to you and the users.

Synchronizing the preview site

During the preparation phase you run repeatedly a script that synchronizes the preview site, i.e. migrates the production data to the preview site:

$ go preview
$ ./initdb_from_prod.sh

Upgrade attempts

When you and the users agree that preview seems ready for production, you announce a date and time for an upgrade attempt.

An upgrade attempt lasts an agreed lapse of time (e.g. one hour).

As the hosting provider you make sure that the preview site has been synchronized from the production site.

During the upgrade attempt users must test whether everything works as expected. They must be aware that their changes during this time might get lost in case they decide to cancel the attempt, and that they will remain if the attempt succeeds.