Restructure installation docs

content/docs/docker-windows-aad.md

@@ -5,69 +5,66 @@ path: /docs/docker-windows-aad
 
 # Appsody and Docker Desktop on Windows 10
 
-Docker Desktop on Windows requires access to the computer's filesystems in order to mount host volumes contained in those filesystems. That access is explained in detail in the "Shared Drives" section of the ["Get started with Docker for Windows"](https://docs.docker.com/docker-for-windows/) page.
+Docker Desktop on Windows requires access to the computer's filesystems to mount host volumes contained in those filesystems. You can find more information at [Get started with Docker for Windows](https://docs.docker.com/docker-for-windows/).
 
-Appsody relies on mounted hosted volumes to expedite the startup of applications under development, so that it is imperative that Docker Desktop be configured to access the shared drive containing the user's home directory. Once Docker has that access, the next requirement is for that user to have the "Full Control" permission to directories mounted to containers.
+Appsody relies on mounted hosted volumes to expedite the startup of applications under development. Therefore, Docker Desktop must be configured to access the shared drive that contains the user's home directory. When Docker has that access, the next requirement is for that user to have the "Full Control" permission to directories mounted to containers.
 
-In most cases, it is sufficient to configure Docker with the same user as the user developing applications with Appsody.
+In most cases, it is sufficient to configure Docker with the same user as the user that is developing applications with Appsody.
 
-However, for users of Windows 10 Enterprise secured with Azure Active Directory (AAD), the AAD user does not reside in the local host and may not be accepted in the "Shared Drives" tab of the Docker Desktop "Settings" page, specially if the organization has configured AAD to use authentication mechanisms that do not include user passwords, such as PIN codes.
+However, for users of Windows 10 Enterprise that is secured with Azure Active Directory (AAD), the AAD user does not reside in the local host and might not be accepted in the "Shared Drives" tab of the Docker Desktop "Settings" dialog. Particularly if the organization configured AAD to use authentication mechanisms other than user passwords, such as PIN codes.
 
 ## Workaround for Windows 10 Enterprise secured with Azure Active Directory
 
-If Docker Desktop does not accept your AAD user and password in the "Shared Drives" tab of the Docker "Settings" panel, or you just do not have the password for your user, the only known workaround at this time is to use a separate, local, Windows account to handle the drive sharing and file permissions.
+If Docker Desktop does not accept your AAD user and password in the "Shared Drives" tab of the Docker "Settings" dialog, or you do not have the password for your user, the only known workaround currently is to use a separate, local, Windows account to handle the drive sharing and file permissions.
 
-Assuming the creation of a new user does not violate your organization policies, the workaround is comprised of the following steps:
+Assuming the creation of a new user does not violate your organization's policies, the workaround consists of the following steps:
 
 1. [Create a new local user account](https://support.microsoft.com/en-us/help/4026923/windows-10-create-a-local-user-or-administrator-account
-) on Windows and use that account and respective password in the "Shared Drives" tab of the Docker Desktop's "Settings" panel.
+) on Windows and use that account and its password in the "Shared Drives" tab of the Docker Desktop "Settings" dialog.
 
-   Most systems will have only a single shared drive, labeled "C". If your "Shared Drives" list shows additional drive letters, make sure you select the label matching the drive letter for the AAD user's home directory.
+    Most systems have only a single shared drive, labeled "C". If your "Shared Drives" list shows more drive letters, make sure you select the label that matches the drive letter for the AAD user's home directory.
 
-1. Grant the new user from step 1 the "Full Control" permission to the folders to be mounted by Appsody into a container. You could use the "Security" tab for each folder properties in the File Explorer application, but the quickest and simplest mechanism is to open a "Command Prompt" and issue the following commands to achieve the same results:
+2. Grant the new user the "Full Control" permission to the folders that are going to be mounted into a container by Appsody. You can run Windows Explorer, right-click the directory, click Properties, and on the Security tab change the permissions. Alternatively you can open a command prompt and enter the following [icacls](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/icacls) commands:
 
     ```
-    REM This has to be the same user applied to the Shared Drive in Docker Desktop
+    REM Must be the user that you specified in the "Shared Drives" tab of the Docker Desktop dialog
     set DOCKER_SHARED_DRIVE_USER=Developer
 
-    REM if using the java-microprofile collection and until issue 
-    REM https://github.com/appsody/stacks/issues/363 is resolved:
+    REM Include if you are using Java stacks:
     mkdir %USERPROFILE%\.m2\repository
     icacls "%USERPROFILE%\.m2" /grant %DOCKER_SHARED_DRIVE_USER%:(OI)(CI)F
-    
+
     mkdir %USERPROFILE%\.appsody
     icacls "%USERPROFILE%\.appsody" /grant %DOCKER_SHARED_DRIVE_USER%:(OI)(CI)F
-    
+
     mkdir %USERPROFILE%\directory-for-appsody-project
     icacls "%USERPROFILE%\directory-for-appsody-project" /grant %DOCKER_SHARED_DRIVE_USER%:(OI)(CI)F
     ```
 
-    > Note that the user in the `DOCKER_SHARED_DRIVE_USER` environment variable must match the user specified in the Docker Desktop "Shared Drives" tab in the first step. 
+    Repeat the `mkdir` and `icacls` commands for any other directories where you plan to create new Appsody projects.
 
-    Repeat the `mkdir` and `icacls` commands for any other directory where you are about to create a new Appsody project. If you plan on creating multiple projects, you can also target a parent directory for those future project directories, so that you do not have to repeat the commands for each new Appsody project directory.
+    The parameters to the `icacls` commands specify a recursive authorization. Therefore, if you plan on creating multiple projects, you might want to create a parent directory to contain the individual project directories. Then, you would not need to repeat the `icacls` commands for each new Appsody project directory.
 
-    Since the parameters for `icacls` specify a recursive authorization, granting the permission directly to the `%USERPROFILE%` directory could be faster and simpler, but the instructions in this page were written to minimize impact to the system.
+     Granting the permissions directly to the `%USERPROFILE%` directory might be faster and simpler. However, these instructions are written to minimize impact to the system.
 
-1. Validating the correct permissions
+3. Validating the permissions
 
-   The commands below will run a docker container that creates (and subsequently removes) a directory in each of the directories used by Appsody. The commands will indicate the successful outcome of the validation if the shared drive access and the filesystem permissions are set correctly, 
+   The following commands run a docker container that creates, and then removes, a directory in each of the directories used by Appsody. The commands indicate the successful outcome of the validation if the shared drive access and the filesystem permissions are set correctly:
 
     ```
     docker run --rm -it -v "%USERPROFILE%\.appsody":/data alpine  /bin/sh  -c "mkdir /data/test-write-permission && echo Success; rmdir /data/test-write-permission"
 
     docker run --rm -it -v "%USERPROFILE%\directory-for-appsody-project":/data alpine  /bin/sh  -c "mkdir /data/test-write-permission && echo Success; rmdir /data/test-write-permission"
 
-    REM if you also granted permissions to the .m2 folder:
+    REM If you granted permissions to the .m2 folder:
     docker run --rm -it -v "%USERPROFILE%\.m2\repository":/data alpine  /bin/sh  -c "mkdir /data/test-write-permission && echo Success; rmdir /data/test-write-permission"
-
     ```
 
-
 ## Removing the workaround
 
-If you want to revert the Windows filesystem permissions later, open another "Command Prompt" and execute a `icacls ... /remove` command on all affected directories. The operation is recursive and will remove the permissions from sub-directories of those directories as well.
+If you want to revert the Windows filesystem permissions later, open another command prompt and run a `icacls ... /remove` command on all affected directories. The operation is recursive and removes the permissions from subdirectories too.
 
-As an example, for the specific instructions in this page, you would execute the following commands:
+For example, run the following commands:
 
 ```
 set DOCKER_SHARED_DRIVE_USER=Developer
@@ -77,4 +74,4 @@ icacls "%USERPROFILE%\.appsody" /remove %DOCKER_SHARED_DRIVE_USER%
 icacls "%USERPROFILE%\directory-for-appsody-project" /remove %DOCKER_SHARED_DRIVE_USER%
 ```
 
-You may decide whether or not to remove the directories after removing the permissions.
+You might also want to delete the directories.

content/docs/faq.md

@@ -82,3 +82,24 @@ You might find that embedded Kubernetes on Docker Docktop on macOS is using port
 The workaround is to append `-p 9444:9443` to the Appsody command so that the port inside the container is 9443 but access to the application (the publicly exposed port), is through 9444.
 
 Alternatively you can append `-P` to your Appsody command, which automatically assigns a free port to the process.
+
+### 8. Can I run Appsody with SELinux?
+
+Yes. Although if you see errors similar to the following, it indicates that the Docker daemon, although it runs as `root`, might not be able to access the folders that are mounted from the host file system:
+
+```
+Container] [Warning] Failed to add directory to recursive watch list: /project/user-appopen /project/user-app: permission denied
+npm ERR! path /project/user-app/package.json
+[Container] npm ERR! Code EACCES
+[Container] npm ERR! errno -13
+[Container] npm ERR! syscall open
+[Container] npm ERR! Error: EACCES: permission denied, open '/project/user-app/package.json'
+```
+
+To check whether SELinux is enabled and enforcing its policies, you can run `sestatus`. The output of the command includes the `Current Mode` of SELinux. If it is set to `enforcing`, and you see errors similar to those shown, you might need to change your SELinux configuration.
+
+You can exempt the folders that are mounted by the stacks that you are using, with the following command:
+```
+chcon -Rt svirt_sandbox_file_t </path/to/volume>
+```
+You might need to run this command multiple times to whitelist different paths, depending on your setup, and on the mount points of the specific stack you are using.

content/docs/getting-started/quick-start.md → content/docs/getting-started.md

@@ -1,10 +1,10 @@
 ---
-title: Quick Start
+title: Getting Started
 ---
 
-# Quick Start
+# Getting Started
 
-If you haven't already installed Appsody, follow the steps described in [Installation](/docs/getting-started/installation).
+If you haven't already installed Appsody, follow the steps described in [Installing Appsody](/docs/installing/installing-appsody).
 
 Creating a new Appsody project is easy! All you need is a few commands to create a containerized development environment running with the stack of your choice.
 
@@ -14,8 +14,7 @@ First, choose a development stack. To see all the available stacks, run:
 appsody list
 ```
 
-Create a new directory for your project and run `appsody init <stack>` to download the template project. The following example uses the `nodejs-express` stack to create
-a fully functional Appsody project:
+Create a new directory for your project and run `appsody init <stack>` to download the template project. The following example uses the `nodejs-express` stack to create a fully functional Appsody project:
 
 ```
 mkdir my-project
@@ -40,4 +39,3 @@ You are ready to continue developing your application.
 - When you are ready to build a production docker image, run `appsody build`.
 
 > You can get more information about all the available commands by running `appsody help [command]` or `appsody <command> --help`.
-