Configuration Settings¶
The deploy_virtualenv script can use two different configuration files: deploy.conf - Deployment configuration file and requirements.txt these files have different functionality and usage.
deploy.conf - Deployment configuration file¶
The deploy.conf - Deployment configuration file file allows for setting all configuration arguments in a single file. This allows running the script without any other command line arguments.
The same file can be used for deployment and generation of deployment packages in multiple packaging formats. Current supported deployment packaging formats are: rpm and docker containers.
The deploy.conf - Deployment configuration file file is a Python ConfigParse format
configuration file. This file consists of sections which are deliminated by
square brackets. Inside each section are key/value fields. Multi-Line
values can be defined by indenting subsequent lines.
The deploy.conf - Deployment configuration file file has at least 3 possible sections, all of which are optional: global, pip, rpm.
The deploy.conf - Deployment configuration file supports jinja2 template format substitutions for values of environment variables. This allows setting values based on environment variable values. I.E. setting the version based on the BUILD_NUMBER environment variable provided by the CI pipeline for example.
global settings¶
The global settings section of the deploy.conf - Deployment configuration file defines a number of settings. All of which are optional. These settings act as the default values if they are not set in other sections.
basepython¶
The basepython setting is used to define the python interpreter inside the virtualenv. If this setting is not specified it will default to the python interpreter that runs the virtualenv command.
install_manifest¶
The install_manifest setting specifies a comma separated list of manifests to install. If this setting is not set all package manifests (lists of packages) that will be installed.
** NOTE: It is generally not a good idea to mix multiple types of platform package manifests. Such as using both rpm and tar **
install_os_packages¶
The install_os_packages setting causes the script to attempt to install the rpm package resources needed to install Python sdist format packages.
virtualenv_dir¶
The virtualenv_dir setting specifies the directory that will hold the virtualenv that is created. This directory needs to be writable by the user running the script.
version¶
This setting will set the version string the the value specified.
The example below the version string is specified to be based on the BUILD_NUMBER environment variable, defaulting to ‘0.0.0’ if the BUILD_NUMBER is not set. In the example below if the BUILD_NUMBER was set to 15 the version would be ‘0.0.15’:
version = 0.0.{{BUILD_NUMBER|default('0')}}
virtualenv_version_package¶
This setting will lookup the most recent version of the package specified and append that version number to the end of the virtualenv name. This allows versioning the virtualenvs based on a specific package version.
For example, if the most recent version of the public_mirror package is 0.39.0 and the virtualenv was created with the following settings:
name = mirror
virtualenv_version_package = public_mirror
The virtualenv will be named ** mirror_0.39.0 **
virtualenv_user¶
This setting specifies the unix username that should own the created virtualenv.
This setting requires the following:
- This script is being run by a user that has the privileges to change the
ownership to the user specified (generally root) * The user specified has been created on the system.
virtualenv_group¶
This setting specifies the unix group of the created virtualenv.
This setting requires the following:
- This script is being run by a user that has the privileges to change the group to the user specified (generally root)
- The group specified has been created on the system.
pip package manifest¶
This configuration section allows defining settings related to the installation of python packages that are installed using the pip tool. As part of a pip package manifest.
This section is used to define the python packages to install.
deps¶
The deps section contains a list of python packages to install. The format for the deps is the same as the format of a pip requirements file.
rpm package manifest¶
The [rpm] configuration section allows defining package manifests (list of packages) of rpm packages installed using the yum tool.
These is section defines a package manifest of rpm packages to install prior to installing the python packages.
Note:
rpm package installations are not atomic and once installed some package dependencies can block uninstall or upgrade of certain packages. As a result a rpm install failure can leave the system in a different package state than when the script run started.
deps¶
This section is a list of rpm packages to install.
docker_container packaging (creation)¶
The [docker_container] section contains the settings used to create a docker container containing the python application in a virtualenv. This section allows for adding settings used to create the docker container.
The docker plugin will generate basic sane container based on the defaults and values in the global section of the configuration.
This section can be used to set docker specific settings such as commands to use for healthchecks of the created docker container.
add¶
base_image¶
default=ubuntu:17.10
container_name¶
copy¶
deb_deps¶
A manifest of debian packages to install into the container prior to creating the python virtualenv.
entrypoint¶
env¶
expose¶
files¶
healthcheck¶
This is the healthcheck script to run in the container.
label¶
A list of labels to be applied to the container.
rpm_deps¶
A manifest of rpm packages to install into the container prior to creating the python virtualenv.
run_before¶
A list of shell commands to run before creating the python virtualenv inside the container.
run_after¶
A list of shell commands to run after creating the python virtualenv inside the container.
setenv¶
Environment variables to set when creating the container.
stopsignal¶
user¶
volume¶
A list of volume mappings to use with the container.
rpm packaging¶
The [rpm_package] section defines settings related to the creation of rpm packages. The settings in this section will override the default values from the global settings for rpm package generation only.
deps¶
This is a manifest (list of packages) to be listed as dependencies of the created rpm package.
Note:
This should include the packages that contain the python interpreter
and virtualenv commands to use to deploy the virtualenv when the created package
is installed.
Example deploy.conf¶
; Copyright (c) 2016, Yahoo Inc.
; Copyrights licensed under the BSD License
; See the accompanying LICENSE.txt file for terms.
[global]
;######################################################################
; Global settings
;######################################################################
; The name of the virtualenv to create
name = public_mirror
; The python interpreter to use for the virtualenv
; this will default to the python interpreter running the virtualenv
; command if it is not specified.
basepython = python3
; Base directory to create virtualenv in
virtualenv_dir = /var/tmp/virtualenv
;######################################################################
; Version settings
;######################################################################
; There are several ways to specify a version for the virtualenv.
;
; The first way is to specify the version directly. This file allows
; using environment variables using :ref:`jinja2` template syntax.
; In the example below the last digit of the version will be either the
; value of the BUILD_NUMBER environment variable or 0 if it is not set.
; This method makes it easy to generate a unique version number in a CI
; pipeline that sets the BUILD_NUMBER environment variable.
version = 0.0.{{BUILD_NUMBER|default('0')}}
; The second method to specify a version is to use the latest version
; of a python package in the Python package repository to determine the
; version component of the virtualenv.
; If no versions is found or specified the virtualenv will not have a
; version component in the name.
; virtualenv_version_package = public_mirror
; The user and group that should own the virtualenv. If not specified
; the current user will be used.
virtualenv_user =
virtualenv_group =
; When package manifest to install into the virtualenv
; If none are specified all manifest will be deployed.
; Note:
; It is generally a bad idea to use tar and rpm manifest together.
install_manifest = pip, rpm
; If the user has root privileges setting this to True will
; attempt to install the python devel package resources using
; rpm. This is here for backwards compatibility, it is
; recommended to specify the devel packages in the rpm
; package manifest instead.
install_os_packages = False
; The RPMs generated by invirtualenv includes all the wheels needed to
; generate the virtualenv. The wheels are stored at
; /usr/share/<name>_<version>/wheels dir. If use_local_wheels is set to True,
; invirtualenv will try to use the wheels stored locally when it generates the
; virtualenv in %post install section of the RPM installation. Set it to True
; if you want to avoid fetching packages from pypi during virtualenv creation.
use_local_wheels = False
; When invirutalenv creates the application virtualenv the console_scripts are
; deployed to <virtualenv_dir>/bin directory. If you want invirtualenv to
; automatically link these binary/cmdline scripts to /usr/bin set
; link_bin_files to True
link_bin_files = False
[pip]
;######################################################################
; PIP package settings
;######################################################################
; deps contains a list of python packages to install.
; It is recommended this be a concrete list such as what is returned
; using the 'pip freeze' command.
; Each line must be indented.
deps:
public_mirror==0.0.39
[rpm]
;######################################################################
; rpm package install settings
;######################################################################
; deps contains a list of rpm packages to install.
; These dependencies are applied as a single rpm operation with
; the packages ordered as specified.
;
; Keep in mind rpm that rpm operations are not atomic so using
; a large number of packages with specific versions numbers can
; cause dependency conflicts with already installeed packages and
; leave the system in a state that cannot easily be reverted.
; NOTE: This section is different from rpm_package section. If you are planning
; to create RPMs DO NOT use this section, use rpm_package section instead and
; list your rpm deps there. If you list deps here and try to generate RPMs
; the generated RPM will try to yum install dependencies in %post install
; section and result in a dead lock.
deps:
[rpm_package]
;######################################################################
; rpm package creation settings
;######################################################################
# Deps listed here are added as rpm package dependencies of the created
# package. This should at minimum include the python interpreter used
# to run the script contained in the package.
deps:
python3
# These settings allow specifying these values in the spec file used to
# generate the rpm package.
; group=
; license=
; packager=
[docker_container]
;######################################################################
; docker container creation settings
;######################################################################
base_image=ubuntu:17.10
container_name=invirtualenvapp/publicmirror
; entrypoint=/bin/bash
; expose=
files:
setenv:
DEBIAN_FRONTEND=noninteractive
requirements.txt¶
The requirements.txt file is a pip format requirements.txt file and only specifies the python packages to be installed in the virtualenv.