vagrant-lxc-ng/README.md

217 lines
7.9 KiB
Markdown
Raw Normal View History

2013-04-12 21:29:03 +00:00
# vagrant-lxc [![Build Status](https://travis-ci.org/fgrehm/vagrant-lxc.png?branch=master)](https://travis-ci.org/fgrehm/vagrant-lxc) [![Gem Version](https://badge.fury.io/rb/vagrant-lxc.png)](http://badge.fury.io/rb/vagrant-lxc) [![Code Climate](https://codeclimate.com/github/fgrehm/vagrant-lxc.png)](https://codeclimate.com/github/fgrehm/vagrant-lxc) [![Coverage Status](https://coveralls.io/repos/fgrehm/vagrant-lxc/badge.png?branch=master)](https://coveralls.io/r/fgrehm/vagrant-lxc)
2013-03-08 05:04:17 +00:00
2013-04-10 06:12:10 +00:00
Linux Containers support for Vagrant 1.1+
2013-03-03 03:38:48 +00:00
## Dependencies
2013-04-10 06:12:10 +00:00
* Vagrant 1.1+ (1.1.3+ recommended)
* lxc 0.7.5+ (0.8.0-rc1+ recommended)
2013-04-15 13:54:42 +00:00
* redir (if you are planning to use port forwarding)
* arch command (uname -m) on PATH
2013-04-10 06:12:10 +00:00
* A Kernel [higher than 3.5.0-17.28](#help-im-unable-to-restart-containers)
2013-04-10 06:17:48 +00:00
On a clean Ubuntu 12.10 machine it means something like:
2013-03-03 03:38:48 +00:00
```
2013-03-05 04:04:39 +00:00
sudo apt-get update && sudo apt-get dist-upgrade
sudo apt-get install lxc redir
2013-04-10 06:17:48 +00:00
# Downloads and install Vagrant 1.1.5
wget "http://files.vagrantup.com/packages/64e360814c3ad960d810456add977fd4c7d47ce6/vagrant_`uname -m`.deb" -O /tmp/vagrant.deb
sudo dpkg -i /tmp/vagrant.deb
2013-03-03 03:38:48 +00:00
```
2013-04-10 06:12:10 +00:00
## What is currently supported? (v0.3.0)
2013-03-05 04:04:39 +00:00
2013-03-30 22:49:32 +00:00
Pretty much everything you need from Vagrant:
* Vagrant's `up`, `halt`, `reload`, `destroy`, `ssh` and `package` commands (box packaging is kind of experimental)
2013-03-05 04:04:39 +00:00
* Shared folders
* Provisioning
2013-03-05 04:04:39 +00:00
* Setting container's host name
* Port forwarding
2013-03-05 04:04:39 +00:00
2013-03-18 23:44:51 +00:00
*Please refer to the [closed issues](https://github.com/fgrehm/vagrant-lxc/issues?labels=&milestone=&page=1&state=closed)
2013-04-10 06:12:10 +00:00
and the [changelog](CHANGELOG.md) for most up to date information.*
2013-03-18 23:44:51 +00:00
2013-03-05 04:04:39 +00:00
## Current limitations
2013-03-03 03:38:48 +00:00
2013-03-27 13:16:42 +00:00
* Does not detect forwarded ports collision, right now you are responsible for taking care of that
2013-04-10 06:12:10 +00:00
* A hell lot of `sudo`s (this will probably be like this until [user namespaces](http://s3hh.wordpress.com/2013/02/12/user-namespaces-lxc-meeting/) are supported)
* [Does not tell you if dependencies are not met](https://github.com/fgrehm/vagrant-lxc/issues/11)
(will probably just throw up some random error)
2013-03-05 04:04:39 +00:00
* + bunch of other [core features](https://github.com/fgrehm/vagrant-lxc/issues?labels=core&milestone=&page=1&state=open)
2013-03-05 04:56:49 +00:00
and some known [bugs](https://github.com/fgrehm/vagrant-lxc/issues?labels=bug&page=1&state=open)
2013-03-03 03:38:48 +00:00
2013-04-10 06:12:10 +00:00
## Installation
```
vagrant plugin install vagrant-lxc
```
2013-03-03 03:38:48 +00:00
## Usage
2013-04-22 02:42:41 +00:00
After installing, add a [base box](#available-boxes) using any name you want, for example:
2013-03-03 03:38:48 +00:00
```
2013-04-22 02:42:41 +00:00
vagrant box add lxc-quantal64 http://dl.dropbox.com/u/13510779/lxc-quantal-amd64-2013-04-21.box
2013-03-03 03:38:48 +00:00
```
2013-04-10 06:12:10 +00:00
Make a Vagrantfile that looks like the following, filling in your information where necessary:
2013-03-03 03:38:48 +00:00
```ruby
Vagrant.configure("2") do |config|
2013-04-22 02:42:41 +00:00
# Change it to the name of the box you have just added
2013-04-10 06:12:10 +00:00
config.vm.box = "lxc-quantal64"
2013-03-04 01:42:18 +00:00
2013-04-10 06:12:10 +00:00
# You can omit this block if you don't need to override any container setting
2013-03-03 03:38:48 +00:00
config.vm.provider :lxc do |lxc|
2013-04-10 06:12:10 +00:00
# OPTIONAL: Same effect as as 'customize ["modifyvm", :id, "--memory", "1024"]' for VirtualBox
lxc.customize 'cgroup.memory.limit_in_bytes', '1024M'
# OPTIONAL: Limits swap size
lxc.customize 'cgroup.memory.memsw.limit_in_bytes', '512M'
2013-03-03 03:38:48 +00:00
end
end
```
2013-04-10 06:12:10 +00:00
And finally run `vagrant up --provider=lxc`.
2013-03-18 23:44:51 +00:00
If you are on a mac or window host and still want to try this plugin out, you
2013-03-31 21:22:57 +00:00
can use the [same Vagrant VirtualBox machine I use for development](#using-virtualbox-for-development).
2013-03-03 03:38:48 +00:00
2013-04-22 02:42:41 +00:00
### Available boxes
2013-04-22 04:38:54 +00:00
| LINK | DESCRIPTION |
2013-04-22 02:42:41 +00:00
| --- | --- |
2013-04-22 04:38:54 +00:00
| [lxc-raring-amd64-2013-04-21.box](http://dl.dropbox.com/u/13510779/lxc-raring-amd64-2013-04-21.box) | Ubuntu 13.04 Raring x86_64 (Puppet 3.1.1) |
| [lxc-quantal-amd64-2013-04-21.box](http://dl.dropbox.com/u/13510779/lxc-quantal-amd64-2013-04-21.box) | Ubuntu 12.10 Quantal x86_64 (Puppet 3.1.1 & Chef 11.4.0) |
| [lxc-precise-amd64-2013-04-21.box](http://dl.dropbox.com/u/13510779/lxc-precise-amd64-2013-04-21.box) | Ubuntu 12.04 Precise x86_64 (Puppet 3.1.1 & Chef 11.4.0) |
2013-04-22 02:42:41 +00:00
*Please note that I'm currently using only the quantal x86_64 on a daily basis,
and I've only done some basic testing with the others*
You can also build a clean box by providing `CHEF=0` and `PUPPET=0` to the available
[rake tasks](tasks/boxes.rake). For example:
```
CHEF=0 PUPPET=0 rake boxes:ubuntu:build:precise64
```
2013-04-10 06:12:10 +00:00
### Storing container's rootfs on a separate partition
Before the 0.3.0 version of this plugin, there used to be a support for specifying
the container's rootfs path from the `Vagrantfile`, on 0.3.0 this was removed as you
can achieve the same effect by symlinking or mounting `/var/lib/lxc` on a separate
partition.
### NFS shared folders
NFS shared folders are not supported and will behave as a "normal" shared folder
so we can share the same Vagrantfile with VBox environments.
2013-03-03 03:38:48 +00:00
## Development
2013-03-12 18:29:18 +00:00
If want to develop from your physical machine, just sing that same old song:
2013-03-03 03:38:48 +00:00
```
2013-04-10 06:12:10 +00:00
git clone git://github.com/fgrehm/vagrant-lxc.git
2013-03-03 03:38:48 +00:00
cd vagrant-lxc
bundle install
bundle exec rake # to run unit specs
```
To run acceptance specs, you'll have to ssh into one of the [development boxes](development/Vagrantfile) and run:
```
bundle exec rake spec:acceptance
2013-03-03 03:38:48 +00:00
```
2013-03-12 18:29:18 +00:00
To build the provided quantal64 box:
```
bundle exec rake boxes:quantal64:build
2013-03-14 23:26:40 +00:00
vagrant box add quantal64 boxes/output/lxc-quantal64.box
```
### Using `vagrant-lxc` to develop itself
2013-03-03 03:38:48 +00:00
Yes! The gem has been [bootstrapped](http://en.wikipedia.org/wiki/Bootstrapping_(compilers)
and since you can boot a container from within another, after cloning the
project you can run the commands below from the host machine to get a container
ready for development:
```sh
# Required in order to allow nested containers to be started
2013-03-09 19:41:24 +00:00
sudo apt-get install apparmor-utils
sudo aa-complain /usr/bin/lxc-start
2013-03-14 23:26:40 +00:00
bundle install
cd development
bundle exec vagrant up lxc --provider=lxc
bundle exec vagrant ssh lxc
```
2013-03-14 23:26:40 +00:00
That should result in a container ready to be `bundle exec vagrant ssh`ed.
Once you've SSH into the guest container, you'll be already on the project's root.
Keep in mind that you'll probably need to run `sudo aa-complain /usr/bin/lxc-start`
on the host whenever you want to hack on it, otherwise you won't be able to
start nested containers there to try things out.
### Using VirtualBox for development
2013-03-18 23:44:51 +00:00
```
cd development
bundle exec vagrant up vbox
2013-03-29 15:39:57 +00:00
# A reload is needed to ensure the updated kernel gets loaded
2013-03-18 23:44:51 +00:00
bundle exec vagrant reload vbox
bundle exec vagrant ssh vbox
```
2013-03-03 03:38:48 +00:00
2013-03-05 04:04:39 +00:00
## Protips
2013-03-03 03:38:48 +00:00
2013-03-05 04:04:39 +00:00
If you want to find out more about what's going on under the hood on vagrant,
2013-03-14 23:26:40 +00:00
prepend `VAGRANT_LOG=debug` to your `vagrant` commands. For `lxc-start`s
2013-03-05 04:04:39 +00:00
debugging set `LXC_START_LOG_FILE`:
2013-03-03 03:38:48 +00:00
```
2013-03-14 23:26:40 +00:00
LXC_START_LOG_FILE=/tmp/lxc-start.log VAGRANT_LOG=debug vagrant up
2013-03-03 03:38:48 +00:00
```
2013-03-05 04:04:39 +00:00
This will output A LOT of information on your terminal and some useful information
about `lxc-start` to `/tmp/lxc-start.log`.
2013-03-03 03:38:48 +00:00
2013-03-18 23:44:51 +00:00
## Help! I'm unable to restart containers!
2013-03-04 01:23:26 +00:00
2013-03-05 04:04:39 +00:00
It happened to me quite a few times in the past and it seems that it is related
2013-03-05 04:56:49 +00:00
to a bug on linux kernel, so make sure you are using a bug-free kernel
2013-03-05 04:04:39 +00:00
(>= 3.5.0-17.28). More information can be found on:
2013-03-04 01:23:26 +00:00
2013-03-05 04:04:39 +00:00
* https://bugzilla.kernel.org/show_bug.cgi?id=47181
* https://bugs.launchpad.net/ubuntu/+source/linux/+bug/1021471
* https://bugs.launchpad.net/ubuntu/+source/linux/+bug/1065434
2013-03-04 04:06:08 +00:00
2013-03-11 01:02:46 +00:00
Sometimes the dev boxes I'm using are not able to `lxc-start` containers
2013-04-17 23:23:17 +00:00
anymore. Most of the times it was an issue with the arguments I provided
to it for customization (or a *buggy* kernel). If you run into that, rollback your changes
2013-03-11 01:02:46 +00:00
and try to `vagrant reload` the dev box. If it still doesn't work,
please file a bug at the [issue tracker](https://github.com/fgrehm/vagrant-lxc/issues).
2013-03-05 04:04:39 +00:00
2013-02-25 23:09:32 +00:00
## Similar projects
* [vagabond](https://github.com/chrisroberts/vagabond) - "a tool integrated with Chef to build local nodes easily"
* [vagueant](https://github.com/neerolyte/vagueant) - "vaguely like Vagrant for linux containers (lxc)"
2013-02-25 23:09:32 +00:00
## Contributing
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request