@@ -1,4 +1,11 @@

+# Building an ISO from the Source Code for Photon OS

+

+This document describes how to build an ISO from the source code for Photon OS, the open-source minimalist Linux operating system from VMware that is optimized for cloud computing platforms, VMware vSphere deployments, and applications native to the cloud. 

+

 ## Folder Layout

+

+Here is the structure of the directories on GitHub that contain the source code for Photon OS:

+

 ```

 photon/

 ├── Makefile

@@ -6,42 +13,46 @@ photon/

 ├── Dockerfile

 ├── Vagrantfile

 ├── SPECS        # RPM SPEC files

-├── common       # Build, Packaging config

+├── common       # Build, packaging config

 ├── docs         # Documentation

 ├── installer    # Installer used at runtime

 ├── support      # Build scripts

 └── tools

 ```

-## How to build the ISO?

+## How to Build the ISO

+

+The following process for building the ISO assumes that the following prerequisites are in place:

-Pre-requisites :

+* A build operating system running the 64-bit version of Ubuntu 14.04 or later

+* Packages: bison, gawk, g++, createrepo, python-aptdaemon, genisoimage, texinfo, python-requests

+* Docker

+* Downloaded the source code from the Photon OS repository on GitHub into `$HOME/workspaces/photon`.

+

+Here's how to install the packages on Ubuntu: 

- * Build O/S : Ubuntu 14.04 (or later) 64 bit

- * Packages: bison, gawk, g++, createrepo, python-aptdaemon, genisoimage, texinfo, python-requests

 ```

 sudo apt-get -y install bison gawk g++ createrepo python-aptdaemon genisoimage texinfo python-requests

 ```

- * Docker:

+Here's how to get Docker:

 ```

 wget -qO- https://get.docker.com/ | sh

 ```

-Make sure `/bin/sh` is a symbolic link pointing to `/bin/bash`

-

-If `/bin/sh` is pointing `/bin/dash`, execute the following:

+Make sure `/bin/sh` is a symbolic link pointing to `/bin/bash`. If `/bin/sh` is pointing `/bin/dash`, execute the following:

 ```

 sudo ln -sf /bin/bash /bin/sh

 ```

-Assuming you checked out the workspace under `$HOME/workspaces/photon`.

+Here's how to make the ISO, assuming you checked out the workspace under `$HOME/workspaces/photon`:

 ```

 cd $HOME/workspaces/photon

 sudo make iso

 ```

-Deliverable will be created at `$HOME/workspaces/photon/stage/photon.iso`

+The ISO is created at `$HOME/workspaces/photon/stage/photon.iso`

+

-## How to use cached toolchain and RPMS?

+## How to Use the Cached Toolchain and RPMS

 ```

 mkdir $HOME/photon-cache

 sudo make iso PHOTON_CACHE_PATH=$HOME/photon-cache

@@ -53,7 +64,7 @@ photon-cache/

 ├──RPMS/x86-64/*.rpm

 └──RPMX/noarch/*.rpm

 ```

-## How to use cached sources?

+## How to Use Cached Sources

 ```

 mkdir $HOME/photon-sources

 sudo make iso PHOTON_SOURCES_PATH=$HOME/photon-sources

@@ -66,16 +77,20 @@ photon-sources/

 └──...

 ```

-## Where are the build logs?

+## Where are the Build Logs?

 ```

 $HOME/workspaces/photon/stage/LOGS

 ```

-## Complete build environment using Vagrant

-A `Vagrantfile` is available to ensure a quick standup of a development/build environment for Photon, this Vagrantfile uses a box called `photon-build-machine` box that is created through a [Packer](http://packer.io) template available under `support/packer-templates`, see the [README.md](https://github.com/vmware/photon/blob/master/support/packer-templates/README.md) for more information on how to build `photon-build-machine`.

+## Building RPMs from their Source RPMs

+

+For instructions on how to install and build a package on Photon OS from the package's source RPM, see the [Photon OS Administration Guide](https://github.com/vmware/photon/blob/master/docs/photon-admin-guide.md#building-a-package-from-a-source-rpm).

+

+## Complete Build Environment Using Vagrant

+A `Vagrantfile` is available to ensure a quick standup of a development or build environment for Photon. This Vagrantfile uses a box called `photon-build-machine` that is created through a [Packer](http://packer.io) template available under `support/packer-templates`; see the [README.md](https://github.com/vmware/photon/blob/master/support/packer-templates/README.md) for more information on how to build `photon-build-machine`.

-## Photon Vagrant box

-As with the build-machine a Packer template is available under `support/packer-templates` to build a Photon based Vagrant box running Docker, see the [README.md](https://github.com/vmware/photon/blob/master/support/packer-templates/README.md) for more information on how to build.

+## Photon Vagrant Box

+As with the build-machine a Packer template is available under `support/packer-templates` to build a Photon based Vagrant box running Docker, see the [README.md](https://github.com/vmware/photon/blob/master/support/packer-templates/README.md) for more information on how to build it. 

-## Automated build environment and Vagrant boxes

-Convenience make targets also exist to build both the `photon-build-machine` and the `photon` Packer templates as well as building a fresh ISO using the `photon-build-machine`. See the [README.md](https://github.com/vmware/photon/blob/master/support/packer-templates/README.md) for more details.

+## Automated Build Environment and Vagrant Boxes

+Convenience `make` targets also exist to build both the `photon-build-machine` and the `photon` Packer templates as well as building a fresh ISO using the `photon-build-machine`. See the [README.md](https://github.com/vmware/photon/blob/master/support/packer-templates/README.md) for details.

@@ -1,4 +1,4 @@

-# Photon Administration Guide

+# Photon OS Administration Guide

 -   [Introduction](#introduction)

     -   [Examining the Packages in the SPECS Directory on

@@ -80,9 +80,11 @@

 ## Introduction

-This guide covers managing packages, controlling services with systemd, setting up networking, initializing Photon OS with cloud-init, running Docker containers, and working with other technologies, such as Kubernetes. 

+This guide describes the fundamentals of administering Photon OS, the free, open-source minimalist Linux operating system from VMware that is optimized for cloud computing platforms, VMware vSphere deployments, and applications native to the cloud. 

-Photon OS is a Linux container host optimized for vSphere and cloud-computing platforms such as Amazon Elastic Compute and Google Compute Engine. Photon OS is lightweight and extensible. It supports the most common container formats, including Docker, Rocket, and Garden. Photon OS includes a yum-compatible, package-based lifecycle management system called tdnf and optionally works with RPM-OSTree for image-based system versioning. 

+The guide covers the basics of managing packages, controlling services with systemd, setting up networking, initializing Photon OS with cloud-init, running Docker containers, and working with other technologies, such as Kubernetes. The guide also includes a section to get you started using Photon OS quickly and easily. 

+

+Photon OS is a Linux container host optimized for vSphere and cloud-computing platforms such as Amazon Elastic Compute and Google Compute Engine. As a lightweight and extensible operating system, Photon OS works with the most common container formats, including Docker, Rocket, and Garden. Photon OS includes a yum-compatible, package-based lifecycle management system called tdnf and optionally works with RPM-OSTree for image-based system versioning. 

 When used with development tools and environments such as VMware Fusion, VMware Workstation, HashiCorp (Vagrant and Atlas), and production runtime environments (vSphere, vCloud Air), Photon OS lets you seamlessly migrate container-based applications from development to production. With a small footprint and fast boot and run times, Photon OS is optimized for cloud computing and cloud  applications.  

@@ -138,13 +140,13 @@ It contains the libraries files for Java runtime environment

 ### Looking at the Differences Between the Minimal and the Full Version

-The minimal version of Photon OS contains about 50 packages. The full version of Photon OS adds several hundred packages to those in the minimal version to create a more fully featured operating system. 

+The minimal version of Photon OS contains about 50 packages. As it is installed, the number of packages increases to nearly 100 to fulfill dependencies. The full version of Photon OS adds several hundred packages to those in the minimal version to deliver a more fully featured operating system. 

 You can view a list of the packages that appear in the minimal version by examining the following file: 

 [https://github.com/vmware/photon/blob/master/common/data/packages_minimal.json](https://github.com/vmware/photon/blob/master/common/data/packages_minimal.json)

-You can view a list of the packages that appear in the minimal version by examining the following file: 

+You can view a list of the packages that appear in the full version by examining the following file: 

 [https://github.com/vmware/photon/blob/master/common/data/packages_full.json](https://github.com/vmware/photon/blob/master/common/data/packages_full.json)

@@ -159,7 +161,7 @@ One notable difference between the two versions of Photon OS pertains to OpenJDK

 A later section covers tdnf. 

-### The Root Account and the sudo and su Commands

+### The Root Account and the `sudo` and `su` Commands

 This guide assumes that you are logged in to Photon OS with the root account and running commands as root. The sudo program comes with the full version of Photon OS. On the minimal version, you must install sudo with tdnf if you want to use it. As an alternative to installing sudo on the minimal version, you can switch users as needed with the `su` command to run commands that require root privileges. 

@@ -212,13 +214,13 @@ You can also build an ISO containing Photon OS from its source code on GitHub by

 ### Installing the OVA for the Minimal Version in vSphere

-You can download the OVA for the minimal version of Photon OS from Bintray and deploy it in vSphere in a matter of seconds. 

+You can download the OVA for the minimal version of Photon OS from Bintray and deploy it in vSphere in a matter of seconds. Here's how: 

 Download the OVA for the minimal version of Photon OS from the following URL: 

 	https://bintray.com/vmware/photon/ova

-To install the OVA in vSphere, on the File menu, click Deploy OVF Template, and then click Browse to locate the image that you downloaded. Move through the Deploy OVF Template dialog boxes by clicking Next to accept the default settings, and then click Finish. 

+To install the OVA in vSphere, on the `File` menu, click `Deploy OVF Template`, and then click `Browse` to locate the image that you downloaded. Move through the `Deploy OVF Template` dialog boxes by clicking `Next` to accept the default settings, and then click `Finish`. 

 In vSphere Client, turn on the power of the Photon OS virtual machine and open a console to it.

@@ -288,7 +290,7 @@ AppCatalyst is optimized for cloud-native application workloads. A common use ca

 By bundling Photon OS with AppCatalyst, VMware streamlines the workflow of getting a Docker engine running on a Linux machine inside a hypervisor on a Mac. 

-Here's how to install AppCatalyst, create a VM running Photon OS, and run a Docker container---all in a matter of minutes. The technology preview version of AppCatalyst requires Mac OS X 10.9 or later.

+Here's how to install AppCatalyst, create a VM running Photon OS, and run a Docker container--all in a matter of minutes. The technology preview version of AppCatalyst requires Mac OS X 10.9 or later.

 First, turn off Fusion if you are running it on your Mac. 

@@ -708,7 +710,7 @@ After establishing a new repository, you must run the following command to updat

 ## Managing Services with systemd

-Photon OS manages services with systemd. By using systemd, Photon OS adopts a contemporary Linux standard to bootstrap the user space and concurrently start services---an architecture that differs from traditional Linux systems such as SUSE Linux Enterprise Server. 

+Photon OS manages services with systemd. By using systemd, Photon OS adopts a contemporary Linux standard to bootstrap the user space and concurrently start services--an architecture that differs from traditional Linux systems such as SUSE Linux Enterprise Server. 

 A traditional Linux system contains an initialization system called SysVinit. With SLES 11, for instance, SysVinit-style init programs control how the system starts up and shuts down. Init implements system runlevels. A SysVinit runlevel defines a state in which a  process or service runs. 

@@ -1000,7 +1002,7 @@ To add a DNS server to your static network configuration file, insert a DNS key

 	Gateway=192.168.0.1

 	DNS=192.168.0.1

-Another way of adding a DNS server is to modify /etc/systemd/resolved.conf --- a method that can be particularly useful when your machine is working with DHCP. For more information, see https://www.freedesktop.org/software/systemd/man/resolved.conf.html.

+Another way of adding a DNS server is to modify /etc/systemd/resolved.conf--a method that can be particularly useful when your machine is working with DHCP. For more information, see https://www.freedesktop.org/software/systemd/man/resolved.conf.html.

 You can optionally activate the local DNS stub resolver of systemd-resolved by adding `dns` and `resolve` to /etc/nsswitch.conf. To do so, make a backup copy of /etc/nsswitch.conf and then execute the following command as root:

@@ -1374,7 +1376,7 @@ You can also add a cloud-init user-data file to an existing instance of a Photon

 ## Docker Containers

-Photon OS includes the open source version of Docker. With Docker, Photon OS becomes a Linux run-time host for containers---that is, a Linux cloud container. A container is a process that runs on the Photon OS host with its own isolated application, file system, and networking.

+Photon OS includes the open source version of Docker. With Docker, Photon OS becomes a Linux run-time host for containers--that is, a Linux cloud container. A container is a process that runs on the Photon OS host with its own isolated application, file system, and networking.

 On Photon OS, the Docker daemon is enabled by default. To view the status of the daemon, run this command: 

@@ -1468,7 +1470,7 @@ To build a package from its source RPM, or SRPM, Photon OS requires the followin

 * gcc. This package is also installed by default on the full version of Photon OS, so you should not have to install it. 

 * make, Cmake, automake, or another make package, depending on the package you are trying to install and build from its source RPM. Cmake is installed by default on Photon OS. You can install other make packages if need be by using tdnf or yum.  

-Another requirement is a local unprivileged user account other than the root account. You should build RPMs as an unprivileged user. Do not build a package as root---building an RPM with the root account might damage your system. 

+Another requirement is a local unprivileged user account other than the root account. You should build RPMs as an unprivileged user. Do not build a package as root--building an RPM with the root account might damage your system. 

 If you are building a package on a virtual machine running Photon OS in VMware vSphere, VMware Workstation, or VMware Fusion, take a snapshot of your virtual machine before building the package.