Usage

This page is rather for reference. The full process of installing Lino using getlino is documented in the Lino Book.

The getlino configure command

getlino configure

The getlino configure command configures your machine as a Lino server. This is required before you can run getlino startsite.

If you run this command as root (using sudo), it will turn the machine into a production server or a demo server by also installing system packages and system-wide configuration files. Otherwise it will install Lino into a virtual environment. If you want Lino to install into an existing virtual environment, you should activate it before running getlino configure in order to use it as the default value for --shared-env.

getlino configure asks a lot of questions, one question for each server configuration option. Read the docs below for more explanations. You can answer ENTER to each question if your don’t care.

getlino configure creates or reads and updates a configuration file where it stores your answers. Depending on whether you are root, the configuration file will be either /etc/getlino/getlino.conf or ~/.getlino.conf.

If you specify --batch, every option gets its default value, which you may override by specifying command-line arguments. Use this option only when you know what you want (e.g. in a Dockerfile).

After running getlino configure as root, you may want to run it once more without being root, because only then it will also write a .bash_aliases file in your home directory.

Run-time behaviour options:

--batch

Run in batch mode, i.e. without asking any questions. Assume yes to all questions.

Server configuration options

--shared-env

Full path to your default virtualenv.

Default value is taken from VIRTUAL_ENV environment value. If this is empty, every new site will get its own virgin environment.

--repos-base

Base directory for your shared repositories. This is where getlino should clone repositories of packages to be used in editable mode (“development version”) specified by getlino startsite --dev-repos.

If this is empty and a site requests a development version, this will be stored in a directory named --repos-link below the virtualenv dir.

--clone

Clone all known repositories to your --repos-base and install them into your --shared-env. Used when configuring a contributor environment or a demo server.

--branch

The git branch to use for --clone.

--devtools

Whether to install development tools (used to build docs and run tests).

--log-base

The root directory for Lino’s log files on this server. Each new site will get its entry below that directory.

--backups-base

The root directory for backups on this server. Each new site will get its entry below that directory. Used e.g. by make_snapshot.sh.

--sites-base

The root directory for sites on this server.

New sites will get created below that directory (with another level named by --local-prefix).

This will be added to the PYTHONPATH of every Lino process (namely in manage.py and wsgi.py).

The PYTHONPATH is needed because the settings.py of a site says from lino_local.settings import *, and the manage.py sets DJANGO_SETTINGS_MODULE to 'lino_local.mysite1.settings'.

--local-prefix

Prefix for local server-wide importable packages.

Relative directory or symbolic link to the virtualenv.

Relative directory or symbolic link to repositories.

--server-domain

Fully qualified domain name of this server. Default is ‘localhost’.

Default settings for new sites

--front-end

Which front end (default_ui) to use on new sites.

--languages

Default value for languages of new sites.

--linod

Whether new sites should have a linod.sh script which runs the linod command.

When running as root, this will also add a supervisor configuration file which runs the linod command automatically.

--db-engine

Default value is ‘mysql’ when running as root or ‘sqlite3’ otherwise.

--db-user

A shared database username to use for all sites on this server.

If this is set, you must also set --db-password.

Used during development and testing when you prefer to have a single database user for all databases. For security reasons these options should not be used on a production server.

--db-password

The password for the --db-user.

--db-port

The port to use for connecting to the database server when --db-engine is mysql or postgresql.

Server features

--appy

Whether this server provides LibreOffice service needed by sites that use lino_xl.lib.appypod.

--redis

Whether this server provides redis service needed by sites that use lino.modlib.notify.

--webdav

Whether new sites should have webdav.

--https

Whether this server provides secure http.

This option will cause getlino to install certbot.

When you use this option, you must have your domain name (--server-domain) registered so that it points to the server. If your server has a dynamic IP address, you may use some dynamic DNS service like FreedomBox or dynu.com.

The getlino startsite command

getlino startsite

The script will ask you some questions:

Run-time behaviour options:

--batch

Whether to run in batch mode, i.e. without asking any questions. Assume yes to all questions. Don’t use this on a machine that is already being used.

Settings for the new site

--dev-repos

A space-separated list of repositories for which this site uses the development version (i.e. not the PyPI release).

Usage example:

$ getlino startsite avanti mysite --dev-repos "lino xl"

Not that the sort order is important. The following would not work:

$ getlino startsite avanti mysite --dev-repos "xl lino"
--shared-env

Full path to the shared virtualenv to use for this site. Default value is the value specified during getlino configure --shared-env If this is empty, the new site will get its own virgin environment.

Configuration files

~/.getlino.conf
/etc/getlino/getlino.conf

Multiple database engines on a same server

Note that getlino startsite does not install any db engine because this is done by getlino configure.

When you maintain a Lino server, you don’t want to decide for each new site which database engine to use. You decide this once during getlino configure. In general, apt-get install is called only during getlino configure, never during getlino startsite. If you have a server with some mysql sites and exceptionally want to install a site with postgres, you simply call getlino configure before calling getlino startsite.

You may use multiple database engines on a same server by running configure between startsite invocations.

The startsite template

No longer used: the cookiecutter-startsite project contains a cookiecutter template used by getlino startsite.

Shared virtual environments

You can run multiple sites on a same virtualenv. That virtualenv is then called a shared environment.

If you update a shared virtualenv (by activating it and running pull.sh of some pip command), the change will affect all sites and you must take special care for migrating their data if needed.

In a developer environment and a contributor environment you usually have a single shared env used by all your sites. On a production server you usually have no shared-env at all (each production site has its own env). On a demo server you usually hav several shared envs:

  • /usr/local/lino/sharedenvs/master

  • /usr/local/lino/sharedenvs/stable

You can specify a default shared environment with getlino configure --shared-env getlino startsite --shared-env.

Note that getlino configure --clone) will install all known framework repositories into the default shared env.

getlino startsite does not install any Python packages when a shared env is used.

Concepts

virtualenv

A virtual Python environment.

Developer environment

A set of tools configured on the desktop computer of a Lino developer who wants to develop their own Lino application.

Contributor environment

An extended developer environment suitable for developers who plan to potentially contribute to the Lino framework. A bit more work to install, but more future-proof.

Production server

A dedicated server designed to host one or several production sites.

Demo server

A dedicated server designed to host a series of demo sites.