From f6cabe9dddfa33d81ed4d19caa9642a60c89385d Mon Sep 17 00:00:00 2001 From: David Wrede Date: Wed, 25 May 2016 10:43:14 -0700 Subject: [PATCH] Updated tutorial with more Linux caveats and minor formatting fixes Signed-off-by: David Wrede --- .../shared/_setup_environment.html.md.erb | 4 +- .../getting-started-configure-plan.html.md | 2 +- .../getting-started-create-plan.html.md.erb | 4 +- .../getting-started-process-build.html.md | 9 ++- .../getting-started-run-package.html.md | 80 ------------------- 5 files changed, 11 insertions(+), 88 deletions(-) delete mode 100644 www/source/tutorials/getting-started-run-package.html.md diff --git a/www/source/shared/_setup_environment.html.md.erb b/www/source/shared/_setup_environment.html.md.erb index 8fdf963c62..a48f73e0f5 100644 --- a/www/source/shared/_setup_environment.html.md.erb +++ b/www/source/shared/_setup_environment.html.md.erb @@ -15,9 +15,9 @@ To start building artifacts in Habitat, you first need to clone the Habitat repo eval "$(docker-machine env default)" -4. From the root of your local repo, run `make shell`. This will build the Docker container that contains a basic development environment for building the Habitat binaries, including the studio environment. During the initial creation process, the Docker container will be built from scratch. This can take several minutes. + If your host machine is running Linux, run `export IN_DOCKER=true`. - > Note: If your host machine is running Linux, run `export IN_DOCKER=true` before calling `make shell`. +4. From the root of your local repo, run `make shell`. This will build the Docker container that contains a basic development environment for building the Habitat binaries, including the studio environment. During the initial creation process, the Docker container will be built from scratch. This can take several minutes. Once `make shell` completes, you will be at a bash prompt inside the habitat/devshell container. You should see a prompt like the following: diff --git a/www/source/tutorials/getting-started-configure-plan.html.md b/www/source/tutorials/getting-started-configure-plan.html.md index 2fbf5b753e..49669484d8 100644 --- a/www/source/tutorials/getting-started-configure-plan.html.md +++ b/www/source/tutorials/getting-started-configure-plan.html.md @@ -15,7 +15,7 @@ For example, the archive for our Node.js app already has a configuration file ca 2. Open `config/config.json` in your text editor. -3. Copy the contents from the original `config.json` into `config/config.json` as shown below. +3. Copy the contents from the original `config.json` (shown below) into `config/config.json`. { "message": "Hello, World!", diff --git a/www/source/tutorials/getting-started-create-plan.html.md.erb b/www/source/tutorials/getting-started-create-plan.html.md.erb index dbbcb915a8..8ca8db5e58 100644 --- a/www/source/tutorials/getting-started-create-plan.html.md.erb +++ b/www/source/tutorials/getting-started-create-plan.html.md.erb @@ -14,7 +14,7 @@ To create a plan, do the following: [1][default:/src:0]$cd plans -2. Create a new directory and a plan called _mytutorialapp_ by calling the `new-plan` target. +2. Create a new directory and a plan called "mytutorialapp" by calling the `new-plan` target. [2][default:/src/plans:0]$make new-plan plan=mytutorialapp @@ -73,7 +73,7 @@ We now have a skeleton plan, but we need to modify some of its settings before w pkg_expose=(8080) -You've finished with the basic setup of your plan. It is time to move into defining how our source files from the previous step get installed into the _mytutorialapp_ artifact through callbacks. +You've finished with the basic setup of your plan. It is time to move into defining how our source files from the previous step get installed into the mytutorialapp artifact through callbacks. ## Add in callbacks diff --git a/www/source/tutorials/getting-started-process-build.html.md b/www/source/tutorials/getting-started-process-build.html.md index 2f0e3d4c1a..c3643d3c2e 100644 --- a/www/source/tutorials/getting-started-process-build.html.md +++ b/www/source/tutorials/getting-started-process-build.html.md @@ -5,7 +5,7 @@ title: Process your build # Run your service The Habitat depot can contain multiple versions and releases of a given artifact. When you start a Habitat service, and depending on whether or not you specify a particular version number, Habitat will either pull the latest version, or the latest release for that particular version of the artifact. -A supervisor manages any client app or service process within a Habitat service, so when a Habitat service starts up, the Supervisor executes a command on the client software through a run script that was either generated by Habitat when the artifact was built (through the `pkg_binaries_run` setting), or through a run hook like in the case of the _mytutorialapp_. +A supervisor manages any client app or service process within a Habitat service, so when a Habitat service starts up, the Supervisor executes a command on the client software through a run script that was either generated by Habitat when the artifact was built (through the `pkg_binaries_run` setting), or through a run hook like in the case of mytutorialapp. Services can currently be run in two different ways: You can either use the supervisor (`hab-sup`) directly, or you can use a Docker container that calls the supervisor. Using the `hab-sup` directly allows you to rapidly install and test your services before uploading any artifacts into a depot; however, using a Docker container does not require you to have the Habitat binaries built and installed on your host machine. Exporting your artifact into a Docker container also allows you to create a portable Habitat service that can be run anywhere Docker containers can run. @@ -26,8 +26,9 @@ To show the portability of Habitat, you will export and run a Habitat service fr [17][default:/src/plans:0]$hab install core/hab-pkg-dockerize -5. Run `hab pkg exec core/hab-pkg-dockerize hab-pkg-dockerize origin/packagename` with the origin and name of your artifact. These values are referenced in the pkg_origin and pkg_name settings of your plan, respectively. +5. Change directory and run `hab pkg exec core/hab-pkg-dockerize hab-pkg-dockerize origin/packagename` with the origin and name of your artifact. These values are referenced in the pkg_origin and pkg_name settings of your plan, respectively. + [18][default:/src/plans:0]$cd /src [18][default:/src:0]$hab pkg exec core/hab-pkg-dockerize hab-pkg-dockerize myorigin/mytutorialapp Habitat will proceed to unpack and install all necessary Habitat artifacts, the Habitat command-line interface (CLI) tools and binaries, the mytutorialapp artifact, and all of its dependencies. Then it will create an image using the Docker scratch image as the base image and build up the rest of the image from there. @@ -53,10 +54,12 @@ To show the portability of Habitat, you will export and run a Habitat service fr mytutorialapp(O): mytutorialapp(O): Running on http://0.0.0.0:8080 -4. Because we are running this service in a Docker container, you need the IP address of the VM that is running it to access the message of the day. Type the following command in your terminal window to bring up the site: +4. Because we are running this service in a Docker container, you need the IP address of the VM that is running it to access the message of the day. If your host machine is running Mac OS X, type the following command in your terminal window to bring up the site. open "http://$(docker-machine ip default):8080/" + If you're running on Linux, you can simply open a browser and go to http://localhost:8080. + Here's an example of what you should see in your browser: ![Screen shot of node.js tutorial output](/images/nodejs-tutorial-output.png) diff --git a/www/source/tutorials/getting-started-run-package.html.md b/www/source/tutorials/getting-started-run-package.html.md deleted file mode 100644 index b917719af2..0000000000 --- a/www/source/tutorials/getting-started-run-package.html.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Finding and running the sample package ---- - -# Run and update the package - -> **Note** This content is outdated and will be refactored into the current tutorial at a later time. - -In this tutorial, we have a simple Node.js application that is already packaged up using Habitat. It simply prints out a "Hello World" message whenever you access its URL endpoint. This step will show you how to run the application in a Docker container, make a small change, verify the change, and proceed onto updating the plan for the package itself. - -## Run the container -Because you pulled down a Docker image in the previous step, simply run the container using the same Docker CLI commands as you would for any other Docker container. Also, this Node.js app requires port 8080 to be open, so you need to include that in your run command. As that executes, Habitat performs some additional actions that are not part of a typical Docker container deployment. Let's walk through them. - -~~~ bash -$ docker run -p 8080:8080 -it quay.io/hab/nodejs-tutorial-app -hab(MN): Starting chef/nodejs-tutorial-app -hab(CS): Checking remote for newer versions... -hab(CS): Already running latest. -hab(GS): Supervisor 172.17.0.5: 74c1df5f-cd6a-4cf2-80de-173b6330a6c3 -hab(GS): Census nodejs-tutorial-app.default: e308aadf-c93d-4f3e-82cb-e82080544fe7 -hab(GS): Starting inbound gossip listener -hab(GS): Starting outbound gossip distributor -hab(GS): Starting gossip failure detector -hab(CN): Starting census health adjuster -hab(SC): Updated config.json -nodejs-tutorial-app(TS): Starting -nodejs-tutorial-app(SO): -nodejs-tutorial-app(O): > nodejs_tutorial_app@0.1.0 start /hab/srvc/nodejs-tutorial-app -nodejs-tutorial-app(O): > node server.js -nodejs-tutorial-app(O): -nodejs-tutorial-app(O): Running on http://0.0.0.0:8080 -~~~ - -The first thing that you should notice is that Habitat checks to see if there are any more recent versions of the nodejs-tutorial-app package from the depot. Then, unlike a traditional Docker container, we use a supervisor to start up and monitor the application inside the package payload. This combination of a supervisor and application is known as a Habitat service. - -The second thing you should notice is that the Supervisor in the Habitat service begins listening for other Habitat services that might be in its same service group. These service groups are used to share rumors about configuration changes, leader elections, health information of other services in the group, and so on. - -Finally, a configuration file name `config.json` was added or updated in the Habitat service. You'll learn more about configuration in the next section. - -Now that the Node.js app is running, connect to the Node server itself in your web browser to see the default message of the day. To do that, you must connect to the IP address of the VM that is running the Docker container. Type in the following command in your terminal window to bring up the site: - - open "http://$(docker-machine ip default):8080/" - -Here's an example of what you should see in your browser: - -![Screen shot of node.js tutorial output](/images/nodejs-tutorial-output.png) - -We will learn how to make permanent updates to our application in the next step, but for now, let's re-run our docker container and update the message value when our Habitat service starts up. To do this, we must pass in a Docker environment variable with the following format: HAB_PACKAGENAME='keyname=newvalue'. - - > Note: Your packagename must be upppercase. - -Here is how you change the message for nodejs-tutorial-app: - -~~~ bash -$ docker run -e HAB_NODEJS_TUTORIAL_APP='message="Habitat rocks!"' -p 8080:8080 -it chef/nodejs-tutorial-app -hab(MN): Starting chef/nodejs-tutorial-app -hab(CS): Checking remote for newer versions... -hab(CS): Already running latest. -hab(GS): Supervisor 172.17.0.3: 4b029dca-d365-486e-87ac-20cebc517127 -hab(GS): Census nodejs-tutorial-app.default: b5c66ceb-55dc-426d-b96a-d2998b6dfec3 -hab(GS): Starting inbound gossip listener -hab(GS): Starting outbound gossip distributor -hab(GS): Starting gossip failure detector -hab(CN): Starting census health adjuster -hab(SC): Updated config.json -nodejs-tutorial-app(TS): Starting -nodejs-tutorial-app(SO): -nodejs-tutorial-app(O): > nodejs_tutorial_app@0.1.0 start /hab/srvc/nodejs-tutorial-app -nodejs-tutorial-app(O): > node server.js -nodejs-tutorial-app(O): -nodejs-tutorial-app(O): Running on http://0.0.0.0:8080 -~~~ - -Now refresh, or connect again to the local URL through your web browser. - -![Screen shot of node.js output with new message](/images/nodejs-tutorial-update-output.png) - -Making these configuration changes at startup can be useful when using the same Habitat package in multiple environments without changing the default settings defined in the default.toml file. - -Learn how to make the change permanent by [updating the package itself](/tutorials/getting-started-make-change).