Permalink
Please sign in to comment.
Browse files
Merge pull request #68 from mbruzek/packge-update-readme
Updating the packages from the jujubox removal, and updating README
- Loading branch information...
2 parents
2c05cfa
+
d766448
commit 3df12bf82ce6bd16d519bb812c710831e799e6fb
chuckbutler
committed
Nov 26, 2016
chuckbutler
committed
Showing
with
90 additions
and 88 deletions.
- +86 −78 README.md
- +4 −10 charmbox-setup.sh
| @@ -1,107 +1,115 @@ | ||
| -# Charmbox | ||
| +# Charm Box | ||
| -Charmbox is an extension of the [jujubox](https://registry.hub.docker.com/u/whitmo/jujubox/) | ||
| -container which adds tools for development, testing, and review of Juju Charms. | ||
| +Charm box is a container project that provides a [Juju](https://jujucharms.com) | ||
| +[Charm](https://jujucharms.com/docs/stable/charms) development environment. The | ||
| +charmbox container includes tools for building, testing, and reviewing Juju | ||
| +Charms. | ||
| +Juju is an open source, universal model for applications. Juju allows you to | ||
| +deploy, configure, manage, maintain, and scale cloud services quickly and | ||
| +efficiently on public clouds, as well as on physical servers. | ||
| -## Usage | ||
| +This container comes with the basic tools you need to get started with Juju and | ||
| +Charms. It includes [charm-tools](https://github.com/juju/charm-tools) to | ||
| +build charms and [bundletester](https://github.com/juju-solutions/bundletester) | ||
| +to test charms. | ||
| +This container is built on top of the | ||
| +[jujubox](https://github.com/juju-solutions/jujubox) container, adding tools | ||
| +and functionality. Refer to the jujubox project for more information about the | ||
| +options to run that container and the volumes available. | ||
| -### Juju Inside Docker | ||
| +To use this container you need to install Docker, download charmbox, and run | ||
| +charmbox. | ||
| -If you already have Docker installed (see below), and you don't want to install | ||
| -Juju on your host machine, the container can be run directly from Docker Hub: | ||
| +# Install Docker | ||
| - sudo docker run --rm -ti jujusolutions/charmbox | ||
| +## Linux | ||
| +Install Docker using the package manager for your Linux distribution, or | ||
| +[get.docker.com](https://get.docker.com/). We recommend Docker version 1.6 or | ||
| +greater. | ||
| -Once inside the container, you can use quickstart to set up Juju with any provider | ||
| -except local, and use bundletester to test a charm: | ||
| +## Mac OS X | ||
| - $ubuntu@ab3d:~/$ juju quickstart | ||
| - $ubuntu@ab3d:~/$ bundletester -t cs:trusty/ubuntu | ||
| +There are several ways to | ||
| +[install Docker on Mac OS X](https://docs.docker.com/engine/installation/mac/). | ||
| +Consult the latest documentation on | ||
| +[Getting Started with Docker for Mac](https://docs.docker.com/docker-for-mac/). | ||
| -Note that local provider is not currently available within the container, | ||
| -but it is possible to use an existing local provider with Charmbox (see below). | ||
| +# Download charmbox | ||
| +The easiest way to use charmbox is to simply pull the container from the | ||
| +[Docker hub](https://registry.hub.docker.com/u/jujusolutions/charmbox/). | ||
| -### Using Charmbox with Existing Juju | ||
| +``` | ||
| +docker pull jujusolutions/charmbox | ||
| +``` | ||
| -If you already have Juju configured, you can use your existing Juju installation, | ||
| -including any environments, with a few extra arguments to the run command: | ||
| +If you want to see the code you can download the charmbox project from | ||
| +[github](https://github.com/juju-solutions/charmbox) and build it from source. | ||
| - sudo docker run --rm -ti --net=host -v $HOME/.juju:/home/ubuntu/.juju jujusolutions/charmbox | ||
| +``` | ||
| +git clone https://github.com/juju-solutions/charmbox.git && cd charmbox | ||
| +docker build -t jujusolutions/charmbox ./ | ||
| +``` | ||
| +# Run charmbox | ||
| -### Using Charmbox with Existing Juju and Local Provider | ||
| +There are several different ways to run charmbox depending on what you are | ||
| +trying to accomplish. | ||
| -If you wish to use local provider, you will need to bootstrap from **outside** | ||
| -the container, but all subsequent operations will work normally within the | ||
| -container: | ||
| +## Running charmbox to build Charms | ||
| - juju switch local | ||
| - juju bootstrap | ||
| - sudo docker run --rm --net=host -v $HOME/.juju:/home/ubuntu/.juju -ti charmbox | ||
| +The main use case for charm box is to build charms from layers and interfaces. | ||
| +By using charmbox you do not need to install and configure the tools. | ||
| -Once inside the container, you can use bundletester to test a charm: | ||
| +As with jujubox you should volume mount (-v) `$JUJU_DATA` directory from the | ||
| +host to the charmbox container so you preserve the Juju information between | ||
| +runs. The output from a charm build will be in `/home/ubuntu/charms/` so mount | ||
| +the `$JUJU_REPOSITORY` directory to preserve the built artifacts. To have | ||
| +access to the layers and interfaces, mount the `$LAYER_PATH` and | ||
| +`$INTERFACE_PATH` from the host to the charmbox container. Remember the | ||
| +charmbox file system is reset after you exit the container. | ||
| - $ubuntu@ab3d:~/$ bundletester -t lp:~user/charms/trusty/foo/branch | ||
| - $ubuntu@ab3d:~/$ exit | ||
| +``` | ||
| +docker run --rm -it \ | ||
| + -v $JUJU_DATA:/home/ubuntu/.local/share/juju \ | ||
| + -v $JUJU_REPOSITORY:/home/ubuntu/charms \ | ||
| + -v $LAYER_PATH:/home/ubuntu/charms/layers \ | ||
| + -v $INTERFACE_PATH:/home/ubuntu/charms/interfaces \ | ||
| + jujusolutions/charmbox | ||
| +``` | ||
| -Once you are done with the container, make sure you destroy the local provider that | ||
| -you bootstrapped: | ||
| +## Running charmbox to test Charms | ||
| - juju destroy-environment local | ||
| +Another use case for charmbox is to use the test tools included. In this case | ||
| +you may need to mount the charm or bundle directory and run the `bundletester` | ||
| +tool. You can map the current workign directory into charmbox for testing | ||
| +a bundle or charm. | ||
| +``` | ||
| +docker run --rm -it \ | ||
| + -v $JUJU_DATA:/home/ubuntu/.local/share/juju \ | ||
| + -v $JUJU_REPOSITORY:/home/ubuntu/charms \ | ||
| + -v $PWD:/home/ubuntu/pwd \ | ||
| + jujusolutions/charmbox | ||
| +``` | ||
| -### Using Charmbox with Charms on your Host Machine | ||
| +See the Environment Variables | ||
| +[reference](https://jujucharms.com/docs/2.0/reference-environment-variables) | ||
| +for more details on `$JUJU_DATA`, `$JUJU_REPOSITORY`, `$LAYER_PATH` and | ||
| +`$INTERFACE_PATH` . | ||
| -If you have charms already checked out on your host machine, you can mount the | ||
| -Juju repository subdirectory: | ||
| +## charmbox and the LXD provider | ||
| - sudo docker run --rm -ti -v $JUJU_REPOSITORY/trusty:/home/ubuntu/trusty jujusolutions/charmbox | ||
| +At this time you can not run charmbox on the LXD provider inside of Docker | ||
| +because of some nested container issues. If you want to use the LXD provider | ||
| +install Juju and LXD on the host system. | ||
| -At this time, you cannot directly mount `$JUJU_REPOSITORY` inside | ||
| -the container because it would overwrite `/home/ubuntu`. Thus, it is | ||
| -recommended that you mount the `trusty` or `precise` subdirectories. | ||
| +# More information | ||
| -### Mounting CWD into charmbox for testing | ||
| +For more information about what you can do in charmbox check out the | ||
| +[Juju documenation](https://jujucharms.com/docs). | ||
| -You can map the current working directory into charmbox for testing a single | ||
| -charm: | ||
| - | ||
| - sudo docker run --rm -ti -v $(pwd):/home/ubuntu/trusty/{charm} jujusolutions/charmbox | ||
| - | ||
| - | ||
| -## Building Charmbox from Source | ||
| - | ||
| - git clone https://github.com/juju-solutions/charmbox.git && cd charmbox | ||
| - sudo docker build -t charmbox . | ||
| - sudo docker run --rm -ti charmbox | ||
| - | ||
| - | ||
| -## Installing Docker | ||
| - | ||
| -### Linux | ||
| - | ||
| -Install Docker using the package manager for your distro, or | ||
| -[get.docker.com](https://get.docker.com/). | ||
| - | ||
| -Docker >= 1.4.1 recommended. | ||
| - | ||
| -### OS X | ||
| - | ||
| -Docker does not run natively in OS X, so we'll need to use VirtualBox | ||
| -and docker-machine. This is relatively easy for users of brew: | ||
| - | ||
| - brew install cask | ||
| - brew cask install virtualbox | ||
| - brew install docker | ||
| - brew install docker-machine | ||
| - | ||
| - docker-machine create -d virtualbox default | ||
| - docker-machine start default && eval $(docker-machine env default) | ||
| - | ||
| -When docker-machine finishes, it will prompt you to export Docker | ||
| -environment variables. With that done, you're ready to use docker. | ||
| - | ||
| - docker run -ti jujusolutions/charmbox | ||
| +If you find any bugs please create an issue in the | ||
| +[jujubox github repository](https://github.com/juju-solutions/charmbox/issues). |
0 comments on commit
3df12bf