vagrant-lxc-ng/README.md

176 lines
5.8 KiB
Markdown
Raw Normal View History

2013-02-25 04:58:04 +00:00
# vagrant-lxc
Highly experimental, soon to come, Linux Containers support for the unreleased
2013-03-03 03:38:48 +00:00
Vagrant 1.1.
Please refer to the [closed issues](https://github.com/fgrehm/vagrant-lxc/issues?labels=&milestone=&page=1&state=closed)
to find out whats currently supported.
## WARNING
2013-03-05 04:04:39 +00:00
Please keep in mind that although I'm already using this on my laptop, this is
"almost alpha" software and things might go wrong.
2013-03-03 03:38:48 +00:00
## Dependencies
2013-03-05 04:04:39 +00:00
LXC, `bsdtar` packages and a Kernel [higher than 3.5.0-17.28](#im-unable-to-restart-containers),
which on Ubuntu 12.10 means:
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
2013-03-03 03:44:41 +00:00
sudo apt-get install lxc bsdtar
2013-03-03 03:38:48 +00:00
```
2013-03-05 04:04:39 +00:00
## What is currently supported?
* Vagrant's `up`, `halt`, `reload`, `destroy`, and `ssh` commands
* Shared folders
* Provisioners
* Setting container's host name
* Host-only / private networking
## Current limitations
2013-03-03 03:38:48 +00:00
* Ruby >= 1.9.3 only, patches for 1.8.7 are welcome
2013-03-05 04:04:39 +00:00
* A hell lot of `sudo`s
* Only a [single box supported](boxes), I'm still [figuring out what should go
on the .box file](https://github.com/fgrehm/vagrant-lxc/issues/4)
2013-03-03 23:42:29 +00:00
* "[works](https://github.com/fgrehm/vagrant-lxc/issues/20) on [my machine](https://github.com/fgrehm/vagrant-lxc/issues/7)" (TM)
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)
and a some known [bugs](https://github.com/fgrehm/vagrant-lxc/issues?labels=bug&page=1&state=open)
2013-03-03 03:38:48 +00:00
## Usage
For now you'll need to install the gem from sources:
```
2013-03-03 03:44:41 +00:00
git clone git://github.com/fgrehm/vagrant-lxc.git --recurse
2013-03-03 03:38:48 +00:00
cd vagrant-lxc
bundle install
bundle exec rake install
bundle exec rake boxes:build:ubuntu-cloud
2013-03-03 03:44:41 +00:00
vagrant-lxc box add ubuntu-cloud boxes/output/ubuntu-cloud.box
2013-03-03 03:38:48 +00:00
```
Since Vagrant 1.1 has not been released yet and to avoid messing up with you
current Vagrant installation, I've vendored Vagrant's sources from the master
2013-03-05 04:04:39 +00:00
and made it available from [`vagrant-lxc`](bin/vagrant-lxc). So after installing
`vagrant-lxc` and adding the base box, create a `Vagrantfile` like the one below
and run `vagrant-lxc up --provider=lxc`:
2013-03-03 03:38:48 +00:00
```ruby
Vagrant.configure("2") do |config|
config.vm.box = "ubuntu-cloud"
2013-03-04 01:42:18 +00:00
2013-03-05 04:04:39 +00:00
# Create a private network, which allows host-only access to the machine
# using a specific IP.
# config.vm.network :private_network, ip: "192.168.33.10"
2013-03-04 01:42:18 +00:00
# Share an additional folder to the guest Container. The first argument
# is the path on the host to the actual folder. The second argument is
# the path on the guest to mount the folder. And the optional third
# argument is a set of non-required options.
config.vm.synced_folder "/tmp", "/host_tmp"
2013-03-03 03:38:48 +00:00
config.vm.provider :lxc do |lxc|
2013-03-03 23:42:29 +00:00
# Same as 'customize ["modifyvm", :id, "--memory", "1024"]' for VirtualBox
lxc.start_opts << 'lxc.cgroup.memory.limit_in_bytes=400M'
# Limits swap size
lxc.start_opts << 'lxc.cgroup.memory.memsw.limit_in_bytes=500M'
2013-03-03 03:38:48 +00:00
end
2013-03-05 04:04:39 +00:00
# ... your puppet / chef / shell provisioner configs here ...
2013-03-03 03:38:48 +00:00
end
```
If you don't trust me and believe that it will mess up with your current Vagrant
2013-03-03 03:44:41 +00:00
installation and / or are afraid that something might go wrong with your machine,
fire up the [same Vagrant VirtualBox machine I'm using for development](#using-virtualbox-for-development)
2013-03-03 03:38:48 +00:00
to try things out and do the same as above. That might also get you up and running
2013-03-05 04:04:39 +00:00
if you are working on a mac or windows host ;)
2013-03-03 03:38:48 +00:00
## Development
If you know what you'll be doing and want to develop from your physical machine,
just sing that same old song:
```
git clone git://github.com/fgrehm/vagrant-lxc.git --recurse
cd vagrant-lxc
bundle install
bundle exec rake boxes:build:ubuntu-cloud
bundle exec rake # to run all specs
```
### Using VirtualBox for development
I've also prepared a Vagrant 1.0 VirtualBox machine for development that you can
get up and running with the [`setup-vagrant-dev-box`](setup-vagrant-dev-box)
script. Feel free to use it :)
```
2013-03-04 23:40:20 +00:00
cp Vagrantfile.dev.1.0 Vagrantfile
2013-03-03 03:38:48 +00:00
./setup-vagrant-dev-box
vagrant ssh
```
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,
prepend `VAGRANT_LOG=debug` to your `vagrant-lxc` commands. For `lxc-start`s
debugging set `LXC_START_LOG_FILE`:
2013-03-03 03:38:48 +00:00
```
2013-03-05 04:04:39 +00:00
LXC_START_LOG_FILE=/tmp/lxc-start.log VAGRANT_LOG=debug vagrant-lxc 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`.
Debugging whats going on with the container itself is a pain, there are some
nice little scripts on the [/dev](dev) folder of the project.
2013-03-03 03:38:48 +00:00
2013-03-04 01:23:26 +00:00
## Help!
### I've accidentaly ran `vagrant-lxc` on a Vagrant 1.0 project and I can't use it anymore
2013-03-03 03:38:48 +00:00
That happened to me before so here's how to recover:
```
rm -rf .vagrant
mv .vagrant.v1* .vagrant
```
2013-02-25 23:09:32 +00:00
2013-03-05 04:04:39 +00:00
### 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
to to a bug on linux kernel, so make sure you are using a bug-free kernel
(>= 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
Sometimes the Virtual Box dev machine I'm using is not able to `lxc-start`
containers anymore. Most of the times it was an issue with the [arguments](https://github.com/fgrehm/vagrant-lxc/blob/master/lib/vagrant-lxc/container.rb#L85)
[I provided](https://github.com/fgrehm/vagrant-lxc/blob/master/example/Vagrantfile#L12-L15)
2013-03-05 04:04:39 +00:00
to it. If you run into that, rollback your changes and try to `vagrant reload`
the dev box. If it still doesn't work, please file a bug at the issue tracker
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