diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index 3abaf1b403eb..888d1656ef7a 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -5,7 +5,12 @@ OpenShift Developers :toc2: :sectanchors: -The OpenShift architecture builds upon the flexibility and scalability of https://docker.com/[Docker] and https://github.com/kubernetes/kubernetes[Kubernetes] to deliver a powerful new https://www.youtube.com/watch?v=aZ40GobvA1c[Platform-as-a-Service] system. This article explains how to set up a development environment and get involved with this latest version of OpenShift. Kubernetes is included in this repo for ease of development, and the version we include is periodically updated. +The OpenShift architecture builds upon the flexibility and scalability of +https://docker.com/[Docker] and https://github.com/kubernetes/kubernetes[Kubernetes] +to deliver a powerful new https://www.youtube.com/watch?v=aZ40GobvA1c[Platform-as-a-Service] +system. This article explains how to set up a development environment and get +involved with this latest version of OpenShift. Kubernetes is included in this +repo for ease of development, and the version we include is periodically updated. To get started you can either: @@ -20,30 +25,44 @@ Or if you are interested in development, start with: == Download from GitHub -The OpenShift team periodically publishes binaries to GitHub on https://github.com/openshift/origin/releases[the Releases page]. These are Linux, Windows, or Mac OS X 64bit binaries (note that Mac and Windows are client only). You'll need Docker installed on your local system (see https://docs.docker.com/installation/[the installation page] if you've never installed Docker before). +The OpenShift team periodically publishes binaries to GitHub on +https://github.com/openshift/origin/releases[the Releases page]. These are +Linux, Windows, or Mac OS X 64bit binaries (note that Mac and Windows are +client only). You'll need Docker installed on your local system +(see https://docs.docker.com/installation/[the installation page] if you've +never installed Docker before). -The tar file for each platform contains a single binary `openshift` which is the all-in-one OpenShift installation. +The tar file for each platform contains a single binary `openshift` which is +the all-in-one OpenShift installation. -* Use `sudo openshift start` to launch the server. Root access is required to create services due to the need to modify IPTables. See issue: https://github.com/kubernetes/kubernetes/issues/1859. +* Use `sudo openshift start` to launch the server. Root access is required to + create services due to the need to modify IPTables. + See issue: https://github.com/kubernetes/kubernetes/issues/1859. * Use `oc login ...` to connect to an OpenShift server * Use `openshift help` to see more about the commands in the binary == OpenShift Development -To get started, https://help.github.com/articles/fork-a-repo[fork] the https://github.com/openshift/origin[origin repo]. +To get started, https://help.github.com/articles/fork-a-repo[fork] the +https://github.com/openshift/origin[origin repo]. === Develop locally on your host -You can develop OpenShift 3 on Windows, Mac, or Linux, but you'll need Docker installed on Linux to actually launch containers. +You can develop OpenShift 3 on Windows, Mac, or Linux, but you'll need Docker +installed on Linux to actually launch containers. -* For OpenShift 3 development, install the http://golang.org/[Go] programming language +* For OpenShift 3 development, install the http://golang.org/[Go] programming + language * To launch containers, install the https://docker.com/[Docker] platform Here's how to get set up: -1. For Go, Git and optionally also Docker, follow the links below to get to installation information for these tools: + -** http://golang.org/doc/install[Installing Go]. Currently, OpenShift supports building using Go 1.7.x. Do NOT use $HOME/go for Go installation, save that for the Go workspace below. +1. For Go, Git and optionally also Docker, follow the links below to get to + installation information for these tools: + +** http://golang.org/doc/install[Installing Go]. Currently, OpenShift supports + building using Go 1.7.x. Do NOT use $HOME/go for Go installation, save that + for the Go workspace below. ** http://git-scm.com/book/en/v2/Getting-Started-Installing-Git[Installing Git] ** https://docs.docker.com/installation/[Installing Docker] + @@ -62,7 +81,8 @@ export GOPATH=$HOME/go export PATH=$PATH:$GOPATH/bin export OS_OUTPUT_GOPATH=1 ---- -4. Open up a new terminal or source the changes in your current terminal. Then clone this repo: +4. Open up a new terminal or source the changes in your current terminal. Then + clone this repo: $ mkdir -p $GOPATH/src/github.com/openshift $ cd $GOPATH/src/github.com/openshift @@ -74,20 +94,30 @@ export OS_OUTPUT_GOPATH=1 $ make clean build -6. Next, assuming you have not changed the kubernetes/openshift service subnet configuration from the default value of 172.30.0.0/16, you need to instruct the Docker daemon to trust any Docker registry on the 172.30.0.0/16 subnet. If you are running Docker as a service via `systemd`, add the `--insecure-registry 172.30.0.0/16` argument to the options value in `/etc/sysconfig/docker` and restart the Docker daemon. For more details on controlling Docker options with systemd, please refer https://docs.docker.com/engine/admin/systemd/[here]. - Otherwise, add "--insecure-registry 172.30.0.0/16" to the Docker daemon invocation, for example: +6. Next, assuming you have not changed the kubernetes/openshift service subnet + configuration from the default value of 172.30.0.0/16, you need to instruct + the Docker daemon to trust any Docker registry on the 172.30.0.0/16 subnet. + If you are running Docker as a service via `systemd`, add the + `--insecure-registry 172.30.0.0/16` argument to the options value in + `/etc/sysconfig/docker` and restart the Docker daemon. For more details on + controlling Docker options with systemd, please refer https://docs.docker.com/engine/admin/systemd/[here]. + Otherwise, add "--insecure-registry 172.30.0.0/16" to the Docker daemon + invocation, for example: $ docker daemon --insecure-registry 172.30.0.0/16 -7. Then, the OpenShift firewalld rules are also a work in progress. For now it is easiest to disable firewalld altogether: +7. Then, the OpenShift firewalld rules are also a work in progress. For now it + is easiest to disable firewalld altogether: $ sudo systemctl stop firewalld -8. Firewalld will start again on your next reboot, but you can manually restart it with this command when you are done running OpenShift: +8. Firewalld will start again on your next reboot, but you can manually restart + it with this command when you are done running OpenShift: $ sudo systemctl start firewalld -9. Now change into the directory with the OpenShift binaries, and start the OpenShift server: +9. Now change into the directory with the OpenShift binaries, and start the + OpenShift server: $ cd _output/local/bin/linux/amd64 $ sudo ./openshift start @@ -95,16 +125,21 @@ export OS_OUTPUT_GOPATH=1 + NOTE: Replace "linux/amd64" with the appropriate value for your platform/architecture. -10. Launch another terminal, change into the same directory you started OpenShift, and deploy the private docker registry within OpenShift with the following commands: +10. Launch another terminal, change into the same directory you started + OpenShift, and deploy the private docker registry within OpenShift + with the following commands: $ sudo chmod +r openshift.local.config/master/admin.kubeconfig $ ./oadm registry -n default --config=openshift.local.config/master/admin.kubeconfig -11. If it is not there already, add the current directory to the $PATH, so you can leverage the OpenShift commands elsewhere. +11. If it is not there already, add the current directory to the $PATH, so you + can leverage the OpenShift commands elsewhere. -12. You are now ready to edit the source, rebuild and restart OpenShift to test your changes. +12. You are now ready to edit the source, rebuild and restart OpenShift to + test your changes. -13. NOTE: to properly stop OpenShift and clean up, so that you can start fresh instance of OpenShift, execute: +13. NOTE: to properly stop OpenShift and clean up, so that you can start + fresh instance of OpenShift, execute: $ sudo pkill -x openshift $ docker ps | awk 'index($NF,"k8s_")==1 { print $1 }' | xargs -l -r docker stop