Skip to content
This repository was archived by the owner on Jan 19, 2018. It is now read-only.

[ROUGH DRAFT] Reorganize docs into a single folder and clean up spec description #209

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

[ROUGH DRAFT] Reorganize docs into a single folder and clean up spec description #209

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
0 docs/getting-started.md → GETTING_STARTED.md
View file
Open in desktop
File renamed without changes.
0 docs/glossary.md → GLOSSARY.md
View file
Open in desktop
File renamed without changes.
0 docs/implementation_guide.md → IMPLEMENTATION_GUIDE.md
View file
Open in desktop
File renamed without changes.
107 changes: 36 additions & 71 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,10 @@ The Nulecule specification enables complex applications to be defined, packaged

**[Glossary of terms](docs/glossary.md)**

## Specification

An actively maintained page on the specifics of the specification can be found at [SPECIFICATION.md](SPECIFICATION.md).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe s/specifics/details/ "specifics of the specification" sounds funny :)


## Nulecule Specification Highlights

* Application description and context maintained in a single container through extensible metadata
Expand All @@ -36,90 +40,51 @@ The Nulecule specification enables complex applications to be defined, packaged

## Deployment User Experience

The Nulecule specification has been implemented in the [Atomic App reference implementation](https://github.com/projectatomic/atomicapp). Atomic App currently supports docker containers and kubernetes and docker orchestration providers. The [atomic command](https://github.com/projectatomic/atomic) is used to run the container that contains the Nulecule specification and the Atomic App implementation.

This example is a single container application based on the centos/httpd image, but you can use your own.

You may wish to run the Nulecule from an empty directory as it will copy the Nulecule files to the working directory for inspection every time it is run.

### Option 1: Non-interactive defaults

Run the image. It will automatically use kubernetes as the orchestration provider. This will become interactive and prompt for defaults if the Nulecule file doesn't provide defaults for all of the parameters.

```
[sudo] atomic run projectatomic/helloapache
```

### Option 2: Unattended

1. Create the file `answers.conf` with these contents:

This sets up the values for the two configurable parameters (image and hostport) and indicates that kubernetes should be the orchestration provider.

[general]
provider = kubernetes

[helloapache-app]
image = centos/httpd # optional: choose a different image
hostport = 80 # optional: choose a different port to expose
1. Run the application from the current working directory

$ [sudo] atomic run projectatomic/helloapache
...
helloapache
The Nulecule specification has been implemented in the [Atomic App reference implementation](https://github.com/projectatomic/atomicapp). Atomic App currently supports docker as well as container orchestrators such as Kubernetes, OpenShift and Marathon. The [atomic](https://github.com/projectatomic/atomic) or [atomicapp](https://github.com/projectatomic/atomicapp] command is used to run the container that contains the Nulecule specification.
Copy link
Contributor

@dustymabe dustymabe Jul 6, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the 3rd hyperlink is messed up there is an extra ] in there

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's not call atomic app a "reference" implementation. Let's just refer to it as an implementation

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/command is/commands can be/


## Getting started on Nulecule with Atomic App

1. As an additional experiment, remove the kubernetes pod and change the provider to 'docker' and re-run the application to see it get deployed on native docker.
Nulecule can use the Atomic App implementation which can be used either natively on your OS __or__ ran via the [atomic](https://github.com/projectatomic/atomic) command on [Fedora or CentOS Atomic hosts](https://www.projectatomic.io/download/).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It just so happens that Atomic CLI is installed by default on Atomic hosts but the user can install atomic CLI on any host. Might be worth changing the wording so that it isn't misleading.


### Option 3: Install and Run
__Detailed instructions on [getting started](https://github.com/projectatomic/atomicapp/blob/master/docs/start_guide.md) are available.__ Alternatively, use the [quick start guide](https://github.com/projectatomic/atomicapp/blob/master/docs/quick_start.md) to get a Nuleculized application running immediately.

You may want to download the application, review the configuration and parameters as specified in the Nulecule file, and edit the answerfile before running the application.

1. Download the application files using `atomic install`

[sudo] atomic install projectatomic/helloapache

1. Rename `answers.conf.sample`

mv answers.conf.sample answers.conf

1. Edit `answers.conf`, review files if desired and then run

$ [sudo] atomic run projectatomic/helloapache
...
helloapache

## Test
Any of these approaches should create a kubernetes pod or a running docker container.

With a kubernetes pod, once its state is "Running" curl the minion it's running on.

```
$ kubectl get pod helloapache
POD IP CONTAINER(S) IMAGE(S) HOST LABELS STATUS
helloapache 172.17.0.8 helloapache centos/httpd 10.3.9.216/ name=helloapache Running
$ curl 10.3.9.216
<bunches_of_html_goodness>
```

If you test the docker provider, once the container is running, curl the port on your localhost.
This example is a single container application based on the centos/httpd image, but you can use your own.

A quick example of this being used are launching the `projectatomic/helloapache` example:

```bash
▶ sudo atomicapp run projectatomic/helloapache --destination helloapache
INFO :: Atomic App: 0.5.2 - Mode: Run
INFO :: Unpacking image projectatomic/helloapache to helloapache
INFO :: Skipping pulling docker image: projectatomic/helloapache
INFO :: Extracting Nulecule data from image projectatomic/helloapache to helloapache
INFO :: App exists locally and no update requested
INFO :: Using namespace default
INFO :: trying kubectl at /usr/bin/kubectl
INFO :: trying kubectl at /usr/local/bin/kubectl
INFO :: found kubectl at /usr/local/bin/kubectl
INFO :: Deploying to Kubernetes

Your application resides in helloapache
Please use this directory for managing your application

▶ kubectl get po
NAME READY STATUS RESTARTS AGE
helloapache 1/1 Running 0 6s
k8s-etcd-127.0.0.1 1/1 Running 0 20d
k8s-master-127.0.0.1 4/4 Running 0 23h
k8s-proxy-127.0.0.1 1/1 Running 0 23h
```
$ curl localhost
<bunches_of_html_goodness>
```

Additional examples are available in the [examples](examples/) directory.

## Developer User Experience

See the [Getting Started with Nulecule guide](docs/getting-started.md).
See the [Getting Started with Nulecule guide](GETTING_STARTED.md).

## Implementations

This is only a specification. Implementations may be written in any language. See [implementation guide](/docs/implementation_guide.md) for more details.
This is only a specification. Implementations may be written in any language. See [implementation guide](IMPLEMENTATION_GUIDE.md) for more details.

**Reference implementation** https://github.com/projectatomic/atomicapp
**Reference implementation:** https://github.com/projectatomic/atomicapp
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Still would rather not use the words "reference implementation" here. Let's just list Atomic App as an implementation, but not the reference implementation.


## Examples / Library

Expand Down
Loading