Welcome | Get started | Dive into Lino | Contribute | Topics | Reference | More

Lino and local files

site_dir and project_dir

Lino sets these two attributes automatically when the Site initializes. You should not override them.

Site.project_dir is the directory containing your settings.py file. Or more precisely the directory containing the source file of your DJANGO_SETTINGS_MODULE. When using a settings package, Site.project_dir points to the settings subdir of what getlino calls the project directory.

Site.site_dir is usually the same as Site.project_dir, except in the following cases:

• When a Site.master_site is given, the slave uses the Site.site_dir of the master.

• When an environment variable LINO_CACHE_ROOT is defined, Lino sets the Site.site_dir to LINO_CACHE_ROOT + Site.project_name. This is used in CI environments where we use settings from a code repository (e.g. book) and don't want to write to the repository itself.

The site_dir is the root for some subdirectories with special meaning:

• a log directory will activate logging to a lino.log file.

• a migrations directory will activate Django migrations.

• a config directory will be added to the config search path. See local config files.

• a media directory is the default value for MEDIA_ROOT

• a static_root directory is the default value for STATIC_ROOT.

Lino sets the MEDIA_ROOT to site_dir / 'media' and the STATIC_ROOT to site_dir / 'static_root'.

The site_dir is also where the default.db file sits when using sqlite.

The site cache

site cache

The directory where Lino automatically generates certain files to be served as media files.

Both the ExtJS front end and the React front end *.js or *.json files in the site cache.

The site cache sits below Site.media_root.

About LINO_CACHE_ROOT

When a Site.master_site is specified, the slave site uses the site cache of the master.

The front end populates the site cache either "late" or "early", where "late" means on each incoming request, and "early" means during explicit collectstatic, makehelp and buildcache command. On a production site we want to call it "early": we explicitly run collectstatic, makehelp and buildcache after an upgrade, and don't want Lino to waste resources by checking whether it's done again and again for every incoming request. But when developing, we don't want Lino to generate all js files (for all user types and all languages) for every little change in the source code.

The lino.core.site.Site.build_js_cache_on_startup attribute is False.

• with force=True by buildcache or when lino.modlib.system.BuildSiteCache is run.

On a production site, Site.build_js_cache_on_startup should be True for best performance, but during development and testing this is not necessary, so default value is False, which means that each file is built upon need (when a first request comes in).

You can also set Site.build_js_cache_on_startup to None, which means that Lino decides automatically during startup: it becomes False if either lino.core.utils.is_devserver() returns True or DEBUG is set.

LINO_BUILD_CACHE_ON_STARTUP

If a variable of that name is set, then Lino will override the code value and set build_js_cache_on_startup to True.

When some exception occurs while populating the site cache Lino usually removes the partly generated file to make sure that it will try to generate it again (and report the same error message) for every subsequent next request. You can set Site.keep_erroneous_cache_files to True if you need to see the partly generated cache file. Don't forget to remove this when you have inspected the file and fixed the reason of the exception, because if this is True and some next exception occurs (which will happen sooner or later), then all subsequent requests will usually end up to the user with a blank screen and (if they notice it), a message TypeError: Lino.main_menu is undefined in their Javascript console.