Changes to MySQL image for style and readability

openshift_images/mysql.adoc

@@ -10,97 +10,189 @@
 toc::[]
 
 == Overview
-The OpenShift MySQL database image https://github.com/openshift/mysql[repository] contains the sources and Dockerfiles for building MySQL database images. The resulting images can be run by Docker.
+The OpenShift MySQL database image
+https://github.com/openshift/mysql[repository] contains the sources and
+Dockerfiles for building MySQL database images. The resulting images can be run
+by Docker.
 
 == Versions
-Currently supported versions of MySQL:
-
-* https://github.com/openshift/mysql/tree/master/5.5[5.5]
+Currently, OpenShift only supports version https://github.com/openshift/mysql/tree/master/5.5[5.5] of MySQL.
 
 == Base Images
 
+The following base images are currently available:
+
 * RHEL-7
 * CentOS-7
 
 [NOTE]
 ====
-RHEL-7 image is not available at https://registry.hub.docker.com/[Docker Hub]. In order to perform build action on a RHEL-7 based MySQL image, you need to run the build on properly subscribed RHEL-7 machine.
+A RHEL-7 image is not available at https://registry.hub.docker.com/[Docker Hub].
+In order to perform a build action on a RHEL-7 based MySQL image, you need to
+run the build on a properly subscribed RHEL-7 machine.
 ====
 
 == Installation
-To build MySQL image, choose between the CentOS7 or RHEL7 base image:
+To build a MySQL image, use one of the following procedures, depending on your
+base image.
+
+*RHEL-7 Base Image*
+
+To build a RHEL-7 based MySQL image:
+
+. Clone the following repository:
++
+****
+`$ git clone https://github.com/openshift/mysql.git`
+****
+. Navigate into the directory you just created:
++
+****
+`$ cd mysql`
+****
+. Build the image:
++
+****
+`$ make build TARGET=rhel7 VERSION=5.5`
+****
+
+*CentOS-7 Base Image*
+
+This image is available on DockerHub. To download it:
+
+****
+`$ docker pull openshift/mysql-55-centos7`
+****
+
+Alternatively, you can build a CentOS-7 based MySQL image:
+
+. Clone the following repository:
++
+****
+`$ git clone https://github.com/openshift/mysql.git`
+****
+. Navigate into the directory you just created:
++
+****
+`$ cd mysql`
+****
+. Build the image:
++
+****
+`$ make build VERSION=5.5`
+****
+
+[NOTE]
+====
+If you omit the `*VERSION*` parameter, then the build action is performed on all
+the supported versions of MySQL. Currently, only version 5.5 is supported, so
+you can omit this parameter.
+====
 
-=== RHEL-7 base image
+== Creating a Container
+To create a container running MySQL, you must run one of following commands,
+depending on your base image.
 
-----
-$ git clone https://github.com/openshift/mysql.git
-$ cd mysql
-$ make build TARGET=rhel7 VERSION=5.5
-----
+*RHEL-7 Base Image*
 
-=== CentOS-7 base image
+To create a container running MySQL with a RHEL-7 base image:
+****
+`$ docker run -d --name _<mysql_database>_ -e MYSQL_USER=_<user>_ -e MYSQL_PASSWORD=_<pass>_ -e MYSQL_DATABASE=_<db>_ -p 3306:3306 openshift/mysql-55-rhel7`
+****
 
-----
-$ git clone https://github.com/openshift/mysql.git
-$ cd mysql
-$ make build VERSION=5.5
-----
+This creates a container named with the credentials and database that you
+specified.
 
-[NOTE]
-====
-By omitting the `VERSION` parameter, the build action will be performed on all the supported versions of MySQL. Since we are now supporting only version `5.5`, you can omit this parameter.
-====
+*CentOS-7 Base Image*
+
+To create a container running MySQL with a CentOS-7 base image:
 
-== Usage
-To create a container running MySQL, you need to run following commands.
+****
+`$ docker run -d --name _<mysql_database>_ -e MYSQL_USER=_<user>_ -e MYSQL_PASSWORD=_<password>_ -e MYSQL_DATABASE=_<db>_ -p 3306:3306 openshift/mysql-55-centos7`
+****
 
-=== RHEL-7 image
+This creates a container named with the credentials and database that you
+specified.
 
-----
-$ docker run -d --name mysql_database -e MYSQL_USER=user -e MYSQL_PASSWORD=pass -e MYSQL_DATABASE=db -p 3306:3306 openshift/mysql-55-rhel7
-----
+== Testing
 
-=== CentOS-7 image
+To access and test if the application is running:
 
-----
-$ docker run -d --name mysql_database -e MYSQL_USER=user -e MYSQL_PASSWORD=pass -e MYSQL_DATABASE=db -p 3306:3306 openshift/mysql-55-centos7
-----
+****
+`$ mysql -h 127.0.0.1 --user=_<user>_ --password=_<password>_ <<< "SELECT 1;"`
+****
 
-This will create a container named `mysql_database`, with credentials `user:pass` and database `db`. To access and test if the application is running, run:
-----
-$ mysql -h 127.0.0.1 -uuser -ppass <<< "SELECT 1;"
-----
+== Stopping the Container
 
 To properly stop the container:
-----
-$ docker stop mysql_database
-----
+
+****
+`$ docker stop _<mysql_database>_`
+****
 
 == Environment variables
 
-* *MYSQL_USER* - This variable specifies username for database user that
-    will be created for your application to use.
+The image recognizes the following environment variables that you can set
+during initialization with this command:
 
-* *MYSQL_PASSWORD* - Password for the *MYSQL_USER*.
+****
+`$ docker run -e VAR=_<variable>_`
+****
 
-* *MYSQL_DATABASE* - Name of the database that will be created. *MYSQL_USER*
-    will have full rights to the database.
+.MySQL Environment Variables
+[cols="4a,6a",options="header"]
+|===
 
-* *MYSQL_ROOT_PASSWORD* - Password for the root user. This variable is optional. If not set, remote login to the root account will not be possible. Local connections from inside the container are always allowed without a password.
+|Variable name |Description
 
-== Volumes
+|`*MYSQL_USER*`
+|Specifies the username for the database user that is created for use by your
+application.
+
+|`*MYSQL_PASSWORD*`
+|Password for the `*MYSQL_USER*`.
+
+|`*MYSQL_DATABASE*`
+|Name of the database to which `*MYSQL_USER*` has full rights.
+
+|`*MYSQL_ROOT_PASSWORD*`
+|Optional password for the root user. If this is not set, then remote login to
+the root account is not possible. Local connections from within the container
+are always permitted without a password.
+|===
 
-* */var/lib/mysql/data* - This is the data directory where MySQL stores database files.
+=== Settings
 
-== Settings
-MySQL settings can be configured by additional environment variables.
+MySQL settings can be configured with the following environment variables:
 
-* *MYSQL_LOWER_CASE_TABLE_NAMES* - Sets how the table names are stored and compared
+.Additional MySQL Settings
+[cols="3a,6a,1a",options="header"]
+|===
 
-* *MYSQL_MAX_CONNECTIONS* - The maximum permitted number of simultaneous client connections
+|Variable name |Description |Default
 
-* *MYSQL_FT_MIN_WORD_LEN* - The minimum length of the word to be included in a FULLTEXT index
+|`*MYSQL_LOWER_CASE_TABLE_NAMES*`
+|Sets how the table names are stored and compared.
+|0
 
-* *MYSQL_FT_MAX_WORD_LEN* - The maximum length of the word to be included in a FULLTEXT index
+|`*MYSQL_MAX_CONNECTIONS*`
+|The maximum permitted number of simultaneous client connections.
+|151
+
+|`*MYSQL_FT_MIN_WORD_LEN*`
+|The minimum length of the word to be included in a FULLTEXT index.
+|4
+
+|`*MYSQL_FT_MAX_WORD_LEN*`
+|The maximum length of the word to be included in a FULLTEXT index.
+|20
+
+|`*MYSQL_AIO*`
+|Controls the *innodb_use_native_aio* setting value if the native AIO is broken.
+|1
+|===
+
+== Volumes
 
-* *MYSQL_AIO* - Controls the *innodb_use_native_aio* setting value in case the native AIO is broken. See http://help.directadmin.com/item.php?id=529
+* *_/var/lib/mysql/data_* - This is the data directory where MySQL stores
+database files.