Example¶

Let’s make config for hello-world flask application. To start you need to put following in vagga.yaml:

containers:
  flask: ❶
    setup:
    - !Ubuntu trusty ❷
    - !UbuntuUniverse ❸
    - !Install [python3-flask] ❹
commands:
  py3: !Command ❺
    container: flask ❻
    run: python3 ❼

• ❶ – create a container “flask”
• ❷ – install base image of ubuntu
• ❸ – enable the universe repository in ubuntu
• ❹ – install flask from package (from ubuntu universe)
• ❺ – create a simple command “py3”
• ❻ – run command in container “flask”
• ❼ – the command-line is “python3”

To run command just run vagga command_name:

$ vagga py3
[ .. snipped container build log .. ]
Python 3.4.0 (default, Apr 11 2014, 13:05:11)
[GCC 4.8.2] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import flask
>>>

This is just a lazy example. Once your project starts to mature you want to use some specific version of flask and some other dependencies:

containers:
  flask:
    setup:
    - !Ubuntu trusty
    - !Py3Install
      - werkzeug==0.9.4
      - MarkupSafe==0.23
      - itsdangerous==0.22
      - jinja2==2.7.2
      - Flask==0.10.1
      - sqlalchemy==0.9.8

And if another developer does git pull and gets this config, running vagga py3 next time will rebuild container and run command in the new environment without any additional effort:

$ vagga py3
[ .. snipped container build log .. ]
Python 3.4.0 (default, Apr 11 2014, 13:05:11)
[GCC 4.8.2] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import flask, sqlalchemy
>>>

You probably want to move python dependencies into requirements.txt:

containers:
  flask:
    setup:
    - !Ubuntu trusty
    - !Py3Requirements "requirements.txt"

And vagga is smart enough to rebuild if requirements.txt change.

In case you’ve just cloned the project you might want to run bare vagga to see which commands are available. For example, here are some commands available in vagga project itself:

$ vagga
Available commands:
    make                Build vagga
    build-docs          Build vagga documentation
    test                Run self tests

(the descriptions on the right are added using description key in command)

More Reading¶

• Managing Dependencies with Vagga shows basic concepts of using vagga and what problems it solves.
• Evaluating Mesos discuss how to run network tolerance tests.

Command-Centric Workflow¶

When you start working on project, you don’t need to know anything about virtual machines, dependencies, paths whatever. You just need to know what you can do with it.

Consider we have an imaginary web application. Let’s see what we can do:

> git clone git@git.git:somewebapp.git somewebapp
> cd somewebapp
> vagga
Available commands:
    build-js    build javascript files needed to run application
    serve       serve a program on a localhost

Ok, now we know that we probably expected to build javascipt files and that we can run a server. We now just do:

> vagga build-js
# container created, dependencies populated, javascripts are built
> vagga serve
Now you can go to http://localhost:8000 to see site in action

Compare that to vagrant:

> vagrant up
# some machine(s) created
> vagrant ssh
# now you are in new shell. What to do?
> make
# ok probably something is built (if project uses make), what now?
> less README
# long reading follows

Or compare that to docker:

> docker pull someuser/somewebapp
> docker run --rm --it someuser/somewebapp
# if you are lucky something is run, but how to build it?
# let's see the README

Lazy Container Creation¶

There are few interesting cases where lazy containers help.

containers:

  build:
    setup:
    - !Ubuntu trusty
    - !Install [make, nodejs, uglifyjs]

  serve:
    setup:
    - !Ubuntu trusty
    - !UbuntuUniverse
    - !Install [python-django]

commands:

  build-js: !Command
    container: build
    run: "make build-js"

  serve: !Command
    container: serve
    run: "python manage.py runserver"

containers:

  testing:
    setup:
    - !Ubuntu trusty
    - !UbuntuUniverse
    - !Install [make, nodejs, uglifyjs, python-django, nosetests]

commands:

  test:
    container: testing
    run: [nosetests]

> vagrant up
# two containers are up at this point
> vagrant ssh build -- make
# built, now we don't want to waste memory for build virtual machine
> vagrant halt build
> vagrant ssh serve -- python manage.py runserver

> vagga
Available commands:
    md2html         convert markdown to html without installation
    tests           run tests
    example-web     run live demo (flask app)
    example-plugin  example of plugin for markdown parser
> vagga example-web
Now go to http://localhost:8000 to see the demo

> ls -R examples
examples/web:
Vagrantfile README flask-app.py

examples/plugin:
Vagrantfile README main.py plugin.py

> cd examples/web
> vagrant up && vagrant ssh -- python main.py --help
> vagrant ssh -- python main.py --port 8000
# ok got it, let's stop it
> vagrant halt && vagrant destroy

Container Versioning and Rebuilding¶

What if the project dependencies are changed by upstream? No problem:

> git pull
> vagga serve
# vagga notes that dependencies changed, and rebuilds container
> git checkout stable
# moving to stable branch, to fix some critical bug
> vagga serve
# vagga uses old container that is probably still around

Vagga hashes dependencies, and if the hash changed creates new container. Old ones are kept around for a while, just in case you revert to some older commit or switch to another branch.

How you do this with Vagrant:

> git pull
> vagrant ssh -- python manage.py runserver
ImportError
> vagrant reload
> vagrant ssh -- python manage.py runserver
ImportError
> vagrant reload --provision
#  If you are lucky and your provision script is good, dependency installed
> vagrant ssh -- python manage.py runserver
# Ok it works
> git checkout stable
> vagrant ssh -- python manage.py runserver
# Wow, we still running dependencies from "master", since we added
# a dependency it works for now, but may crash when deploying
> vagrant restart --provision
# We used ``pip install requirements.txt`` in provision
# and it doesn't delete dependencies
> vagrant halt
> vagrant destroy
> vagrant up
# let's wait ... it sooo long.
> vagrant ssh -- python manage.py runserver
# now we are safe
> git checkout master
# Oh no, need to rebuild container again?!?!

Using Docker? Let’s see:

> git pull
> docker run --rm -it me/somewebapp python manage.py runserver
ImportError
> docker tag me/somewebapp:latest me/somewebapp:old
> docker build -t me/somewebapp .
> docker run --rm -it me/somewebapp python manage.py runserver
# Oh, that was simple
> git checkout stable
> docker run --rm -it me/somewebapp python manage.py runserver
# Oh, crap, I forgot to downgrade container
# We were smart to tag old one, so don't need to rebuild:
> docker run --rm -it me/somewebapp:old python manage.py runserver
# Let's also rebuild dependencies
> ./build.sh
Running: docker run --rm me/somewebapp_build python manage.py runserver
# Oh crap, we have hard-coded container name in build script?!?!

Well, docker is kinda easier because we can have multiple containers around, but still hard to get right.

Running Multiple Processes¶

Many projects require multiple processes around. E.g. when running web application on development machine there are at least two components: database and app itself. Usually developers run database as a system process and a process in a shell.

When running in production one usually need also a cache and a webserver. And developers are very lazy to run those components on development system, just because it’s complex to manage. E.g. if you have a startup script like this:

#!/bin/sh
redis-server ./config/redis.conf &
python manage.py runserver

You are going to loose redis-server running in background when python process dead or interrupted. Running them in different tabs of your terminal works while there are two or three services. But today more and more projects adopt service-oriented architecture. Which means there are many services in your project (e.g. in our real-life example we had 11 services written by ourselves and we also run two mysql and two redis nodes to emulate clustering).

This means either production setup and development are too diverse, or we need better tools to manage processes.

How vagrant helps? Almost in no way. You can run some services as a system services inside a vagrant. And you can also have multiple virtual machines with services, but this doesn’t solve core problem.

How docker helps? It only makes situation worse, because now you need to follow logs of many containers, and remember to docker stop and docker rm the processes on every occassion.

Vagga’s way:

commands:
  run_full_app: !Supervise
    children:
      web: !Command
        container: python
        run: "python manage.py runserver"
      redis: !Command
        container: redis
        run: "redis-server ./config/redis.conf"
      celery: !Command
        container: python
        run: "python manage.py celery worker"

No just run:

> vagga run_full_app
# two python processes and a redis started here

It not only allows you to start processes in multiple containers, it also does meaningful monitoring of them. The stop-on-failure mode means if any process failed to start or terminated, terminate all processes. It’s opposite to the usual meaning of supervising, but it’s super-useful development tool.

Let’s see how it’s helpful. In example above celery may crash (for example because of misconfiguration, or OOM, or whatever). Usually when running many services you have many-many messages on startup, so you may miss it. Or it may crash later. So you click on some task in web app, and wait when the task is done. After some time, you think that it may be too long, and start looking in logs here and there. And after some tinkering around you see that celery is just down. Now, you lost so much time just waiting. Wouldn’t it be nice if everything is just crashed and you notice it immediately? Yes it’s what stop-on-failure does.

Then if you want to stop it, you just press Ctrl+C and wait for it to shut down. If it hangs for some reason (may be you created a bug), you repeat or press Ctrl+/ (which is SIGQUIT), or just do kill -9 from another shell. In any case vagga will not exit until all processes are shut down and no hanging processes are left ever (Yes, even with kill -9).

User Namespaces¶

As you might noticed that adding user to docker group (if your docker socket is accessed by docker group), is just like giving him a paswordless sudo. This is because root user in docker container is same root that one on host. Also user that can start docker container can mount arbitrary folder in host filesystem into the container (So he can just mount /etc and change /etc/passwd).

Vagga is different as it uses a user namespaces and don’t need any programs running as root or setuid programs or sudo (except systems’ builtin newuidmap/newgidmap if you want more that one user inside a container, but newuidmap setuid binary is very small functionally and safe).

No Central Daemon¶

Vagga keeps your containers in .vagga dir inside your project. And runs them just like any other command from your shell. I.e. command run with vagga is child of your shell, and if that process is finished or killed, its just done. No need to delete container in some central daemon like docker has (i.e. docker doesn’t always remove containers even when using --rm).

Docker also shares some daemon configuration between different containers even run by different users. There is no such sharing in vagga.

Also not having central daemon shared between users allows us to have a user-defined settings file in $HOME/.config/vagga/.

Children Processes¶

Running processes as children of current shell has following advantages:

• You can monitor process and restart when dead (needs polling in docker), in fact there a command type supervise that does it for you)
• File descriptors may be passed to process
• Processes/containers may be socket-activated (e.g. using systemd --user)
• Stdout and stderr streams are just inherited file descriptors, and they are separate (docker mixes the two; it also does expensive copying of the stream from the container to the client using HTTP api)

Filesystems¶

All files in vagga is kept in .vagga/container_name/ so you can inspect all persistent filesystems easily, without finding cryptic names in some system location, and without sudo

Filesystem Permissions¶

Docker by default runs programs in container as root. And it’s also a root on the host system. So usually in your development project you get files with root owner. While it’s possible to specify your uid as a user for running a process in container, it’s not possible to do it it portable. I.e. your uid in docker container should have passwd entry. And somebody else may have another uid so must have a different entry in /etc/passwd. Also if some process realy needs to be root inside the container (e.g. it must spawn processes by different users) you just can’t fix it.

With help of user namespaces Vagga runs programs as a root inside a container, but it looks like your user outside. So all your files in project dir are still owned by you.

Security¶

While docker has enterprise support, including security updates. Vagga doesn’t have such (yet).

However, Vagga runs nothing with root privileges. So even running root process in guest system it’s at least as secure as running any unprivileged program in host sytem. It also uses chroot and linux namespaces for more isolation. Compare it to docker which doesn’t consider running as root inside a container secure.

You can apply selinux or apparmor rules for both.

Filesystem Redundancy¶

Vagga creates each container in .vagga as a separate directory. So theoretically it uses more space than layered containers in docker. But if you put that dir on btrfs filesystem you can use bedup to achieve much better redundancy than what docker provides.

Containers¶

While vagrant emulates full virtual machine, vagga uses linux containers. So you don’t need hardware virtualization and a supervisor. So usually vagga is more light on resources.

Also comparing to vagrant where you run project inside a virtual machine, vagga is suited to run commands inside a container, not a full virtual machine with SSH. In fact many vagga virtual machines don’t have a shell and/or a package manager inside.

Commands¶

While vagrant is concentrated around vagrant up and VM boot process. Light containers allows you to test your project in multiple environments in fraction of second without waiting for boot or having many huge processes hanging around.

So instead of having vagrant up and vagrant ssh we have user-defined commands like vagga build or vagga run or vagga build-a-release-tarball.

Linux-only¶

While vagrant works everywhere, vagga only works on linux systems with recent kernel and userspace utulities.

If you use a mac, just run vagga inside a vagrant container, just like you used to run docker :)

Half-isolation¶

Being only a container allows vagga to share memory with host system, which is usually a good thing.

Memory and CPU usage limits can be enforced on vagga programs using cgroups, just like on any other process in linux. Vagga runs only on quite recent linux kernels, which has much more limit capabilities than previous ones.

Also while vagrant allows to forward selected network ports, vagga by default shares network interface with the host system. Isolating and forwarding ports will be implemented soon.

Common Parameters¶

These parameters work for both kinds of commands:

description¶

Description that is printed in when vagga is run without arguments

banner¶

The message that is printed before running process(es). Useful for documenting command behavior.

banner-delay¶

The seconds to sleep before printing banner. For example if commands run a web service, banner may provide a URL for accessing the service. The delay is used so that banner is printed after service startup messages not before. Note that currently vagga sleeps this amount of seconds even if service is failed immediately.

epilog¶

The message printed after command is run. It’s printed only if command returned zero exit status. Useful to print further instructions, e.g. to display names of build artifacts produced by command.

Parameters of !Command¶

container¶

The container to run command in

run¶

The command to run. It’s either a string (which is passed to /bin/sh -c) or a list of command and arguments.

work-dir¶

The working directory to run in. Path relative to project root. By default command is run in the same directory where vagga started (sans the it’s mounted as /work so the output of pwd would seem to be different)

accepts-arguments¶

Denotes whether command accepts additional arguments. Defaults to false for shell commands, and true for regular commands.

environ¶

The mapping of environment to pass to command. This overrides environment specified in container on value by value basis.

pid1mode¶

This denotes what is run as pid 1 in container. It may be wait, wait-all-children or exec. The default wait is ok for most regular processes. See What’s Special With Pid 1? for more info.

write-mode¶

The parameter specifies how container’s base file system is used. By default container is immutable (corresponds to the read-only value of the parameter), which means you can only write to the /tmp or to the /work (which is your project directory).

Another option is transient-hard-link-copy, which means that whenever command is run, create a copy of the container, consisting of hard-links to the original files, and remove the container after running command. Should be used with care as hard-linking doesn’t prevent original files to be modified. Still very useful to try package installation in the system. Use vagga _build --force container_name to fix base container if that was modified.

user-id¶

The user id to run command as. If the external-user-id is omitted this has same effect like using sudo -u inside container (except it’s user id instead of user name)

external-user-id¶

(experimental) This option allows to map the user-id as seen by command itself to some other user id inside container namespace (the namespace which is used to build container). To make things a little less confusing, the following two configuration lines:

user-id: 1
external-user-id: 0

Will make your command run as user id 1 visible inside the container (which is “daemon” or “bin” depending on distribution). But outside the container it will be visible as your user (i.e. user running vagga). Which effectively means you can create/modify files in project directory without permission errors, but tar and other commands which have different behaviour when running as root would think they are not root (but has user id 1)

Parameters of !Supervise¶

mode¶

The set of processes to supervise and mode. See Supervision for more info

children¶

A mapping of name to child definition of children to run. All children are started simultaneously.

kill-unresponsive-after¶

(default 2 seconds) If some process have exited (in stop-on-failure mode) vagga will send TERM signal to all other processes. If they don’t finish in the specified number of seconds, vagga will kill them with KILL signal (so they finish without being able to intercept singal unconditionally). If you don’t like this behavior set the parameter to some large value.

Generic Installers¶

To run arbitrary shell command use !Sh:

setup:
- !Ubuntu trusty
- !Sh "apt-get install -y python"

If you have more than one-liner you may use YAMLy literal syntax for it:

setup:
- !Ubuntu trusty
- !Sh |
   wget somepackage.tar.gz
   tar -xzf somepackage.tar.gz
   cd somepackage
   make && make install

To run !Sh you need /bin/sh. If you don’t have shell in container you may use !Cmd that runs command directly:

setup:
# ...
- !Cmd [/usr/bin/python, '-c', 'print "hello from build"']

To install a package of any (supported) linux distribution just use !Install command:

containers:

  ubuntu:
    setup:
    - !Ubuntu trusty
    - !Install [python]

  ubuntu-precise:
    setup:
    - !Ubuntu precise
    - !Install [python]

  alpine:
    setup:
    - !Alpine v3.1
    - !Install [python]

Occasionally you need some additional packages to use for container building, but not on final machine. Use !BuildDeps for them:

setup:
- !Ubuntu trusty
- !Install [python]
- !BuildDeps [python-dev, gcc]
- !Sh "make && make install"

The python-dev and gcc packages from above will be removed after building whole container.

To add some environment arguments to subsequent build commands use !Env:

setup:
# ...
- !Env
  VAR1: value1
  VAR2: value2
- !Sh "echo $VAR1 / $VAR2"

Sometimes you want to rebuild container when some file changes. For example if you have used the file in the build. There is a !Depends command which does nothing per se, but add a dependency. The path must be relative to your project directory (the dir where vagga.yaml is). For example:

setup:
# ...
- !Depends requirements.txt
- !Sh "pip install -r requirements.txt"

To download and unpack tar archive use !Tar command:

setup:
- !Tar
  url: http://something.example.com/some-project-1.0.tar.gz
  sha256: acd1234...
  path: /
  subdir: some-project-1.0

Only url field is mandatory. The path is target path to unpack into, and subdir is a dir inside tar file. By default path is root of new filesystem. The subdir is a dir inside the tar file, if omitted whole tar archive will be unpacked. You can use !Tar command to download and unpack the root filesystem from scratch.

There is a shortcut to download tar file and build and install from there, which is !TarInstall:

setup:
- !TarInstall
  url: http://static.rust-lang.org/dist/rust-0.12.0-x86_64-unknown-linux-gnu.tar.gz
  sha256: abcd1234...
  subdir: rust-0.12.0-x86_64-unknown-linux-gnu
  script: ./install.sh --prefix=/usr

Only the url is mandatory here too. The script is by default ./configure --prefix=/usr; make; make install. It’s run in subdir of unpacked archive. If subdir is omitted it’s run in the only subdirectory of the archive. If archive contains more than one directory and subdir is empty, it’s an error, however you may use . as subdir.

To remove some data from the image after building use !Remove command:

setup:
# ...
- !Remove /var/cache/something

To clean directory but ensure that directory exists use !EmptyDir command:

setup:
# ...
- !EmptyDir /tmp

To ensure that directory exists use !EnsureDir command. It’s very often used for future mount points:

setup:
# ...
- !EnsureDir /sys
- !EnsureDir /dev
- !EnsureDir /proc

Sometimes you want to keep some cache between builds of container or similar containers. Use !CacheDirs for that:

setup
# ...
- !CacheDirs { "/var/cache/apt": "apt-cache" }

Mutliple directories may be specified at once.

Sometimes you just want to write a file in target system:

setup:
# ...
- !Text
  /etc/locale.conf: |
     LANG=en_US.UTF-8
     LC_TIME=uk_UA.UTF-8

Ubuntu¶

To install base ubuntu system use:

setup:
- !Ubuntu trusty

Potentially any ubuntu long term support release instead of trusty should work. To install a non LTS release, use:

setup:
- !UbuntuRelease { version: 14.10 }

To install any ubuntu package use generic !Install command:

setup:
- !Ubuntu trusty
- !Install python

Many interesting ubuntu packages are in the “universe” repository, you may add it by series of !UbuntuRepo commands (see below), but there is shortcut !UbuntuUniverse:

setup:
- !Ubuntu trusty
- !UbuntuUniverse
- !Install [checkinstall]

The !UbuntuRepo command adds additional repository. For example, to add marathon repository you may write:

setup:
- !Ubuntu trusty
- !UbuntuRepo
  url: http://repos.mesosphere.io/ubuntu
  suite: trusty
  components: [main]
- !Install [mesos, marathon]

This effectively adds repository and installs mesos and marathon packages.

Alpine¶

To install base alpine system use:

setup:
- !Alpine v3.1

Potentially any alpine version instead of v3.1 should work.

To install any alpine package use generic !Install command:

setup:
- !Alpine v3.1
- !Install [python]

Npm Installer¶

You can build somewhat default nodejs environment using !NpmInstall command. For example:

setup:
- !Ubuntu trusty
- !NpmInstall [react-tools]

All node packages are installed as --global which should be expected. If no distribution is specified before the !NpmInstall command, the implicit !Alpine v3.1 (in fact the latest version) will be executed.

setup:
- !NpmInstall [react-tools]

So above should just work as expected if you don’t need any special needs. E.g. it’s usually perfectly ok if you only use node to build static scripts.

The following npm features are supported:

• Specify package@version to install specific version (recommended)
• Use git:// url for the package. In this case git will be installed for the duration of the build automatically
• Bare package_name (should be used only for one-off environments)

Other forms may work, but are unsupported for now.

Python Installer¶

There are two separate commands for installing packages for python2 and python3. Here is a brief example:

setup:
- !Ubuntu trusty
- !Py2Install [sphinx]

Currently packages are installed by system pip. We consider this an implementation detail and will use latest pip in future. The python-dev headers are installed for the time of the build too. Both python-dev and pip are removed when installation is finished.

The following pip package specification formats are supported:

• The package_name==version to install specific version (recommended)
• Bare package_name (should be used only for one-off environments)
• The git+ and hg+ links (the git and mercurial are installed as build dependency automatically), since vagga 0.4 git+https and hg+https are supported too (required installing ca-ceritificates manually before)

All other forms may work but not supported. Specifying command-line arguments instead of package names is not supported. To configure pip use !PipConfig directive. In the example there are full list of parameters:

setup:
- !Ubuntu trusty
- !PipConfig
  index-urls: ["http://internal.pypi.local"]
  find-links: ["http://internal.additional-packages.local"]
  dependencies: true
- !Py2Install [sphinx]

They should be self-descriptive. Note unlike in pip command line we use single list both for primary and “extra” indexes. See pip documentation for more info about options

Better way to specify python dependencies is to use “requirements.txt”:

setup:
- !Ubuntu trusty
- !Py3Requirements "requirements.txt"

This works the same as Py3Install including auto-installing of version control packages and changes tracking. I.e. It will rebuild container when “requirements.txt” change. So ideally in python projects you may use two lines above and that’s it.

The Py2Requirements command exists too.

Dependent Containers¶

Sometimes you want to build on top of another container. For example, container for running tests might be based on production container, but it might add some test utils. Use !Container command for that:

container:
  base:
    setup:
    - !Ubuntu trusty
    - !Py3Install [django]
  test:
    setup:
    - !Container base
    - !Py3Install [nosetests]

It’s also sometimes useful to freeze some part of container and test next build steps on top of of it. For example:

container:
  temporary:
    setup:
    - !Ubuntu trusty
    - !TarInstall
      url: http://download.zeromq.org/zeromq-4.1.0-rc1.tar.gz
  web:
    setup:
    - !Container temporary
    - !Py3Install [pyzmq]

In this case when you try multiple different versions of pyzmq, the zeromq itself will not be rebuilt. When you’re done, you can append build steps and remove the temporary container.

Sometimes you need to generate (part of) vagga.yaml itself. For some things you may just use shell scripting. For example:

container:
  setup:
  - !Ubuntu trusty
  - !Env { VERSION: 0.1.0 }
  - !Sh "apt-get install somepackage==$VERSION"

In more complex scenarios you may want to generate real vagga.yaml. You may use that with ancillary container and !SubConfig command. For example, here is how we use a docker2vagga script to transform Dockerfile to vagga config:

docker-parser: ❶
  setup:
  - !Alpine v3.1
  - !Install [python]
  - !Depends Dockerfile ❷
  - !Depends docker2vagga.py ❷
  - !Sh 'python ./docker2vagga.py > /docker.yaml' ❸

somecontainer:
  setup:
  - !SubConfig
    source: !Container docker-parser ❶
    path: docker.yaml ❹
    container: docker-smart ❺

Few comments:

• ❶ – container used for build, it’s rebuilt automatically as a dependency for “somecontainer”
• ❷ – normal dependency rules apply, so you must add external files that are used to generate the container and vagga file in it
• ❸ – put generated vagga file inside a container
• ❹ – the “path” is relative to the source if the latter is set
• ❺ – name of the container used inside a “docker.yaml”

The !SubConfig command may be used to include some commands from another file without building container. Just omit generator command:

subdir:
  setup:
  - !SubConfig
    path: subdir/vagga.yaml
    container: containername

The YAML file used may be a partial container, i.e. it may contain just few commands, installing needed packages. The other things (including the name of the base distribution) can be set by original container:

# vagga.yaml
containers:
  ubuntu:
    setup:
    - !Ubuntu trusty
    - !SubConfig
      path: packages.yaml
      container: packages
  alpine:
    setup:
    - !Alpine v3.1
    - !SubConfig
      path: packages.yaml
      container: packages

# packages.yaml
containers:
  packages:
    setup:
    - !Install [redis, bash, make]

Upgrading 0.3.x -> 0.4.x¶

The release is focused on migrating from small amount of C code to “unshare” crate and many usability fixes, including ones which have small changes in semantics of configuration. The most important changes:

• The !Sh command now runs shell with -ex this allows better error reporting (but may change semantics of script for some obscure cases)
• There is now kill-unresponsive-after setting for !Supervise commands with default value of 2. This means that processes will shut down unconditionally two seconds after Ctrl+C.

See Release Notes and Github for all changes.

Upgrading 0.2.x -> 0.3.x¶

This upgrade should be seamless. The release is focused on migrating code from pre-1.0 Rust to... well... rust 1.2.0.

Other aspect of code migration is that it uses musl libc. So building vagga from sources is more complex now. (However it’s as easy as previous version if you build with vagga itself, except you need to wait until rust builds for the first time).

Upgrading 0.1.x -> 0.2.x¶

There are basically two things changed:

1. The way how containers (images) are built
2. Differentiation of commands

rust:
  builder: ubuntu
  parameters:
    repos: universe
    packages: make checkinstall wget git uidmap
  provision: |
    wget https://static.rust-lang.org/dist/rust-0.12.0-x86_64-unknown-linux-gnu.tar.gz
    tar -xf rust-0.12.0-x86_64-unknown-linux-gnu.tar.gz
    cd rust-0.12.0-x86_64-unknown-linux-gnu
    ./install.sh --prefix=/usr

rust:
  setup:
  - !Ubuntu trusty
  - !UbuntuUniverse ~
  - !TarInstall
    url: http://static.rust-lang.org/dist/rust-1.0.0-alpha-x86_64-unknown-linux-gnu.tar.gz
    script: "./install.sh --prefix=/usr"
  - !Install [make, checkinstall, git, uidmap]
  - !Sh "echo Done"

Supervision Modes¶

There are three basic modes of operation:

• stop-on-failure – stops all processes as soon as any single one is dead (default)
• wait-all – wait for all processes to finish
• restart – always restart dead processes

In any mode of operation supervisor itself never exits until all the children are dead. Even when you kill supervisor with kill -9 or kill -KILL all children will be killed with -KILL signal too. I.e. with the help of namespaces and good old PR_SET_PDEATHSIG we ensure that no process left when supervisor killed, no one is reparented to init, all traces of running containers are cleared. Seriously. It’s very often a problem with many other ways to run things on development machine.

commands:
  run_full_app: !Supervise
    mode: stop-on-failure
    children:
      web: !Command
        container: python
        run: "python manage.py runserver"
      celery: !Command
        container: python
        run: "python manage.py celery worker"

Tips¶

# run everything, except the web process we are debugging
$ vagga run_full_app --exclude web
# then in another tab
$ vagga run_full_app --only web

Builtin Commands¶

All commands have --help, so we don’t duplicate all command-line flags here

• vagga _run CONTAINER CMD ARG... – run arbitrary command in container defined in vagga.yaml
• vagga _build CONTAINER – builds container without running a command
• vagga _clean – removes images and temporary files created by vagga. To fully remove .vagga directory you can run vagga _clean --everything. For other operations see vagga _clean --help
• vagga _list – list of commands (including builtin ones when using --builtin flag)
• vagga _version_hash – prints version hash for the container, might be used in some automation scripts

Normal Commands¶

If command declared as !Command you get a command with the following usage:

Usage:
    vagga [OPTIONS] some_command [ARGS ...]

Runs a command in container, optionally builds container if that does not
exists or outdated. Run `vagga` without arguments to see the list of
commands.

positional arguments:
  some_command          Your defined command
  args                  Arguments for the command

optional arguments:
  -h,--help             show this help message and exit
  -E,--env,--environ NAME=VALUE
                        Set environment variable for running command
  -e,--use-env VAR      Propagate variable VAR into command environment
  --no-build            Do not build container even if it is out of date.
                        Return error code 29 if it's out of date.
  --no-version-check    Do not run versioning code, just pick whatever
                        container version with the name was run last (or
                        actually whatever is symlinked under
                        `.vagga/container_name`). Implies `--no-build`

All the ARGS that follow command are passed to the command even if they start with dash -.

Supervise Commands¶

If command declared as !Supervise you get a command with the following usage:

Usage:
    vagga run [OPTIONS]

Run full server stack

optional arguments:
  -h,--help             show this help message and exit
  --only PROCESS_NAME [...]
                        Only run specified processes
  --exclude PROCESS_NAME [...]
                        Don't run specified processes
  --no-build            Do not build container even if it is out of date.
                        Return error code 29 if it's out of date.
  --no-version-check    Do not run versioning code, just pick whatever
                        container version with the name was run last (or
                        actually whatever is symlinked under
                        `.vagga/container_name`). Implies `--no-build`

Currently there is no way to provide additional arguments to commands declared with !Supervise.

The --only and --exclude arguments are useful for isolating some single app to a separate console. For example, if you have vagga run that runs full application stack including a database, cache, web-server and your little django application, you might do the following:

$ vagga run --exclude django

Then in another console:

$ vagga run --only django

Now you have just a django app that you can observe logs from and restart independently of other applications.

Global Settings¶

Settings are searched for in one of the following files:

• $HOME/.config/vagga/settings.yaml
• $HOME/.vagga/settings.yaml
• $HOME/.vagga.yaml

Supported settings:

storage-dir¶

Directory where to put images build by vagga. Usually they are stored in .vagga subdirectory of the project dir. It’s mostly useful when the storage-dir points to a directory on a separate partition. Path may start with ~/ which means path is inside the user’s home directory.

cache-dir¶

Directory where to put cache files during the build. This is used to speed up the build process. By default cache is put into .vagga/.cache in project directory but this setting allows to have cache directory shared between multiple projects. Path may start with ~/ which means path is inside the user’s home directory.

site-settings¶

(experimental) The mapping of project paths to settings for this specific project.

proxy-env-vars¶

Enable forwarding for proxy environment variables. Default true. Environment variables currently that this setting influence currently: http_proxy, https_proxy, ftp_proxy, all_proxy, no_proxy.

All project-local settings are also allowed here.

Project-Local Settings¶

Project-local settings may be in the project dir in:

* ``.vagga.settings.yaml``
* ``.vagga/settings.yaml``

All project-local settings are also allowed in global config.

While settings can potentially be checked-in to version control it’s advised not to do so.

version-check¶

If set to true (default) vagga will check if the container that is already built is up to date with config. If set to false vagga will use any container with same name already built. It’s only useful for scripts for performance reasons or if you don’t have internet and containers are not too outdated.

ubuntu-mirror¶

Set to your preferred ubuntu mirror. By default it’s mirror://mirrors.ubuntu.com/mirrors.txt which means mirror will be determined automatically. Note that it’s different from default in ubuntu itself where http://archive.ubuntu.com/ubuntu/ is the default.

Could not read /etc/subuid or /etc/subgid¶

The full error might look like:

ERROR:vagga::container::uidmap: Error reading uidmap: Can't open /etc/subuid: No such file or directory (os error 2)
WARN:vagga::container::uidmap: Could not read /etc/subuid or /etc/subgid (see http://bit.ly/err_subuid)
error setting uid/gid mappings: Operation not permitted (os error 1)

This means there is no /etc/subuid file. It probably means you need to create one. The recommended contents are following:

your_user_name:100000:65536

You may get another similar error:

ERROR:vagga::container::uidmap: Error reading uidmap: /etc/subuid:2: Bad syntax: "user:100000:100O"
WARN:vagga::container::uidmap: Could not read /etc/subuid or /etc/subgid (see http://bit.ly/err_subuid)
error setting uid/gid mappings: Operation not permitted (os error 1)

This means somebody has edited /etc/subuid and made an error. Just open the file (note it’s owned by root) and fix the issue (in the example the last character should be zero, but it’s a letter “O”).

Can’t find newuidmap or newgidmap¶

Full error usually looks like:

WARN:vagga::process_util: Can't find `newuidmap` or `newuidmap` (see http://bit.ly/err_idmap)
error setting uid/gid mappings: No such file or directory (os error 2)

There might be two reasons for this:

1. The binaries are not installed (see below)
2. The commands are not in PATH

In the latter case you should fix your PATH.

The packages for Ubuntu >= 14.04:

$ sudo apt-get install uidmap

The Ubuntu 12.04 does not have the package. But you may use the package from newer release (the following version works fine on 12.04):

$ wget http://gr.archive.ubuntu.com/ubuntu/pool/main/s/shadow/uidmap_4.1.5.1-1ubuntu9_amd64.deb
$ sudo dpkg -i uidmap_4.1.5.1-1ubuntu9_amd64.deb

Most distributions (known: Nix, Archlinux, Fedora), does have binaries as part of “shadow” package, so have them installed on every system.

You should not run vagga as root¶

Well, sometimes users get some permission denied errors and try to run vagga with sudo. Running as root is never an answer.

Here is a quick check list on permission checks:

• Check owner (and permission bits) of .vagga subdirectory if it exists, otherwise the directory where vagga.yaml is (project dir). In case you have already run vagga as root just do sudo rm -rf .vagga
• Could not read /etc/subuid or /etc/subgid
• Can’t find newuidmap or newgidmap
• Check uname -r to have version of 3.9 or greater
• Check sysctl kernel.unprivileged_userns_clone the setting must either not exist at all or have value of 1
• Check zgrep CONFIG_USER_NS /proc/config.gz or grep CONFIG_USER_NS "/boot/config-`uname -r`" (ubuntu) the setting should equal to y

The error message might look like:

You should not run vagga as root (see http://bit.ly/err_root)

Or it might look like a warning:

WARN:vagga::launcher: You are running vagga as a user different from the owner of project directory. You may not have needed permissions (see http://bit.ly/err_root)

Both show that you don’t run vagga by user that owns project. The ligitimate reasons to run vagga as root are:

• If you run vagga in container (i.e. in vagga itself) and the root is not a real root
• If your project dir is owned by root (for whatever crazy reason)

Both cases should inhibit the warning automatically, but as a last resort you may try vagga --no-owner-check. If you have good case where this works, please file an issue and we might make the check better.