Welcome | Get started | Dive | Contribute | Topics | Reference | Changes | More

Introduction to config directories

Lino has a concept of configuration directories that are a bit like Django’s templates directories.

Side note: Code snippets (lines starting with >>>) in this document get tested as part of our development workflow. The following initialization snippet tells you which demo project is being used in this document.

>>> import os
>>> os.environ['LINO_CACHE_ROOT'] = '' # disable for this doctest
>>> from lino import startup
>>> startup('lino_book.projects.confdirs.settings')
>>> from lino.api.doctest import *

Concepts

The settings.SITE.confdirs attribute holds a singleton instance of lino.utils.config.ConfigDirCache, which is the registry for config directories. It is initialized once at startup.

config

A directory named config that is collected at startup into a list of directories to be searched when looking for configuration files.

plugin configuration directory

A config directory in the source directory of a plugin.

site configuration directory

A config directory in the project directory of a Lino site.

local configuration directory

A site configuration directory that contains locally customized template files.

Site config dirs are searched before plugin config dirs.

>>> settings.SITE.confdirs  
<lino.utils.config.ConfigDirCache object at ...>

>>> for cd in settings.SITE.confdirs.config_dirs:
...     print(cd.name, cd.writeable)  
/.../lino_book/projects/confdirs/config True
/.../lino_xl/lib/contacts/config False
/.../lino/modlib/users/config False
/.../lino/modlib/printing/config False
/.../lino/modlib/extjs/config False
/.../lino/modlib/bootstrap3/config False
/.../lino/modlib/jinja/config False
/.../lino/config False

The local configuration directory

All configuration directories are read-only (maintained by the application developer) except one: the local configuration directory.

>>> rt.find_config_file('admin_main.html')  
'.../lino_book/projects/confdirs/config/admin_main.html'

How to make local print templates editable by end users

Some end users want to be able to configure themselves certain templates.

First step : make a local copy of the relevant templates:

$ go mysite
$ cp -a env/lib/python3.6/site-packages/lino_xl/lib/trading/config .

Second step: make the local config directory accessible to the end user via SSH or WebDAV or any other method.

Creating a desktop link to the local configuration directory

A site operator may designate a template manager who is responsible for managing the files in the local configuration directory.

The template manager should have a link on their desktop so that they can easily access the configuration directory using their GUI file manager.

The directory to be shared is the config subdirectory of the site_dir, which usually is the same as the project directory for production sites.

Lino does not create this directory automatically. If you want to use local templates, the server administrator must create that directory and make sure that the Lino web server process has write permission to it.

If the template manager has an Ubuntu desktop with the default files manager, then it is easy (docs):

• Open Files manager

• Select File ‣ Connect to server

• As the Server Address type something like:

  sftp://admin@123.456.78.90/path/to/mysite/config
  

Otherwise consult the documentation of your file manager. If appropriate you might write instructions and contribute them so that we can add them here.

Typical workflow

Here is a typical workflow for a local template optimization.

• Some user wants some change in a printed output.

• The template manager needs to know a database object that serves as example.

• Figure out how to clear the cache and rebuild the printable document without creating useless database content such as new excerpts.

• Find out which file is being used as template. Look at the lino.log if you have no idea where to start.

• Create a backup copy of the template file.

• Make some change, save the template file, rebuild the printable.

• When you are satisfied, remove the backup file.

Implementation details

• lino.core.site.Site.site_dir

• lino.utils.config

The lino_book.projects.cosi1 demo project has a site config dir. This is our demo case of a local config dir. When the cosi1 tests were run on travis (i.e. LINO_CACHE_ROOT is set), Lino forgot to add the cosi1 site’s config dir to its list of config dirs. Another problem was that these “non-local site config dirs” (for which cosi1 on travis is the only example) must come before the plugin config dirs. See config.