Installation

The Scrippy installer (the scrippy command) creates the Scrippy directories, writes the Scrippy main configuration file and installs the Scrippy packages with pip. It also uninstalls them.

Table of content

Install the Scrippy installer

In a dedicated virtual environment (recommended)

python3 -m venv ~/.local/share/scrippy/venv
~/.local/share/scrippy/venv/bin/pip install scrippy

The Scrippy packages will be installed in the same virtual environment as the installer:

  • Run the installer with ~/.local/share/scrippy/venv/bin/scrippy
  • Run your Scrippy scripts with ~/.local/share/scrippy/venv/bin/python, or use this interpreter in the shebang of your scripts:
#!/home/luiggi/.local/share/scrippy/venv/bin/python

Note: A virtual environment is mandatory on externally managed Python environments (see PEP 668).

In the user Python environment

export PATH=${HOME}/.local/bin:${PATH}
pip install scrippy

Default installation

scrippy install

The installer displays the configuration to be installed and asks for a confirmation. Use the -y option to answer yes to all questions:

scrippy install -y

Default values:

User root (system wide installation)
Main configuration file ~/.config/scrippy/scrippy.yml /etc/scrippy/scrippy.yml
Scrippy directories ~/.local/share/scrippy/{conf,data,hist,log,reports,templates,tmp} /etc/scrippy/{conf,data,hist,log,reports,templates,tmp}
Packages All Scrippy packages, latest versions same

The installed packages are scrippy-core, scrippy-remote, scrippy-api, scrippy-db, scrippy-mail, scrippy-git, scrippy-template and scrippy-snmp.

Warning: Any preexisting main configuration file is overwritten. Packages are installed with pip install --upgrade (automatic upgrade or downgrade).

At this point you are ready to write your first Scrippy script. You may also want to learn how Scrippy is configured.

Interactive installation

scrippy install -i

Each directory and package version is prompted for, with the default value between brackets. Press [Enter] to keep the default value.

Installation from a configuration file

To allow automated installations, the installer accepts a YAML configuration file:

scrippy install -c /path/to/config.yml -y

Example of a complete configuration file:

env:
  confdir: ~/.local/share/scrippy/conf
  datadir: ~/.local/share/scrippy/data
  histdir: ~/.local/share/scrippy/hist
  logdir: ~/.local/share/scrippy/log
  reportdir: ~/.local/share/scrippy/reports
  templatedir: ~/.local/share/scrippy/templates
  tmpdir: ~/.local/share/scrippy/tmp
packages:
  scrippy-core: latest
  scrippy-remote: latest
  scrippy-api: latest
  scrippy-db: latest
  scrippy-mail: latest
  scrippy-git: latest
  scrippy-template: latest
  scrippy-snmp: latest
  • Both sections are optional.
  • Directories missing from the env section keep their default value.
  • Paths may be relative or use ~: They are converted to absolute paths (this also applies to paths entered interactively).
  • When defined, the packages section replaces the default package list: Only the listed packages are installed.
  • A package value is either latest (or empty) or a version number (i.e: 3.0.0).
  • The resulting configuration, including the package list, is saved in the main configuration file and used by scrippy uninstall.

Note: -i and -c are mutually exclusive. Both can be combined with -y.

System wide installation

When run as root, the installer performs a system wide installation: The main configuration file is written to /etc/scrippy/scrippy.yml and the Scrippy directories are created in /etc/scrippy.

sudo python3 -m venv /opt/scrippy/venv
sudo /opt/scrippy/venv/bin/pip install scrippy
sudo /opt/scrippy/venv/bin/scrippy install

Warning: /etc/scrippy/scrippy.yml is the lowest priority configuration file: Any user can override its values with his own ~/.config/scrippy/scrippy.yml. To enforce a configuration users can not alter, the system administrator must use /usr/local/etc/scrippy/scrippy.yml (see Configuration).

Externally managed Python environments (PEP 668)

On recent operating systems (Debian 12+, Ubuntu 23.04+...), the system Python environment is externally managed and pip refuses to install or uninstall packages into it. In such an environment, scrippy install and scrippy uninstall fail with a message explaining the available solutions:

  • Recommended: Install Scrippy in a dedicated virtual environment (see above) and run your Scrippy scripts with its Python interpreter.
  • Or force the installation into the system Python environment (this may break Python tools provided by the operating system):
pip install --break-system-packages scrippy
scrippy install --break-system-packages
scrippy uninstall --break-system-packages

The --break-system-packages option only has an effect when the Python environment is externally managed.

Uninstall Scrippy

Uninstall and keep the Scrippy directories

scrippy uninstall

The packages listed in the main configuration file are uninstalled, then the main configuration file is deleted. The Scrippy directories and their content (configuration files, logs, history...) are kept.

When run as root, a confirmation is asked before uninstalling the system wide installation.

Uninstall and delete the Scrippy directories

scrippy uninstall --prune

A confirmation is asked before deleting the Scrippy directories (confdir, datadir, histdir, logdir, reportdir, templatedir, tmpdir) and all their content.

Note: scrippy uninstall neither uninstalls the installer itself (pip uninstall scrippy) nor deletes its virtual environment.

Manual installation

The Scrippy packages can be installed without the installer:

pip install scrippy-core scrippy-template

In this case, the Scrippy main configuration file and directories must be created manually (see Configuration).

Command reference

scrippy install [-i | -c CONFIG] [-y] [--break-system-packages]
scrippy uninstall [-p] [--break-system-packages]
Command Option Description
install -i, --interactive Prompt for configuration values
install -c CONFIG, --config CONFIG Configure Scrippy according to the specified YAML file
install -y, --yes Answer yes to all questions
install, uninstall --break-system-packages Allow pip to modify an externally managed Python environment (PEP 668)
uninstall -p, --prune Remove all Scrippy directories and their content