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

Commit

Permalink
Major update to README and documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@cdrage
cdrage committed Feb 29, 2016
1 parent b8f890c commit d0b11ef
Show file tree
Hide file tree
Showing 4 changed files with 433 additions and 49 deletions.
50 changes: 45 additions & 5 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,48 @@ which is hosted in the [Project Atomic Organization](https://github.com/projecta
These are just guidelines, not rules, use your best judgment and feel free to
propose changes to this document in a pull request.

## Initial dev environment

First of all, clone the github repository: `git clone https://github.com/projectatomic/atomicapp`..

### Installing Atomic App locally
Simply run

```
make install
```

If you want to do some changes to the code, I suggest to do:

```
cd atomicapp
export PYTHONPATH=`pwd`:$PYTHONPATH
alias atomicapp="python `pwd`/atomicapp/cli/main.py"
```

### Building for containerized execution
```
docker build -t [TAG] .
```

Use 'docker build' to package up the application and tag the resulting image.

### Fetch and run
```
atomicapp [--dry-run] [-v] [-a answers.conf] fetch|run|stop|genanswers [--provider docker] [--destination DST_PATH] APP|PATH
```

Pulls the application and its dependencies. If the last argument is
existing path, it looks for `Nulecule` file there instead of pulling anything.

* `--provider docker` Use the Docker provider within the Atomic App
* `--destination DST_PATH` Unpack the application into given directory instead of current directory
* `APP` Name of the image containing the application (ex. `projectatomic/apache-centos7-atomicapp`)
* `PATH` Path to a directory with installed (ex. result of `atomicapp fetch...`) app

Action `run` performs `fetch` prior to its own tasks if an `APP` is provided. Otherwise, it will use its respective `PATH`. When `run` is selected, providers' code is invoked and containers are deployed.


## Submitting Issues

* You can create an issue [here](https://github.com/projectatomic/atomicapp/issues/new), include as many details as possible with your report.
Expand All @@ -33,13 +75,11 @@ Before you submit your pull request consider the following guidelines:

* Include documentation that either describe a change to a behavior of atomicapp or the changed capability to an end user of atomicapp.
* Commit your changes using **a descriptive commit message**. If you are fixing an issue please include something like 'this closes issue #xyz'.
* Additionally think about implementing a git hook, as flake8 is part of the [travis-ci tests](https://travis-ci.org/projectatomic/atomicapp) it will help you pass the CI tests.
* Make sure your tests pass! As we use [travis-ci](https://travis-ci.org/projectatomic/atomicapp) with __flake8__ it's recommended to run both commands before submitting a PR.
```shell
$ cat .git/hooks/pre-push
#!/bin/bash
flake8 -v atomicapp
make syntax-check
make test
```
* Push your branch to GitHub:
Expand Down
178 changes: 134 additions & 44 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,86 +1,176 @@
# Atomic App

Atomic App is a reference implementation of the [Nulecule specification](https://github.com/projectatomic/nulecule). It can be used to bootstrap packaged container environments and then run them. Atomic App is designed to be ran within a container.
![](docs/images/logo.png "Project Atomic")

Examples of this tool may be found within the [Nulecule library repo](https://github.com/projectatomic/nulecule/tree/master/examples).
Atomic App is a reference implementation of the [Nulecule](https://github.com/projectatomic/nulecule) specification. Packaged Atomic App containers are "Nuleculized" and each component of the package is a "Nulecule".

## Getting Started
Atomic App is used to bootstrap packaged container environments and run them on multiple container orchestrators. It is designed from the ground-up to be portable and provider pluggable.

Atomic App itself is packaged as a container. End-users typically do not install the software from source. Instead use the `atomicapp` container as the `FROM` line in a Dockerfile and package your application on top. For example:
- __A "packaged installer" for all container-based environments and applications.__ Replace all those bash and Ansible scripts with one container-based deployment tool.

- __Target multiple providers:__ Specify the provider you want the Atomic App to run on. It supports Kubernetes, OpenShift, Mesos+Marathon and Docker.

- __Inherit already packaged containers:__ Create composite applications by referencing other Nulecule-compliant applications. For example, plugging in an alternative well-orchestrated database in another referenced container image.

- __Fetch and run entire environments:__ Use `atomicapp fetch` and `atomicapp run` to run pre-packaged Nuleculized containers.

## Installing Atomic App
From Linux:
```sh
git clone https://github.com/projectatomic/atomicapp && cd atomicapp
make install
```
FROM projectatomic/atomicapp

MAINTAINER Your Name <[email protected]>
_or_

ADD /Nulecule /Dockerfile README.md /application-entity/
ADD /artifacts /application-entity/artifacts
Download a pre-signed .tar.gz from [download.projectatomic.io](https://download.projectatomic.io) / [GitHub](https://github.com/projectatomic/atomicapp/releases):
```sh
export RELEASE=0.4.2
wget https://github.com/projectatomic/atomicapp/releases/download/$RELEASE/atomicapp-$RELEASE.tar.gz
tar -xvf atomicapp-$RELEASE.tar.gz && cd atomicapp-$RELEASE.tar.gz
make install
```

For more information see the [Nulecule getting started guide](https://github.com/projectatomic/nulecule/blob/master/docs/getting-started.md).
## Using Atomic App

## Developers
Prerequisite: Before proceeding, make sure you either have a Kubernetes, OpenShift or Docker environment setup and ready.

First of all, clone the github repository: `git clone https://github.com/projectatomic/atomicapp`.

### Installing Atomic App locally
Simply run
### Getting started

```
make install
```
Atomic App can be used either natively on your OS or ran via the [atomic cli](https://github.com/projectatomic/atomic) command.

If you want to do some changes to the code, I suggest to do:
Detailed instructions on [getting started](docs/start_guide.md) are available. Alternatively, use the quickstart below.

```
cd atomicapp
export PYTHONPATH=`pwd`:$PYTHONPATH
alias atomicapp="python `pwd`/atomicapp/cli/main.py"
```

### Building for containerized execution
```
docker build -t [TAG] .
```
### Quickstart

Use 'docker build' to package up the application and tag the resulting image.
__Running Apache on Docker:__
```sh
▶ sudo atomicapp run projectatomic/helloapache --provider=docker
2016-02-25 16:06:38,298 - [INFO] - main.py - Action/Mode Selected is: run
2016-02-25 16:06:38,299 - [INFO] - base.py - Unpacking image: projectatomic/helloapache to /var/lib/atomicapp/projectatomic-helloapache-7c32c1632a7b
2016-02-25 16:06:41,904 - [INFO] - container.py - Skipping pulling Docker image: projectatomic/helloapache
2016-02-25 16:06:41,904 - [INFO] - container.py - Extracting nulecule data from image: projectatomic/helloapache to /var/lib/atomicapp/projectatomic-helloapache-7c32c1632a7b
20af2e6e33d10d26aa98d6e63c70de5fd55bfe14b9cc782e1312afe441ef7130
2016-02-25 16:06:42,231 - [INFO] - docker.py - Deploying to provider: Docker
5d6938439d50c21251507b26c73f5e65f102f2b99e183002ef2ec21414c4ee78

### Fetch and run
Your application resides in /var/lib/atomicapp/projectatomic-helloapache-7c32c1632a7b
Please use this directory for managing your application

▶ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
5d6938439d50 centos/httpd "/run-httpd.sh" 3 seconds ago Up 1 seconds 0.0.0.0:80->80/tcp default_centos-httpd_ec75a2fe2a50
```
atomicapp [--dry-run] [-v] [-a answers.conf] fetch|run|stop|genanswers [--provider docker] [--destination DST_PATH] APP|PATH

__Runnning Apache on Kubernetes:__
```sh
▶ sudo atomicapp run projectatomic/helloapache --provider=kubernetes
2016-02-25 15:03:04,341 - [INFO] - main.py - Action/Mode Selected is: run
2016-02-25 15:03:04,343 - [INFO] - base.py - Unpacking image: projectatomic/helloapache to /var/lib/atomicapp/projectatomic-helloapache-c0dd79b5e757
2016-02-25 15:03:07,983 - [INFO] - container.py - Skipping pulling Docker image: projectatomic/helloapache
2016-02-25 15:03:07,984 - [INFO] - container.py - Extracting nulecule data from image: projectatomic/helloapache to /var/lib/atomicapp/projectatomic-helloapache-c0dd79b5e757
886e10a3244f982f3302ab9058ab7b377c6f83e2cf63f001e1ba011358d0b471
2016-02-25 15:03:08,332 - [INFO] - kubernetes.py - Using namespace default
2016-02-25 15:03:08,332 - [INFO] - kubernetes.py - trying kubectl at /usr/bin/kubectl
2016-02-25 15:03:08,332 - [INFO] - kubernetes.py - trying kubectl at /usr/local/bin/kubectl
2016-02-25 15:03:08,332 - [INFO] - kubernetes.py - found kubectl at /usr/local/bin/kubectl
2016-02-25 15:03:08,332 - [INFO] - kubernetes.py - Deploying to Kubernetes
...

Your application resides in /var/lib/atomicapp/projectatomic-helloapache-c0dd79b5e757
Please use this directory for managing your application

▶ kubectl get po
NAME READY STATUS RESTARTS AGE
helloapache 1/1 Running 0 2m
k8s-etcd-127.0.0.1 1/1 Running 0 1d
k8s-master-127.0.0.1 4/4 Running 0 1d
k8s-proxy-127.0.0.1 1/1 Running 0 1d
```

Pulls the application and its dependencies. If the last argument is
existing path, it looks for `Nulecule` file there instead of pulling anything.
__Fetch, edit and run Apache on Kubernetes:__
```sh
▶ mkdir ./localdir

* `--provider docker` Use the Docker provider within the Atomic App
* `--destination DST_PATH` Unpack the application into given directory instead of current directory
* `APP` Name of the image containing the application (ex. `projectatomic/apache-centos7-atomicapp`)
* `PATH` Path to a directory with installed (ex. result of `atomicapp fetch...`) app
▶ sudo atomicapp fetch projectatomic/helloapache --destination ./localdir/
2016-02-25 15:35:41,439 - [INFO] - main.py - Action/Mode Selected is: fetch
2016-02-25 15:35:41,440 - [INFO] - base.py - Unpacking image: projectatomic/helloapache to helloapache
2016-02-25 15:35:45,067 - [INFO] - container.py - Skipping pulling Docker image: projectatomic/helloapache
2016-02-25 15:35:45,067 - [INFO] - container.py - Extracting nulecule data from image: projectatomic/helloapache to helloapache
c12d2047fab44f2906b9cbee3ac86c6c6499921ce33a90085e8765491b44f447

Action `run` performs `fetch` prior to its own tasks if an `APP` is provided. Otherwise, it will use its respective `PATH`. When `run` is selected, providers' code is invoked and containers are deployed.
Your application resides in localdir
Please use this directory for managing your application

## Providers
▶ cd localdir

Providers represent various deployment targets. They can be added by placing the artifact within the respective in `provider/` folder. For example, placing `deploy_pod.yml` within `providers/kubernetes/`. For a detailed description of all providers available see [docs/providers.md](docs/providers.md).
▶ cat Nulecule
...
- name: hostport
description: The host TCP port as the external endpoint
default: 80
...

## Dependencies
▶ vim Nulecule

See [REQUIREMENTS](https://github.com/projectatomic/atomicapp/blob/master/docs/requirements.md) for current Atomic App dependencies.
▶ cat Nulecule
...
- name: hostport
description: The host TCP port as the external endpoint
default: 8080
...

##Communication channels
▶ sudo atomicapp run . --provider=kubernetes
...

* IRC: #nulecule (On Freenode)
* Mailing List: [[email protected]](https://www.redhat.com/mailman/listinfo/container-tools)
▶ # or

# The Badges
▶ docker build -t myapp
...
▶ sudo atomicapp run --provider=kubernetes myapp
...
```

## Real-world examples
Atomic App can be used to launch a cluster of containers (application servers, databases, etc.).

For a list of already packaged examples, visit the [nulecule-library](https://github.com/projectatomic/nulecule-library) repo.

## Contributing to Atomic App
[![Code Health](https://landscape.io/github/projectatomic/atomicapp/master/landscape.svg?style=flat)](https://landscape.io/github/projectatomic/atomicapp/master)
[![Build Status](https://travis-ci.org/projectatomic/atomicapp.svg?branch=master)](https://travis-ci.org/projectatomic/atomicapp)
[![Coverage Status](https://coveralls.io/repos/projectatomic/atomicapp/badge.svg?branch=master&service=github)](https://coveralls.io/github/projectatomic/atomicapp?branch=master)
[![Issue Stats](http://issuestats.com/github/projectatomic/atomicapp/badge/pr)](http://issuestats.com/github/projectatomic/atomicapp)
[![Issue Stats](http://issuestats.com/github/projectatomic/atomicapp/badge/issue)](http://issuestats.com/github/projectatomic/atomicapp)

First of all, awesome! We have [a development guide to help you get started!](CONTRIBUTING.md)

If you have any issues or get stuck, feel free to open a GitHub issue or reach us at our communication channels (see below).

## Providers

We currently support:

- Docker
- Kubernetes
- OpenShift 3
- Marathon (Mesos)

Providers represent various deployment targets. They can be added by placing the artifact within the respective in `provider/` folder. For example, placing `deploy_pod.yml` within `providers/kubernetes/`.

For a detailed description of all providers available see [docs/providers.md](docs/providers.md).

## Dependencies

See [REQUIREMENTS.md](docs/requirements.md) for a list of current Atomic App dependencies.

##Communication channels

* IRC: __#nulecule__ on irc.freenode.net
* Mailing List: [[email protected]](https://www.redhat.com/mailman/listinfo/container-tools)

# Copyright

Copyright (C) 2016 Red Hat Inc.
Expand Down
Binary file added docs/images/logo.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading

0 comments on commit d0b11ef

Please sign in to comment.