Composable image: Move common content into individual settings topics

sites/platform/src/administration/users.md

@@ -42,7 +42,7 @@ A user can have one of the following roles on an environment type which grants t
 | Contributor | Yes              | No         | Yes       | Yes                | Yes        | No              | No              |
 | Viewer      | Yes              | No         | No        | Yes                | No         | No              | No              |
 
-To customize which roles can use SSH, set [`access` in your app configuration](/create-apps/app-reference/single-runtime-image.md#access).
+To customize which roles can use SSH, set [`access` in your app configuration](/create-apps/image-properties/access.md).
 
 ### View a user's permissions across all of the projects in your organization
 

sites/platform/src/create-apps/app-reference/_index.md

@@ -1,24 +1,65 @@
 ---
-title: "App reference"
-weight: 4
+title: "Choose an image type"
+weight: -19
 description: Configure your app and control how it's built and deployed on {{% vendor/name %}}.
 layout: single
 ---
 
+<!-- 
+Jul20205 WORK IN PROGRESS 
+The point of this topic is to help the user to decide which type to choose
+- rework this topic make it clear when you choose one instead of the other (a table, if possible)
+- add "image" definition here and also in the glossary
+- link to use cases
+- mention the level of support for both types
+-->
+
+An _image_ represents the configuration for the container that contains the application (or service) that you want to deploy. 
+
+<!-- JUL20205 kept the original content below for now -->
 To define your app, you can either use one of {{% vendor/name %}}'s [single-runtime image](/create-apps/app-reference/single-runtime-image.md)
 or its [composable image (BETA)](/create-apps/app-reference/composable-image.md).
 
+The single-runtime image type has the following characteristics: 
+- Can contain only a single runtime
+- Requires more manual configuration the composable images, but are more flexible
+- Initial build takes
+- `type` defines your image version (for example, `php:8.4`)
+- You can move to a composable image later, if your application needs change
+
+The composable image type has the following characteristics: 
+- Can contain multiple runtimes
+- Requires less manual configuration than single-runtime images and offers more flexibility in other ways
+- Initial build and rebuilds and can take a long time,<!-- a few minutes? --> but caching increases the speed <!-- clarify this -->
+- `type` defines your Nix channel
+- Can be used for applications only, not services <!-- what about workers? -->
+
+
+<!-- add a feature/comparison table, if appropriate - easier to read for user 
+| Feature              | Single-runtime image | Composable image | 
+|----------------------|----------------------|------------------|
+|   Support            |                      |                  | 
+|   `type`             |                      |                  | 
+|                  |                      |                  | 
+
+-->
+
 ## Single-runtime image
 
 {{% vendor/name %}} provides and maintains a list of single-runtime images you can use for each of your application containers.</br>
 See [all of the options you can use](/create-apps/app-reference/single-runtime-image.md) to define your app using a single-runtime image.
 
 ## Composable image (BETA)
 
-The {{% vendor/name %}} composable image provides more flexibility than single-runtime images.
-When using a composable image, you can define a stack (or group of packages) for your application container to use.
+The {{% vendor/name %}} composable image provides more flexibility than single-runtime images. This image type enables you to define or "compose" the stack (or group of packages) to include in the container that runs your application. 
+
+Composable images can be used for applications only, not for services. This image type enables you to install multiple runtimes (such as PHP, Ruby, and so on) as well aXXX in your application container.
+
+<!-- orig sentence below, now in included in first para 
+When using a composable image, you can define a stack (or group of packages) for your application container to use. 
+-->
 
-There are over 80,000 packages available from the [Nix Packages collection](https://search.nixos.org/) that you can add to your stack.
+There are over 120,000 packages available from the [Nix Packages collection](https://search.nixos.org/) that you can add to your stack.
 You can add as many packages to your application container as you need.
 
 {{% note %}}

sites/platform/src/create-apps/image-properties/_index.md

@@ -0,0 +1,11 @@
+---
+title: "Image properties"
+weight: 4
+description: Details about image properties in the {{% vendor/name %}} config.yaml file
+# layout: single
+---
+
+**Note:** The properties below are available in both single-runtime and composable images. 
+For most of these properties, the syntax and details are the same for both image types. Differences in meaning and syntax are noted as needed in the property details.
+
+To learn about the properties that are unique to each image type, refer to the [single-runtime image](/create-apps/app-reference/single-runtime-image.md#) and [composable image](/create-apps/app-reference/composable-image.md#) topics.

sites/platform/src/create-apps/image-properties/access.md

@@ -0,0 +1,29 @@
+---
+title: "`access`"
+weight: 4
+description: An access dictionary that defines the access control for roles accessing app environments.
+---
+
+Optional in [single-runtime](/create-apps/app-reference/single-runtime-image.md#top-level-properties) and [composable](/create-apps/app-reference/composable-image.md#top-level-properties) images.
+
+{{% description %}}
+
+The `access` dictionary has one allowed key:
+
+| Name  | Allowed values                      | Default       | Description |
+| ----- | ----------------------------------- | ------------- | ----------- |
+| `ssh` | `admin`, `contributor`, or `viewer` | `contributor` | Defines the minimum role required to access app environments via SSH. |
+
+In the following example, only users with `admin` permissions for the given [environment type](/administration/users.md#environment-type-roles)
+can access the deployed environment via SSH:
+
+```yaml {configFile="app"}
+access:
+  ssh: admin
+``` 
+
+<!-- another option for getting back to the single/composable topics 
+Related topics:
+* [Single-runtime image](/create-apps/app-reference/single-runtime-image.md) 
+* [Composable image](/create-apps/app-reference/composable-image.md) 
+-->

sites/platform/src/create-apps/image-properties/additional_hosts.md

@@ -0,0 +1,25 @@
+---
+title: "`additional_hosts`"
+weight: 4
+description: An additional hosts dictionary that maps hostnames to IP addresses.
+---
+
+Optional in [single-runtime](/create-apps/app-reference/single-runtime-image.md#top-level-properties) and [composable](/create-apps/app-reference/composable-image.md#top-level-properties) images.
+
+{{% description %}}
+
+If you're using a private network with specific IP addresses you need to connect to,
+you might want to map those addresses to hostnames to better remember and organize them.
+In such cases, you can add a map of those IP addresses to whatever hostnames you like.
+Then when your app tries to access the hostname, it's sent to the proper IP address.
+
+So in the following example, if your app tries to access `api.example.com`, it's sent to `192.0.2.23`.
+
+```yaml {configFile="app"}
+additional_hosts:
+  api.example.com: "192.0.2.23"
+  web.example.com: "203.0.113.42"
+```
+
+This is equivalent to adding the mapping to the `/etc/hosts` file for the container.
+