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¶
- 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
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¶
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
.