=============
Miscellaneous
=============

.. _getlino.config:

Configuration files
===================

The location of the file getlino uses to store its configuration depends on
whether you are root or not.

.. xfile:: ~/.getlino.conf

  The file getlino uses to store its configuration when not running as root.

.. xfile:: $VIRTUAL_ENV/.getlino.conf

  The file getlino uses to store its configuration when running as root in a
  virtual environment.

.. xfile:: /etc/getlino/getlino.conf

  The file getlino uses to store its configuration when running as root in a
  system python environment (which currently is not recommended but might make
  sense e.g. when Lino becomes a Debian package).


Configuration reference
=======================

.. currentmodule:: getlino

.. data:: usergroup

  The Linux usergroup to set as group owner of files that need to be writeable
  by :term:`django-admin commands <django-admin command>` and the web server.

  You can specify this on the command line as :option:`getlino configure --usergroup`.

  Default value is ``www-data``

  This is needed only on a :term:`production site` with a :data:`web_server` It
  is ignored when the specified group doesn't exist.


.. data:: supervisor_dir

  The directory where :cmd:`supervisor`

.. data:: web_server

  Which web server to use on this production server. This can be "nginx",
  "apache" or empty. When this is empty, :cmd:`getlino configure` won't install
  any web server. You should not change this value when there is already at
  least one :term:`Lino site` on this server.


Shared virtual environments
===========================

You can run multiple Lino sites on a same :term:`virtualenv`.  That virtualenv
is then called a *shared* environemnt.

When you update a shared environment (using :xfile:`pull.sh` or some manual pip
command), the change will affect all sites at once and you must take special
care for migrating their data.

In a :term:`developer environment` you usually have a single shared environment
used by all your sites.  On a :term:`production server` you usually have no
shared environment at all (each production site has its own env). On a :term:`demo
server` you might have several shared environments:

- /usr/local/lino/venvs/main
- /usr/local/lino/venvs/stable

You can specify a *default* shared environment with
:option:`getlino configure --shared-env`
:option:`getlino startsite --shared-env`.

Note that :option:`getlino configure --clone` will install all known framework
repositories into the default shared environment.

:cmd:`getlino startsite` does not install any Python packages when a shared
environment is used.


Scripts generated by getlino
============================


.. xfile:: pull.sh

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

    Generated by :cmd:`getlino configure` and/or :cmd:`getlino startsite`
    whenever Lino creates a virtualenv.

    This file is stored in the :file:`$VIRTUAL_ENV/bin` directory and is
    executable.

    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
