diff --git a/README.md b/README.md index 317d099..d44a1c6 100644 --- a/README.md +++ b/README.md @@ -1,95 +1,75 @@ # Deis Minio v2 -[![Build Status](https://travis-ci.org/deis/minio.svg?branch=master)](https://travis-ci.org/deis/minio) [![Go Report Card](http://goreportcard.com/badge/deis/minio)](http://goreportcard.com/report/deis/minio) [![Docker Repository on Quay](https://quay.io/repository/deisci/minio/status "Docker Repository on Quay")](https://quay.io/repository/deisci/minio) +[![Build Status](https://travis-ci.org/deis/minio.svg?branch=master)](https://travis-ci.org/deis/minio) +[![Go Report Card](http://goreportcard.com/badge/deis/minio)](http://goreportcard.com/report/deis/minio) +[![Docker Repository on Quay](https://quay.io/repository/deisci/minio/status "Docker Repository on Quay")](https://quay.io/repository/deisci/minio) -Deis (pronounced DAY-iss) is an open source PaaS that makes it easy to deploy and manage -applications on your own servers. Deis builds on [Kubernetes](http://kubernetes.io/) to provide -a lightweight, [Heroku-inspired](http://heroku.com) workflow. +Deis (pronounced DAY-iss) Workflow is an open source Platform as a Service (PaaS) that adds a developer-friendly layer to any [Kubernetes](http://kubernetes.io) cluster, making it easy to deploy and manage applications on your own servers. -## Work in Progress +For more information about the Deis workflow, please visit the main project page at https://github.com/deis/workflow. -![Deis Graphic](https://s3-us-west-2.amazonaws.com/get-deis/deis-graphic-small.png) +## Beta Status -Deis Minio v2 is changing quickly. Your feedback and participation are more than welcome, but be -aware that this project is considered a work in progress. +This Deis component is currently in beta status, and we welcome your input! If you have feedback, please submit an [issue][issues]. If you'd like to participate in development, please read the "Development" section below and submit a [pull request][prs]. # About -This package provides a [Minio](http://minio.io) S3-compatible object storage system on Kubernetes. It can be used as a [Deis](https://deis.com/) component to provide object storage for various other components, but it is flexible enough to be run anywhere else. +The Deis minio component provides an [S3 API][s3-api] compatible object storage server, based on [Minio](http://minio.io), that can be run on Kubernetes. It's intended for use within the [Deis v2 platform](http://docs-v2.readthedocs.org/en/latest/) as an object storage server, but it's flexible enough to be run as a standalone pod on any Kubernetes cluster. -We provide it as a Docker container, and also provide the following manifests to run it inside [Kubernetes](http://kubernetes.io/): +Note that in the default [Helm chart for the Deis platform](https://github.com/deis/charts/tree/master/deis-dev), this component is used as a storage location for the following components: -- A [replication controller](http://kubernetes.io/v1.1/docs/user-guide/replication-controller.html) to run a server on a single pod -- A [service](http://kubernetes.io/v1.1/docs/user-guide/services.html) to run in front of the replication controller -- [Secret](http://kubernetes.io/v1.1/docs/user-guide/secrets.html)s for: - - User credentials - - Admin credentials - - SSL (note that the current version does not run with SSL enabled, however) +- [deis/postgres](https://github.com/deis/postgres) +- [deis/registry](https://github.com/deis/registry) +- [deis/builder](https://github.com/deis/builder) -Note: this component currently does not offer persistent storage from the Docker container. +Also note that we aren't currently providing this component with any kind of persistent storage, but it may work with [persistent volumes](http://kubernetes.io/docs/user-guide/volumes/). -# Hacking Minio +# Development -First, install [helm](http://helm.sh) and [boot up a kubernetes cluster][install-k8s]. Next, add the -`deis` repository to your chart list: +The Deis project welcomes contributions from all developers. The high level process for development matches many other open source projects. See below for an outline. -```console -$ helm repo add deis https://github.com/deis/charts -``` +* Fork this repository +* Make your changes +* Submit a [pull request][prs] (PR) to this repository with your changes, and unit tests whenever possible. +* If your PR fixes any [issues][issues], make sure you write Fixes #1234 in your PR description (where #1234 is the number of the issue you're closing) +* The Deis core contributors will review your code. After each of them sign off on your code, they'll label your PR with `LGTM1` and `LGTM2` (respectively). Once that happens, you may merge. -Then, install the Deis chart! +## Docker Based Development Environment -```console -$ helm install deis/deis -``` +The preferred environment for development uses the [`go-dev` Docker image](https://github.com/deis/docker-go-dev). The tools described in this section are used to build, test, package and release each version of Deis. -The chart will install the entire Deis platform onto Kubernetes. You can monitor all the pods that it installs by running: +To use it yourself, you must have [make](https://www.gnu.org/software/make/) installed and Docker installed and running on your local development machine. -```console -$ kubectl get pods --namespace=deis -``` +If you don't have Docker installed, please go to https://www.docker.com/ to install it. -Once this is done, SSH into a Kubernetes minion, and run the following: +After you have those dependencies, build your code with `make build` and execute unit tests with `make test`. -``` -$ curl -sSL http://deis.io/deis-cli/install.sh | sh -$ sudo mv deis /bin -$ kubectl get service deis-workflow -$ deis register 10.247.59.157 # or the appropriate CLUSTER_IP -$ ssh-keygen -t rsa -b 4096 -C "your_email@example.com" -$ eval $(ssh-agent) && ssh-add ~/.ssh/id_rsa -$ deis keys:add ~/.ssh/id_rsa.pub -$ deis create --no-remote -Creating Application... done, created madras-radiator -$ deis pull deis/example-go -a madras-radiator -Creating build... ..o -``` +## Native Go Development Environment -If you want to hack on a new feature, re-compile your code, then rebuild the `deis/minio` image and push it to a Docker registry. The `$DEIS_REGISTRY` environment variable must point to a registry accessible to your Kubernetes cluster. If you're using a locally hosted Docker registry, you may need to configure the Docker engines on your Kubernetes nodes to allow `--insecure-registry 192.168.0.0/16` (or the appropriate address range). +You can also use the standard go toolchain to build and test if you prefer. To do so, you'll need [glide](https://github.com/Masterminds/glide) 0.9 or above and [Go](http://golang.org/) 1.6 or above installed. -```console -$ make build docker-push -``` +After you have those dependencies, you can build and unit-test your code with `go build` and `go test $(glide nv)`, respectively. -(note that `docker-push` runs `docker-build` implicitly) +Note that you will not be able to build or push Docker images using this method of development. -Next, you'll want to remove the `deis-minio` [replication controller](http://kubernetes.io/v1.1/docs/user-guide/replication-controller.html) and re-create it to run your new image. -```console -make kube-clean kube-rc -``` +## Testing -## Installation +The Deis project requires that as much code as possible is unit tested, but the core contributors also recognize that some code must be tested at a higher level (functional or integration tests, for example). -The following steps assume that you have the [Docker CLI](https://docs.docker.com/) and [Kubernetes CLI](http://kubernetes.io/v1.1/docs/user-guide/kubectl-overview.html) installed and correctly configured. +The [end-to-end tests](https://github.com/deis/workflow-e2e) repository has our integration tests. Additionally, the core contributors and members of the community also regularly [dogfood](https://en.wikipedia.org/wiki/Eating_your_own_dog_food) the platform. -``` -make deploy kube-service -``` +## Running End-to-End Tests + +Please see [README.md](https://github.com/deis/workflow-e2e/blob/master/README.md) on the end-to-end tests reposotory for instructions on how to set up your testing environment and run the tests. + +## Dogfooding + +Please follow the instructions on the [official Deis docs](http://docs-v2.readthedocs.org/en/latest/installing-workflow/installing-deis-workflow/) to install and configure your Deis cluster and all related tools, and deploy and configure an app on Deis. ## License -Copyright 2013, 2014, 2015 Engine Yard, Inc. +Copyright 2013, 2014, 2015, 2016 Engine Yard, Inc. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at @@ -97,3 +77,6 @@ Unless required by applicable law or agreed to in writing, software distributed [install-k8s]: http://kubernetes.io/gettingstarted/ +[s3-api]: http://docs.aws.amazon.com/AmazonS3/latest/API/APIRest.html +[issues]: https://github.com/deis/minio/issues +[prs]: https://github.com/deis/minio/pulls