.. _admin.upgrade:

================================
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 :doc:`/admin/preview` for
are more sophisticated approach on sites with many users.  See also
:doc:`/dev/datamig` for technical background information.


- Go to your project directory::

    $ go myproject

  See :cmd:`go` if you don't know that command.

- Activate the python environment (we usually have a shell alias
  :cmd:`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  # not needed when the server runs nginx
    $ sudo service supervisor stop

- Run :xfile:`make_snapshot.sh` to make a snapshot of your database::

    $ ./make_snapshot.sh

  See :doc:`/admin/snapshot` for details.

- Run :xfile:`pull.sh` to update the source code::

    $ pull.sh

- Run the :manage:`install` command to install any new Python dependencies if needed::

    $ python manage.py install

- Run the :manage:`collectstatic` command::

    $ python manage.py collectstatic

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

- Restore the snapshot::

    $ python manage.py run snapshot/restore.py

  You can skip this if you are sure that there is no change in the database structure.

  You can run :xfile:`restore.py` also "just in case", it doesn't do any harm when
  there were no changes in the database structure.

  Running :xfile:`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 :xfile:`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 :xfile:`restore.py` files.  If nothing
  has changed (i.e. :cmd:`diff` gives no output), then you don't need to run the
  :xfile:`restore.py`.

  In case the :xfile:`restore.py` gives error messages, you need to ask support
  from the :term:`application developer` because it's their job to specify the
  details of what happens during the data migration by providing migrators (as
  documented in  :ref:`lino.datamig`).

- Start the web server and supervisor::

    $ sudo service apache2 start
    $ sudo service supervisor start


Glossary
========


.. xfile:: pull.sh

    Update the Python packages used by this :term:`virtualenv`.

    This file is generated by :cmd:`getlino startsite`.

    This includes both the packages installed from cloned source code
    repositories and those installed via PyPI.

    Template: https://github.com/lino-framework/getlino/blob/master/getlino/templates/pull.sh