diff --git a/README.md b/README.md deleted file mode 100644 index 8eb57fe..0000000 --- a/README.md +++ /dev/null @@ -1,45 +0,0 @@ -bootstrap-vz -=========================================== -bootstrap-vz is a bootstrapping framework for Debian. -It is is specifically targeted at bootstrapping systems for virtualized environments. -bootstrap-vz runs without any user intervention and generates ready-to-boot images for -[a number of virtualization platforms](http://andsens.github.io/bootstrap-vz/providers.html). -Its aim is to provide a reproducable bootstrapping process using [manifests](http://andsens.github.io/bootstrap-vz/manifest.html) as well as supporting a high degree of customizability through plugins. - -bootstrap-vz was coded from scratch in python once the bash script architecture that was used in the -[build-debian-cloud](https://github.com/andsens/build-debian-cloud) bootstrapper reached its -limits. - -Documentation -------------- -The end-user documentation for bootstrap-vz is available -at [andsens.github.io/bootstrap-vz](http://andsens.github.io/bootstrap-vz). -There, you can discover [what the dependencies](http://andsens.github.io/bootstrap-vz/#dependencies) -for a specific cloud provider are, [see a list of available plugins](http://andsens.github.io/bootstrap-vz/plugins.html) -and learn [how you create a manifest](http://andsens.github.io/bootstrap-vz/manifest.html). - -Installation ------------- - -bootstrap-vz has a master branch for stable releases and a development for, well, development. -After checking out the branch of your choice you can install the python dependencies by running -`python setup.py install`. However, depending on what kind of image you'd like to bootstrap, -there are other debian package dependencies as well, at the very least you will need `debootstrap`. -[The documentation](http://andsens.github.io/bootstrap-vz/) explains this in more detail. - -Note that bootstrap-vz will tell you which tools it requires when they aren't -present (the different packages are mentioned in the error message), so you can -simply run bootstrap-vz once to get a list of the packages, install them, -and then re-run. - -Developers ----------- -The API documentation, development guidelines and an explanation of bootstrap-vz internals -can be found at [bootstrap-vz.readthedocs.org](http://bootstrap-vz.readthedocs.org). - -Contributing ------------- - -Contribution guidelines are described on the [CONTRIBUTING](CONTRIBUTING.md) file. There's also a -[topic on the documentation](http://bootstrap-vz.readthedocs.org/en/development/guidelines.html#coding-style) -regarding the coding style. diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..93c699f --- /dev/null +++ b/README.rst @@ -0,0 +1,145 @@ +Introduction +============ + +bootstrap-vz is a bootstrapping framework for Debian. +It is is specifically targeted at bootstrapping systems for virtualized environments. +bootstrap-vz runs without any user intervention and +generates ready-to-boot images for a number of virtualization +platforms. +Its aim is to provide a reproducable bootstrapping process using +`manifests `__ as +well as supporting a high degree of customizability through plugins. + +bootstrap-vz was coded from scratch in python once the bash script +architecture that was used in the +`build-debian-cloud `__ +bootstrapper reached its limits. + +Documentation +------------- + +The end-user documentation for bootstrap-vz is available at +`andsens.github.io/bootstrap-vz `__. +There, you can discover `what the +dependencies `__ +for a specific cloud provider are, `see a list of available +plugins `__ and +learn `how you create a +manifest `__. + +Installation +------------ + +bootstrap-vz has a master branch for stable releases and a development +for, well, development. + +After checking out the branch of your choice you can install the +python dependencies by running ``python setup.py install``. However, +depending on what kind of image you'd like to bootstrap, there are +other debian package dependencies as well, at the very least you will +need ``debootstrap``. +`The documentation `__ +explains this in more detail. + +Note that bootstrap-vz will tell you which tools it requires when they +aren't present (the different packages are mentioned in the error +message), so you can simply run bootstrap-vz once to get a list of the +packages, install them, and then re-run. + +Quick start +----------- + +Here are a few quickstart tutorials for the most common images. +If you plan on partitioning your volume, you will need the ``parted`` +package and ``kpartx``: + +.. code:: sh + + root@host:~# apt-get install parted kpartx + +VirtualBox Vagrant +~~~~~~~~~~~~~~~~~~ + +:: + + user@host:~$ sudo -i # become root + root@host:~# git clone https://github.com/andsens/bootstrap-vz.git # Clone the repo + root@host:~# apt-get install qemu-utils debootstrap python-pip # Install dependencies from aptitude + root@host:~# pip install termcolor jsonschema fysom docopt pyyaml # Install python dependencies + root@host:~# bootstrap-vz/bootstrap-vz bootstrap-vz/manifests/virtualbox-vagrant.manifest.yml + +If you want to use the `minimize\_size `__ +plugin, you will have to install the ``zerofree`` package and `VMWare +Workstation `__ +as well. + +Amazon EC2 EBS backed AMI +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code:: sh + + user@host:~$ sudo -i # become root + root@host:~# git clone https://github.com/andsens/bootstrap-vz.git # Clone the repo + root@host:~# apt-get install debootstrap python-pip # Install dependencies from aptitude + root@host:~# pip install termcolor jsonschema fysom docopt pyyaml boto # Install python dependencies + root@host:~# bootstrap-vz/bootstrap-vz bootstrap-vz/manifests/ec2-ebs-debian-official-amd64-pvm.manifest.yml + +To bootstrap S3 backed AMIs, bootstrap-vz will also need the +``euca2ools`` package. However, version 3.2.0 is required meaning you +must however install it directly from the eucalyptus repository like +this: + +.. code:: sh + + apt-get install --no-install-recommends python-dev libxml2-dev libxslt-dev gcc + pip install git+git://github.com/eucalyptus/euca2ools.git@v3.2.0 + +Cleanup +------- + +bootstrap-vz tries very hard to clean up after itself both if a run was +successful but also if it failed. This ensures that you are not left +with volumes still attached to the host which are useless. If an error +occurred you can simply correct the problem that caused it and rerun +everything, there will be no leftovers from the previous run (as always +there are of course rare/unlikely exceptions to that rule). The error +messages should always give you a strong hint at what is wrong, if that +is not the case please consider `opening an +issue `__ and attach +both the error message and your manifest (preferably as a gist or +similar). + +Dependencies +------------ + +bootstrap-vz has a number of dependencies depending on the target +platform and `the selected plugins `__. At a bare minimum +the following python libraries are needed: \* +`termcolor `__ \* +`fysom `__ \* +`jsonschema `__ \* +`docopt `__ \* +`pyyaml `__ To bootstrap Debian +itself +`debootstrap `__ is +needed as well. + +Any other requirements are dependent upon the manifest configuration +and are detailed in the corresponding sections of the documentation. +bootstrap-vz will however warn you if a requirement has not been met, +before the bootstrapping process begins. + +Developers +---------- + +The API documentation, development guidelines and an explanation of +bootstrap-vz internals can be found at +`bootstrap-vz.readthedocs.org `__. + +Contributing +------------ + +Contribution guidelines are described on the +`CONTRIBUTING `__ file. There's also a `topic on the +documentation `__ +regarding the coding style. diff --git a/docs/index.rst b/docs/index.rst index 16a5568..9944ea4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,14 +3,14 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to bootstrap-vz's documentation! -======================================== -Contents: +bootstrap-vz +============ .. toctree:: - :maxdepth: 2 + :maxdepth: 1 + intro manifest providers/index plugins/index @@ -21,11 +21,3 @@ Contents: howitworks switches logging - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/docs/intro.rst b/docs/intro.rst new file mode 100644 index 0000000..72a3355 --- /dev/null +++ b/docs/intro.rst @@ -0,0 +1 @@ +.. include:: ../README.rst diff --git a/docs/providers/index.rst b/docs/providers/index.rst index fb991f2..f5b187b 100644 --- a/docs/providers/index.rst +++ b/docs/providers/index.rst @@ -1,4 +1,3 @@ - Providers =========