From 75f18275c903e628d3f249aa85fbf3da83385a09 Mon Sep 17 00:00:00 2001 From: Bilhar Date: Mon, 13 Oct 2014 17:49:58 +1000 Subject: [PATCH] Added overview topics, and implemented new TOC for each article/topic at top of page. --- .../backing_up_and_restoring_cartridges.adoc | 7 +++++++ .../cartridge_events.adoc | 7 +++++++ .../cartridge_scripts.adoc | 7 +++++++ ...mplate_directories_for_language_cartridges.adoc | 7 +++++++ .../environment_variables.adoc | 7 +++++++ .../exposing_services.adoc | 7 +++++++ .../locking_cartridges.adoc | 7 +++++++ .../openshift_build_process.adoc | 7 +++++++ .../openshift_cartridge_reference.adoc | 6 +++++- .../upgrading_custom_and_community_cartridges.adoc | 7 +++++++ .../installing_client_tools_on_fedora.adoc | 8 ++++++++ .../installing_client_tools_on_macosx.adoc | 6 ++++++ .../installing_client_tools_on_opensuse.adoc | 6 ++++++ .../installing_client_tools_on_rhel.adoc | 6 ++++++ .../installing_client_tools_on_ubuntu_debian.adoc | 6 ++++++ .../installing_client_tools_on_windows.adoc | 14 +++++++++----- getting_started/create_app.adoc | 11 ++++++++--- getting_started/interfaces.adoc | 8 +++++++- user_guide/apps.adoc | 8 ++++---- user_guide/auth_tokens.adoc | 6 ++++++ user_guide/cartridges.adoc | 5 +++-- user_guide/domains.adoc | 7 ++++--- user_guide/ssh_keys.adoc | 7 ++++--- 23 files changed, 145 insertions(+), 22 deletions(-) diff --git a/cartridge_specification_guide/backing_up_and_restoring_cartridges.adoc b/cartridge_specification_guide/backing_up_and_restoring_cartridges.adoc index c65b9170b4e5..9c85fe02b91d 100644 --- a/cartridge_specification_guide/backing_up_and_restoring_cartridges.adoc +++ b/cartridge_specification_guide/backing_up_and_restoring_cartridges.adoc @@ -3,7 +3,14 @@ {product-version} :data-uri: :icons: +:toc: +:toclevels: 1 +:toc-placement!: +:toc-title: Topics Covered +toc::[] + +== Overview OpenShift provides +snapshot+ and +restore+ features for user applications. These features enable OpenShift application developers to: diff --git a/cartridge_specification_guide/cartridge_events.adoc b/cartridge_specification_guide/cartridge_events.adoc index 4d33d4b9b4cf..348c305c1005 100644 --- a/cartridge_specification_guide/cartridge_events.adoc +++ b/cartridge_specification_guide/cartridge_events.adoc @@ -3,7 +3,14 @@ {product-version} :data-uri: :icons: +:toc: +:toclevels: 1 +:toc-placement!: +:toc-title: Topics Covered +toc::[] + +== Overview OpenShift provides a publish and subscribe system that enables a cartridge to act when a developer adds or removes another cartridge in an application. The _Publishes_ and _Subscribes_ elements in the [filename]#$cartridge_name/metadata/manifest.yml# file detail support for cartridge events. diff --git a/cartridge_specification_guide/cartridge_scripts.adoc b/cartridge_specification_guide/cartridge_scripts.adoc index cdc52e4072a8..cee9d722e2e4 100644 --- a/cartridge_specification_guide/cartridge_scripts.adoc +++ b/cartridge_specification_guide/cartridge_scripts.adoc @@ -3,7 +3,14 @@ {product-version} :data-uri: :icons: +:toc: +:toclevels: 1 +:toc-placement!: +:toc-title: Topics Covered +toc::[] + +== Overview Cartridge scripts act as the application programming interface (API) for a cartridge. Use these scripts to contain the required code for single version software that configures easily. For complex configurations and software with multiple versions, use these scripts as shim code to set up the required environment and run additional scripts. You can also create symbolic links from these scripts. Cartridge scripts are located in the [filename]#$cartridge_name/bin/# directory, and run from the cartridge's home directory. diff --git a/cartridge_specification_guide/creating_template_directories_for_language_cartridges.adoc b/cartridge_specification_guide/creating_template_directories_for_language_cartridges.adoc index 84540fa875bb..556e0fac26d2 100644 --- a/cartridge_specification_guide/creating_template_directories_for_language_cartridges.adoc +++ b/cartridge_specification_guide/creating_template_directories_for_language_cartridges.adoc @@ -3,7 +3,14 @@ {product-version} :data-uri: :icons: +:toc: +:toclevel: 1 +:toc-placement!: +:toc-title: Topics Covered +toc::[] + +== Overview Use the [filename]#$cartridge_name/template/# or [filename]#$cartridge_name/template.git/# directory to provide a basic example of an application written in the language or framework your cartridge packages. Welcome the application developer to your cartridge and inform them that the cartridge is operating correctly. If you provide a [filename]#$cartridge_name/template.git/# directory, OpenShift copies the directory for the application developer. diff --git a/cartridge_specification_guide/environment_variables.adoc b/cartridge_specification_guide/environment_variables.adoc index e394db79d505..f2226e617c2e 100644 --- a/cartridge_specification_guide/environment_variables.adoc +++ b/cartridge_specification_guide/environment_variables.adoc @@ -3,7 +3,14 @@ {product-version} :data-uri: :icons: +:toc: +:toclevels: 1 +:toc-placement!: +:toc-title: Topics Covered +toc::[] + +== Overview OpenShift uses environment variables to communicate information between cartridges, applications, and the system. OpenShift provides several system environment variables that are available for use at all cartridge entry points. diff --git a/cartridge_specification_guide/exposing_services.adoc b/cartridge_specification_guide/exposing_services.adoc index d77d021c0327..d866aadd7a7f 100644 --- a/cartridge_specification_guide/exposing_services.adoc +++ b/cartridge_specification_guide/exposing_services.adoc @@ -3,7 +3,14 @@ {product-version} :data-uri: :icons: +:toc: +:toclevels: 1 +:toc-placement!: +:toc-title: Topics Covered +toc::[] + +== Overview Most cartridges provide services by binding to ports. Cartridges must declare to which ports they bind, and provide variable names to describe: * The IP addresses provided to the cartridge for binding. diff --git a/cartridge_specification_guide/locking_cartridges.adoc b/cartridge_specification_guide/locking_cartridges.adoc index beeed3695075..310c1183823f 100644 --- a/cartridge_specification_guide/locking_cartridges.adoc +++ b/cartridge_specification_guide/locking_cartridges.adoc @@ -3,7 +3,14 @@ {product-version} :data-uri: :icons: +:toc: +:toclevels: 1 +:toc-placement!: +:toc-title: Topics Covered +toc::[] + +== Overview Cartridge instances on a gear are either locked or unlocked at any given time. Locking a cartridge enables cartridge scripts to have greater access to the gear's files and directories. Application developers have read and write access to unlocked files, and read-only access to locked files. This means that application scripts and hooks cannot override cartridge code when the cartridge is locked. OpenShift controls the lock state of cartridges, moving them between locked and unlocked at various points in the cartridge life cycle. diff --git a/cartridge_specification_guide/openshift_build_process.adoc b/cartridge_specification_guide/openshift_build_process.adoc index 22ece87fa3a6..f3b74a7a77ba 100644 --- a/cartridge_specification_guide/openshift_build_process.adoc +++ b/cartridge_specification_guide/openshift_build_process.adoc @@ -3,7 +3,14 @@ {product-version} :data-uri: :icons: +:toc: +:toclevels: 1 +:toc-placement!: +:toc-title: Topics Covered +toc::[] + +== Overview When changes to an application's Git repository are pushed, OpenShift builds and deploys the application using the updated repository. The build and deploy process changes if the application is scaling or if it uses a builder cartridge. [[default_build_lifecycle]] diff --git a/cartridge_specification_guide/openshift_cartridge_reference.adoc b/cartridge_specification_guide/openshift_cartridge_reference.adoc index 69d8aeb6a0b4..e94b1afdd0e7 100644 --- a/cartridge_specification_guide/openshift_cartridge_reference.adoc +++ b/cartridge_specification_guide/openshift_cartridge_reference.adoc @@ -3,8 +3,12 @@ {product-version} :data-uri: :icons: +:toc: +:toclevels: 1 +:toc-placement!: +:toc-title: Topics Covered -This topic contains reference material for OpenShift cartridges. +toc::[] [[cartridge_hierarchy]] == Cartridge Hierarchy diff --git a/cartridge_specification_guide/upgrading_custom_and_community_cartridges.adoc b/cartridge_specification_guide/upgrading_custom_and_community_cartridges.adoc index f0782ab8a560..646c6687cae0 100644 --- a/cartridge_specification_guide/upgrading_custom_and_community_cartridges.adoc +++ b/cartridge_specification_guide/upgrading_custom_and_community_cartridges.adoc @@ -3,7 +3,14 @@ {product-version} :data-uri: :icons: +:toc: +:toclevels: 1 +:toc-placement!: +:toc-title: Topics Covered +toc::[] + +== Overview The OpenShift runtime contains a system for upgrading custom cartridges on a gear to the latest available version and for applying gear-level changes that affect cartridges. ifdef::openshift-online[] diff --git a/client_tools_install_guide/installing_client_tools_on_fedora.adoc b/client_tools_install_guide/installing_client_tools_on_fedora.adoc index 689229da55a6..52c490866f42 100644 --- a/client_tools_install_guide/installing_client_tools_on_fedora.adoc +++ b/client_tools_install_guide/installing_client_tools_on_fedora.adoc @@ -3,7 +3,13 @@ {product-version} :data-uri: :icons: +:toc: +:toc-placement!: +:toc-title: Topics Covered +toc::[] + +== Overview The OpenShift client tools are supported on Fedora 16 or later and require sudoer or root access. [NOTE] @@ -19,6 +25,8 @@ You can install the client tools on Fedora operating systems by installing the R The RPM version of the client tools is not updated as frequently as the gem maintained by the OpenShift development team. ==== +== Install Client Tools + *Install with YUM Package Manager* From the terminal, install the client tools and all other required dependencies: diff --git a/client_tools_install_guide/installing_client_tools_on_macosx.adoc b/client_tools_install_guide/installing_client_tools_on_macosx.adoc index 264bb7406190..921824e84085 100644 --- a/client_tools_install_guide/installing_client_tools_on_macosx.adoc +++ b/client_tools_install_guide/installing_client_tools_on_macosx.adoc @@ -3,7 +3,13 @@ {product-version} :data-uri: :icons: +:toc: +:toc-placement!: +:toc-title: Topics Covered +toc::[] + +== Overview The OpenShift client tools are supported on Mac OS X 10.5 or later and require sudo access. Installing the client tools on a Mac OS X operating system comprises three steps: diff --git a/client_tools_install_guide/installing_client_tools_on_opensuse.adoc b/client_tools_install_guide/installing_client_tools_on_opensuse.adoc index 47f9c27b5ff6..981d11d8abda 100644 --- a/client_tools_install_guide/installing_client_tools_on_opensuse.adoc +++ b/client_tools_install_guide/installing_client_tools_on_opensuse.adoc @@ -3,7 +3,13 @@ {product-version} :data-uri: :icons: +:toc: +:toc-placement!: +:toc-title: Topics Covered +toc::[] + +== Overview Installing the client tools on openSUSE requires sudoer or root access and comprises three steps: *Step 1*: Install *_Ruby_* + diff --git a/client_tools_install_guide/installing_client_tools_on_rhel.adoc b/client_tools_install_guide/installing_client_tools_on_rhel.adoc index 61060640c3e5..3c1e9938a0db 100644 --- a/client_tools_install_guide/installing_client_tools_on_rhel.adoc +++ b/client_tools_install_guide/installing_client_tools_on_rhel.adoc @@ -3,7 +3,13 @@ {product-version} :data-uri: :icons: +:toc: +:toc-placement!: +:toc-title: Topics Covered +toc::[] + +== Overview You must have the following to successfully install the client tools: * Red Hat Enterprise Linux 6 or later diff --git a/client_tools_install_guide/installing_client_tools_on_ubuntu_debian.adoc b/client_tools_install_guide/installing_client_tools_on_ubuntu_debian.adoc index 9e05e66f9170..53508155fbe3 100644 --- a/client_tools_install_guide/installing_client_tools_on_ubuntu_debian.adoc +++ b/client_tools_install_guide/installing_client_tools_on_ubuntu_debian.adoc @@ -3,7 +3,13 @@ {product-version} :data-uri: :icons: +:toc: +:toc-placement!: +:toc-title: Topics Covered +toc::[] + +== Overview Install the client tools on Ubuntu or Debian requires sudoer or root access and comprises four steps: *Step 1*: Install *_Ruby_* diff --git a/client_tools_install_guide/installing_client_tools_on_windows.adoc b/client_tools_install_guide/installing_client_tools_on_windows.adoc index e4d7be7987df..689d613de80f 100644 --- a/client_tools_install_guide/installing_client_tools_on_windows.adoc +++ b/client_tools_install_guide/installing_client_tools_on_windows.adoc @@ -4,7 +4,13 @@ :data-uri: :icons: :experimental: +:toc: +:toc-placement!: +:toc-title: Topics Covered +toc::[] + +== Overview The OpenShift Client Tools are supported on the following Windows operating systems: * Windows 7 @@ -17,8 +23,6 @@ The OpenShift Client Tools are supported on the following Windows operating syst Sufficient privileges are required to install software on Windows systems. Depending on specific user permissions, disabling the User Account Control (UAC) on Windows Vista or Windows 7 operating systems may be necessary. ==== -== Before you begin - Installing the client tools on Windows operating system comprises three steps: @@ -30,7 +34,7 @@ Installing the client tools on Windows operating system comprises three steps: Before you can install the client tools, you must download and install *_RubyInstaller_* and *_Git_* on your system. -=== Install RubyInstaller +== Install RubyInstaller 1. From http://rubyinstaller.org/[rubyinstaller.org], download and save the latest RubyInstaller package for Windows to your desired directory. //+ @@ -46,7 +50,7 @@ image:2829.png[image] + Click btn:[Finish] when the install completes. -=== Install Git Version Control +== Install Git Version Control 1. From http://msysgit.github.com/[http://msysgit.github.com/], download and save the latest version of Git for Windows to your desired directory. @@ -64,7 +68,7 @@ image:2828.png[image] + Click btn:[Finish] when the install completes. -=== Install the Client Tools +== Install Client Tools 1. Open Windows Command Prompt. diff --git a/getting_started/create_app.adoc b/getting_started/create_app.adoc index f2a4a5cfca91..6a4c4adedd44 100644 --- a/getting_started/create_app.adoc +++ b/getting_started/create_app.adoc @@ -4,12 +4,17 @@ :data-uri: :icons: :experimental: +:toc: +:toc-placement!: +:toc-title: Topics Covered + +toc::[] When you have completed the link:preliminary_steps.html[preliminary steps] and configured the client tools with the interactive wizard, you are ready to create an application. You should already have a domain created under which you will create the new application. -You can create a new application with either the management console or the command line interface, referred to as the client tools. +You can create a new application with either the management console or the client tools. -== Management Console +== Create Application with Management Console . Log into your account from the management console. . From the btn:[Applications] tab, click btn:[Add Application]. . Click on the web framework cartridge you want to create. @@ -34,7 +39,7 @@ $ git clone //$ rhc domain create //---- -== Client Tools (CLI) +== Create Application with Client Tools (CLI) From the directory where you want the application created, run the following command: ---- diff --git a/getting_started/interfaces.adoc b/getting_started/interfaces.adoc index f25150f01dd1..742c5cb693da 100644 --- a/getting_started/interfaces.adoc +++ b/getting_started/interfaces.adoc @@ -1,9 +1,15 @@ -= Introduction += Interacting with OpenShift {product-author} {product-version} :data-uri: :icons: +:toc: +:toc-placement!: +:toc-title: Topics Covered +toc::[] + +== Overview There are two interfaces available for interacting with OpenShift Online: the Management Console graphical user interface and the command line interface (CLI), referred to as the client tools. == Management Console diff --git a/user_guide/apps.adoc b/user_guide/apps.adoc index 290b63de1a0a..b523d9829ffa 100644 --- a/user_guide/apps.adoc +++ b/user_guide/apps.adoc @@ -4,13 +4,13 @@ :data-uri: :icons: :toc: -:toc-placement: preamble +:toc-placement!: +:toc-title: Topics Covered -All OpenShift applications consist of one web framework cartridge that serves web requests, and additional cartridges that provide other capabilities, such as databases, scheduled jobs, or continuous integration. +toc::[] == Overview - -When a new application is created, a URL with name of the application and the name of the domain is registered in DNS. A copy of the application code is checked out locally into a folder with the same name as the application. Note that different types of applications may require different folder structures. Application components are run on gears. +All OpenShift applications consist of one web framework cartridge that serves web requests, and additional cartridges that provide other capabilities, such as databases, scheduled jobs, or continuous integration. When a new application is created, a URL with name of the application and the name of the domain is registered in DNS. A copy of the application code is checked out locally into a folder with the same name as the application. Note that different types of applications may require different folder structures. Application components are run on gears. With each new application that is created with the client tools, a remote Git repository is populated with the selected cartridge, which is then cloned to the current directory on the local machine. The host name and IP address of the application are also added to the list of known hosts in the [filename]#~/.ssh/known_hosts# directory. diff --git a/user_guide/auth_tokens.adoc b/user_guide/auth_tokens.adoc index e26620e5314d..a43e428f1caf 100644 --- a/user_guide/auth_tokens.adoc +++ b/user_guide/auth_tokens.adoc @@ -3,7 +3,13 @@ {product-version} :data-uri: :icons: +:toc: +:toc-placement!: +:toc-title: Topics Covered +toc::[] + +== Overview An authorization token is used to automatically log in to an OpenShift account without having to enter login credentials each time. A token is also used to grant another user full or partial access to an account, which is determined by the _scope_ of the token, which are described in the following table. .Available Scopes for Authorization Tokens diff --git a/user_guide/cartridges.adoc b/user_guide/cartridges.adoc index 0066a2a75047..847fa511d81d 100644 --- a/user_guide/cartridges.adoc +++ b/user_guide/cartridges.adoc @@ -4,9 +4,10 @@ :data-uri: :icons: :toc: -:toc-placement: preamble +:toc-placement!: +:toc-title: Topics Covered -All OpenShift applications consist of one web framework cartridge that serves web requests, and additional cartridges that provide other capabilities, such as databases, scheduled jobs, or continuous integration. +toc::[] == Overview diff --git a/user_guide/domains.adoc b/user_guide/domains.adoc index 0db0420ed0a9..fcf74de13221 100644 --- a/user_guide/domains.adoc +++ b/user_guide/domains.adoc @@ -4,12 +4,13 @@ :data-uri: :icons: :toc: -:toc-placement: preamble +:toc-placement!: +:toc-title: Topics Covered -All OpenShift applications must belong to a _domain_, which forms part of an application's public URL. +toc::[] == Overview -The format for an application URL is _application-domain_.example.com. Each account can have access to one or more domains that are shared by others. Depending on the type of account you have, you might be able to create more than one domain. +All OpenShift applications must belong to a _domain_, which forms part of an application's public URL. The format for an application URL is _application-domain_.example.com. Each account can have access to one or more domains that are shared by others. Depending on the type of account you have, you might be able to create more than one domain. ifdef::openshift-online[] A blacklist restricts the domain names that are available. A warning message informs you if a blacklisted domain name has been selected when you attempt to create a domain. Domain names consist of a maximum of 16 alphanumeric characters and cannot contain spaces or symbols. Note that a domain must be created before you can create applications. diff --git a/user_guide/ssh_keys.adoc b/user_guide/ssh_keys.adoc index 76206bbaf3af..832659efaa94 100644 --- a/user_guide/ssh_keys.adoc +++ b/user_guide/ssh_keys.adoc @@ -5,12 +5,13 @@ :icons: :experimental: :toc: -:toc-placement: preamble +:toc-placement!: +:toc-title: Topics Covered -OpenShift uses the Secure Shell (SSH) network protocol to authenticate account credentials with the remote servers for secure communication, and supports both RSA and DSA keys for SSH authentication. +toc::[] == Overview -SSH utilizes key cryptography for both the connection and for authentication. OpenShift uses SSH for performing Git operations and to provide remote access to your application gear. +OpenShift uses the Secure Shell (SSH) network protocol to authenticate account credentials with the remote servers for secure communication, and supports both RSA and DSA keys for SSH authentication. SSH utilizes key cryptography for both the connection and for authentication. OpenShift uses SSH for performing Git operations and to provide remote access to your application gear. When the client tools are installed and the `rhc setup` command is initially run to link:../client_tools_install_guide/configuring_client_tools.html[configure] the client tools, the setup wizard generates a new pair of SSH keys in the default [filename]#.ssh# folder of your home directory. The SSH key pair consists of the public key, [filename]#id_rsa.pub#, and the private key, [filename]#id_rsa#. As part of the initial configuration, you have the option of automatically uploading the public key, [filename]#id_rsa.pub#, to the remote server. Your account can have one or more public SSH keys associated with it, and you can access your account from any workstation that has the private SSH key on it.