The VEfile is a central point of virtstrap. It allows you to define project metadata, requirements, and eventually options for plugins. The VEfile is a YAML file that uses some unique conventions to define the configuration.
To understand the VEfile here’s a short introduction to it’s structure. The following is a valid VEfile:
foo: bar
unladen: swallow
python_is: awesome
In it’s most basic form the VEfile is a simple dictionary or key/value storage. The top most level of keys are considered “sections” and their values can be anything. In the example above the sections are foo, unladen, and python_is. In python this VEfile simply becomes:
{'foo': 'bar', 'unladen': 'swallow', 'python_is': 'awesome' }
Just remember, you can define any key/value pair you wish in the VEfile and virtstrap will happily ignore any section (key) it doesn’t recognize.
For the sections virtstrap does recognize, it expects particular types of values (although it’s still pretty lenient). By design, none of the sections in virtstrap are required. This allows you to use virtstrap without any real specifications. However, once you’re done being lazy and not setting up your project’s repeatable environment, here are the sections you can set.
The requirements section of the VEfile allow you to define your project’s dependencies. Currently there are three forms of dependency declaration.
Package name - This is the simplest declaration. All you do is use the package name so your VEfile would look like this:
requirements:
- some_package # Syntax
- flask # Example
Package name with version specification - This declaration allows you to specify a version or a range of versions. The syntax is similar to defining a just a package name, but it separates the specification string from the package name by a colon. See here:
requirements:
- some_package: "some_spec" # Syntax
- flask: ">=0.7" # Example
- requests: "<=1.0" # Another example
some_spec can be any specification that is allowed by python’s distutils.
Package name with urls - This declaration is the most complex and is meant to be used when you’d like to grab a package from a repository. The syntax may seem verbose for those used to pip’s requirement syntax, but it is meant to be read more easily and hopefully more usable as well. See here:
requirements:
- some_package2: # Syntax for normal urls
- url_to_package_tar_or_zip
- some_package1: # Syntax for VCS
- vcs_type+url_to_repo # vcs_type must be git|bzr|hg|svn
- editable: true # This is optional and makes
# a package editable
- requests: # Example1 (normal url)
- https://github.com/kennethreitz/requests/tarball/v0.10.6
- flask: # Example2 (VCS url)
- git+https://github.com/mitsuhiko/flask
- editable: true
Those familiar with pip will see that the syntax isn’t too far off. The basic syntax for urls is one of two different types: the VCS url or a normal url. A VCS url must be preceded by a type, which is any of the following: git, hg, bzr, or svn. The normal url must point to a tar, zip, or a local directory.
Here’s a full example of a requirements section that installs flask, requests, virtstrap-core, and virtstrap-local.
requirements:
- flask
- requests: ">=0.7"
- virtstrap-core:
- git+https://github.com/ravenac95/virtstrap-core.git
- editable: true
- virtstrap-local:
- https://github.com/ravenac95/virtstrap-local/tarball/v0.3.0
One additional, and powerful, part of VEfile’s structure is it’s ability to use profiles. In virtstrap, a profile is a particular type of environment you’d like to setup. These types of environments could be something like development, testing, staging, production, etc. Virtstrap makes little assumptions about the names you with to use for profiles. The development profile is the single exception. Virtstrap will always use the development profile if you do not specify a different profile. The reason for this is that most of your time with virtstrap will be spent developing code, so it should be simple.
In order to define profiles, VEfile utilizes YAML’s concept of documents. Each document in a YAML file is separated by a ---. The first document in the VEfile is always the default profile. This profile is always used regardless of the currently chosen profile. Every document after that must define a section profile whose value will be used as the profile name. Here’s an example of a VEfile that uses profiles:
################################################
# This section is the default profile
# it is ALWAYS used. So don't put anything here
# that isn't absolutely necessary on every
# environment
################################################
project: tobetterus
requirements:
- sqlalchemy
- flask: ">=0.7"
some_value: foo
--- # This starts a new document (therefore a new profile)
#########################################
# This profile is the development profile
# as defined by the section directly
# below this comment
#########################################
profile: development
# Lists and dictionaries always append the other profile's data
# when profiles are combined
requirements:
- ipython
# If it isn't a list or dictionary it's value
# is overridden entirely.
# So the value of some_value if you use the
# development profile will be 'bar'
some_value: bar
---
profile: production
requirements:
- python-memcached
- mysql-python
The VEfile above defines 3 profiles: default, development, and production.
To use profiles all you have to do is specify the --profiles options on the command line interface. You do this like so:
$ vstrap [command] --profiles=production,development
The line about will use both the production and the development profile. So the list of requirements installed will be sqlalchemy, flask, ipython, python-memcached, and mysql-python. In addition, if you request for the value some_value you will get the value bar, but that’s only really useful if you’re developing a plugin for virtstrap.
These are some suggestions when creating a VEfile.