diff --git a/content/docs/docker-windows-aad.md b/content/docs/docker-windows-aad.md index 0e57fd1c1..15807dc08 100644 --- a/content/docs/docker-windows-aad.md +++ b/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. diff --git a/content/docs/faq.md b/content/docs/faq.md index ca082c3db..d78879ad0 100644 --- a/content/docs/faq.md +++ b/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 +``` +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. diff --git a/content/docs/getting-started/quick-start.md b/content/docs/getting-started.md similarity index 89% rename from content/docs/getting-started/quick-start.md rename to content/docs/getting-started.md index f48fc1ba5..88a662ac0 100644 --- a/content/docs/getting-started/quick-start.md +++ b/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 ` 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 ` 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 --help`. - diff --git a/content/docs/getting-started/installation.md b/content/docs/getting-started/installation.md deleted file mode 100644 index 3aa759440..000000000 --- a/content/docs/getting-started/installation.md +++ /dev/null @@ -1,202 +0,0 @@ ---- -title: Installing Appsody ---- - -# Installing Appsody - -You can install Appsody on your system in a few easy steps by using our binary packages, which are available for macOS®, Ubuntu, Red Hat Enterprise Linux (RHEL), and Windows®. - -## Requirements -- A working internet connection -- Appsody depends on Docker so ensure that you have [Docker](https://docs.docker.com/get-started/) installed and the Docker daemon is running on your system. - -## Installing on macOS - -Follow these steps: - -1. If you don't have the Xcode command line tools installed on your system, install them by running: - -``` -xcode-select --install -``` - -2. If you don't have Homebrew installed on your system, install it by running: - -``` -/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" -``` - -3. To install Appsody, run: - -``` -brew install appsody/appsody/appsody -``` - -This command creates a brew tap for the `appsody/appsody` repo and installs the `appsody` formula. - -That's all there is to it! You can now follow our [Quick Start](/docs/getting-started/quick-start) instructions to create your first containerized development environment with a running *Hello World!* application. - -## Installing on Ubuntu - -Follow these steps: - -1. Your user account must be a member of the `docker` group, which you can configure by running `sudo usermod -aG docker `. -2. Download the latest **Debian install package** from the [Appsody releases page](https://github.com/appsody/appsody/releases). The file is named `appsody_v.r.m_amd64.deb`, where `v.r.m` indicates the release tag. -3. To install the package, run: - -``` -sudo apt install -f /appsody_v.r.m_amd64.deb -``` -Where `` is the fully qualified path to the package. - -That's all there is to it! You can now follow our [Quick Start](/docs/getting-started/quick-start) instructions to create your first containerized development environment with a running *Hello World!* application. - -Alternatively, if you would like to build the binaries from source code, please take a look at [Building from Source] (https://github.com/appsody/appsody/blob/master/build.md). - -## Installing on RHEL - -Follow these steps: - -1. Your user account must be a member of the `docker` group, which you can configure by running `sudo usermod -aG docker `. -2. Download the latest **RPM install package** from the [Appsody releases page](https://github.com/appsody/appsody/releases). The file is named `appsody-v.r.m-1.x86_64.rpm`, where `v.r.m` indicates the release tag. -3. To install the package, run: - -``` -sudo yum install /appsody-v.r.m-1.x86_64.rpm -``` - -Where `` is the fully qualified path to the package. - -That's all there is to it! You can now follow our [Quick Start](/docs/getting-started/quick-start) instructions to create your first containerized development environment with a running *Hello World!* application. - -## Installing on Windows - -> Appsody runs only on Windows 10 Professional and Windows 10 Enterprise editions. If you are running Windows 10 Enterprise with authentication through Azure Active Directory, please follow the additional instructions in the page [Appsody and Docker Desktop on Windows 10](/docs/docker-windows-aad). - -Follow these steps: - -1. Create a directory for Appsody on your Windows 10 system. -2. Download the **Appsody binaries for Windows** from the [Appsody releases page](https://github.com/appsody/appsody/releases) into the directory. The file is named `appsody-v.r.m-windows.tar.gz`, where `v.r.m` indicates the release tag. -3. Extract the files by running `tar -xvf appsody-v.r.m-windows.tar.gz`. - -> If you choose to extract the files using a GUI tool you may have to extract the `appsody-v.r.m-windows.tar.gz` file and extract the extracted `appsody-v.r.m-windows.tar` file afterwards. - -4. To install Appsody, run the following setup command: - -``` -appsody-setup.bat -``` - -That's all there is to it! You can now follow our [Quick Start](/docs/getting-started/quick-start) instructions to create your first containerized development environment with a running *Hello World!* application. - -Note that `appsody-setup.bat` does the following environment changes: -* It modifies your **PATH** environment variable - adding the folder where Appsody is installed to it - on the current command prompt session -* It creates an **APPSODY_PATH** [User Environment Variable](https://docs.microsoft.com/en-us/windows/win32/shell/user-environment-variables), set to the folder where Appsody is installed. -* Updates the **Path** User Environment Variable, appending **APPSODY_PATH** to it. - -This makes it possible for your to run Appsody from the same session you used to install it, or from any command prompt session you may open in the future. - -## Running Appsody with SELinux -If you are running Security-Enhanced Linux, you may experience problems when running Appsody, because the Docker daemon - although it runs as `root` - may not be able to access the folders that are mounted from the host file system. - -The manifestation of these problems include errors such as those reported in the snippet below. -``` -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' -``` - -In order to check whether you have SELinux enabled and enforcing its policies, you can run `sestatus`. The output of this command includes the `Current Mode` of SELinux. If it is set to `enforcing`, and you see errors similar to those in the snippet above, you may need to change your SELinux configuration. - -This can be done by exempting the folders mounted by the stacks you are using, through the following command: -``` -chcon -Rt svirt_sandbox_file_t -``` -You may 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. - -In general - however - you should be required to run the command at most twice: -* For your home directory -* For the directory where your Appsody project is located (assuming this isn't under your home) - -If you are unsure about which directories are mounted by the stack you are using, you can inspect the output of the `appsody run` command, and look at the `-v` parameters in the `docker run` command. For example: -``` -[ibmadmin@naval1 my-project]$ appsody run -Running development environment... -Running command: docker[pull appsody/nodejs-express:0.2] -Running command: docker[run --rm -p 3000:3000 -p 9229:9229 --name my-project-dev -v /home/ibmadmin/appsody/my-project/:/project/user-app -v my-project-deps:/project/user-app/node_modules -v appsody-controller-0.3.1:/.appsody/appsody-controller -t --entrypoint /.appsody/appsody-controller appsody/nodejs-express:0.2 --mode=run] -``` -In the example above, there is one binding mount: -``` -/home/ibmadmin/appsody/my-project/ -``` -In this case, whitelisting the home directory (`/home/ibmadmin`) would be sufficient. - -# Upgrading Appsody -Here we cover the steps to upgrade Appsody on your system. - -## Upgrading on macOS -To upgrade Appsody on your system, run the following command: -``` -brew upgrade appsody -``` -This command checks the installed Appsody folder for outdated installations and replaces them with newer versions. - -## Upgrading on Ubuntu -To upgrade Appsody on your system, follow these steps: -1) Download the most recently released **Debian install package** from the [Appsody releases page](https://github.com/appsody/appsody/releases). The file is named `appsody_v.r.m_amd64.deb`, where v.r.m is the release number. -2) Open your terminal and enter the directory in which you downloaded the file. -3) Run the following command: -``` -sudo apt upgrade -f ./appsody_v.r.m_amd64.deb -y -``` -> The command uses `./` otherwise it will not work. - -## Upgrading on RHEL -To upgrade Appsody on your system, follow these steps: -1) Download the latest **RPM install package** from the [Appsody releases page](https://github.com/appsody/appsody/releases). The file is named `appsody-v.r.m-1.x86_64.rpm`, where v.r.m is the release number. -2) Open your terminal and enter the directory in which you downloaded the file. -3) Run the following command: -``` -sudo yum update appsody-v.r.m-1.x86_64.rpm -y -``` - -## Upgrading on Windows -To upgrade Appsody on your system, follow these steps: -1) Download the **Appsody binaries for Windows** from [Appsody releases page](https://github.com/appsody/appsody/releases). The file is named `appsody-v.r.m-windows.tar.gz`, where `v.r.m` indicates the release tag. -2) Move the file to the directory where you stored the existing Appsody binaries. -3) Untar the file there: `tar -xvf appsody-v.r.m-windows.tar.gz`. - -> If you choose to extract the files using a GUI tool you may have to extract the `appsody-v.r.m-windows.tar.gz` file and extract the extracted `appsody-v.r.m-windows.tar` file afterwards. - -# Uninstalling Appsody -Here we cover the steps to uninstalling Appsody on your system. - -## Uninstalling on macOS -To uninstall Appsody, run the following command: - ``` - brew uninstall appsody - ``` -You may also want to remove the `.appsody` directory that gets created under your home directory: `rm -rf ~/.appsody`. - -## Uninstalling on Ubuntu -To uninstall Appsody, run the following command: -``` -sudo apt remove appsody -``` -You may also want to remove the `.appsody` directory that gets created under your home directory: `rm -rf ~/.appsody`. - -## Uninstalling on RHEL -To uninstall Appsody, run the following command: -``` -sudo yum remove appsody -``` -You may also want to remove the `.appsody` directory that gets created under your home directory: `rm -rf ~/.appsody`. - -## Uninstalling on Windows -To uninstall Appsody from your Windows workstation: -* Delete the directory where you extracted the binaries -* Remove the `.appsody` directory that gets created under your home folder -* Remove **APPSODY_PATH** from the **Path** User Variable entry (see [Modifying the PATH on Windows 10](https://www.architectryan.com/2018/03/17/add-to-the-path-on-windows-10/)). You may also want to remove the **APPSODY_PATH** variable, from the same dialog used to update the Path variable. diff --git a/content/docs/installing/installing-appsody.md b/content/docs/installing/installing-appsody.md new file mode 100644 index 000000000..c522988b2 --- /dev/null +++ b/content/docs/installing/installing-appsody.md @@ -0,0 +1,51 @@ +--- +title: Overview - Installing Appsody +--- + +# Installing Appsody + +The easiest way to install Appsody is to use the installers, which are available for all supported platforms, except Windows®. + +## Platforms + +Appsody supports the following operating systems on x86 hardware: + + - macOS® + - Ubuntu + - Red Hat Enterprise Linux (RHEL) + - Windows® - Windows 10 Professional and Windows 10 Enterprise editions only + +## Requirements + +Appsody depends on Docker so ensure that you have [Docker](https://docs.docker.com/get-started/) installed and the Docker daemon is running on your system. Prerequisites specific to each operating system are provided within the links in the following section. + +## Using installers + +Installation steps are covered in the following sections: + + - [Installing on macOS](/docs/installing/macos) + - [Installing on RHEL](/docs/installing/rhel) + - [Installing on Ubuntu](/docs/installing/ubuntu) + +Appsody does not have an installer package for Windows, so to install Appsody on that operating system follow: + + - [Installing on Windows](/docs/installing/windows) + +## Alternative install methods + +### Appsody binaries + +If you prefer not to use an installer, you can install Appsody by using a binary file. These instructions are for installing on macOS, Ubuntu, and RHEL. For Windows, follow [Installing on Windows](/docs/installing/windows): + +1. Go to the [Appsody Releases page](https://github.com/appsody/appsody/releases), scroll to the release you want and download the file that is appropriate to your operating system. For example, on macOS: `appsody_v.r.m-darwin-amd64.tar.gz`, where `v.r.m` indicates the release tag. + +2. Extract the files by running: +``` +tar -xvf appsody_v.r.m-darwin-amd64.tar.gz +``` + +3. This is a nested zip file so if you use a GUI you might have to unzip twice. + +### Building Appsody from source + +If you would like to build Appsody from the source code, look at [Building from Source](https://github.com/appsody/appsody/blob/master/build.md). diff --git a/content/docs/installing/macos.md b/content/docs/installing/macos.md new file mode 100644 index 000000000..db3a68e36 --- /dev/null +++ b/content/docs/installing/macos.md @@ -0,0 +1,47 @@ +--- +title: Installing on macOS +--- + +# Installing on macOS + +The easiest way to install and uninstall Appsody on macOS is to use [Homebrew](#installing-with-homebrew). + +## Prerequisites + +If you don't have the Xcode Command Line Tools installed on your system, install them by running: + +``` +xcode-select --install +``` + +If you are installing with Homebrew and don't have Homebrew installed, you can install it by running: + +``` +/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" +``` + +## Installing with Homebrew + +To install Appsody with Homebrew, run: + +``` +brew install appsody/appsody/appsody +``` + +You can now follow the [Quick Start](/docs/getting-started/quick-start) instructions to create your first containerized development environment with a running *Hello World!* application. + +# Upgrading + +If you installed Appsody using Homebrew, you can upgrade Appsody on your system by running the following command: +``` +brew upgrade appsody +``` +This command checks the installed Appsody folder for outdated installations and replaces them with newer versions. + +# Uninstalling + +To uninstall Appsody, run the following command: +``` +brew uninstall appsody +``` +You might also want to remove the `.appsody` directory that gets created, by default, within your home directory: `rm -rf ~/.appsody`. diff --git a/content/docs/installing/rhel.md b/content/docs/installing/rhel.md new file mode 100644 index 000000000..86189d38d --- /dev/null +++ b/content/docs/installing/rhel.md @@ -0,0 +1,47 @@ +--- +title: Installing on RHEL +--- + +# Installing on RHEL + +The easiest way to install and uninstall Appsody on Red Hat Enterprise Linux is to use yum. + +## Prerequisites + +To avoid permissions problems on Linux hosts, your user account must be a member of the `docker` group, as detailed in the [Docker documentation](https://docs.docker.com/install/linux/linux-postinstall/), which you can configure by running: +``` +sudo usermod -aG docker +``` + +## Installing + +Follow these steps: + +1. Download the latest RPM install package from the [Appsody releases page](https://github.com/appsody/appsody/releases). The file is named `appsody-v.r.m-1.x86_64.rpm`, where `v.r.m` indicates the release tag. +2. To install the package, run: + +``` +sudo yum install /appsody-v.r.m-1.x86_64.rpm +``` + +where `` is the fully qualified path to the package. + +You can now follow the [Quick Start](/docs/getting-started/quick-start) instructions to create your first containerized development environment with a running *Hello World!* application. + +# Upgrading + +To upgrade Appsody on your system, follow these steps: +1. Download the latest RPM install package from the [Appsody releases page](https://github.com/appsody/appsody/releases). The file is named `appsody-v.r.m-1.x86_64.rpm`, where `v.r.m` is the release number. +2. Open your terminal and change into the directory that contains your downloaded file. +3. Run the following command: +``` +sudo yum update appsody-v.r.m-1.x86_64.rpm -y +``` + +# Uninstalling + +To uninstall Appsody, run the following command: +``` +sudo yum remove appsody +``` +You might also want to remove the `.appsody` directory that gets created under your home directory: `rm -rf ~/.appsody`. diff --git a/content/docs/installing/ubuntu.md b/content/docs/installing/ubuntu.md new file mode 100644 index 000000000..fd4af6d61 --- /dev/null +++ b/content/docs/installing/ubuntu.md @@ -0,0 +1,46 @@ +--- +title: Installing on Ubuntu +--- + +# Installing on Ubuntu + +The easiest way to install and uninstall Appsody on Ubuntu is to use `apt`. + +## Prerequisites + +To avoid permissions problems on Linux hosts, your user account must be a member of the `docker` group, as detailed in the [Docker documentation](https://docs.docker.com/install/linux/linux-postinstall/), which you can configure by running: +``` +sudo usermod -aG docker +``` + +## Installing + +Follow these steps: + +1. Download the latest Debian install package from the [Appsody releases page](https://github.com/appsody/appsody/releases). The file is named `appsody_v.r.m_amd64.deb`, where `v.r.m` indicates the release tag. +2. To install the package, run: + +``` +sudo apt install -f /appsody_v.r.m_amd64.deb +``` +where `` is the fully qualified path to the package. + +You can now follow the [Quick Start](/docs/getting-started/quick-start) instructions to create your first containerized development environment with a running *Hello World!* application. + +# Upgrading + +To upgrade Appsody on your system, follow these steps: +1. Download the latest Debian install package from the [Appsody releases page](https://github.com/appsody/appsody/releases). The file is named `appsody_v.r.m_amd64.deb`, where `v.r.m` is the release tag. +2. Open your terminal and change into the directory that contains your downloaded file. +3. Run the following command: +``` +sudo apt upgrade -f ./appsody_v.r.m_amd64.deb -y +``` + +# Uninstalling + +To uninstall Appsody, run the following command: +``` +sudo apt remove appsody +``` +You might also want to remove the `.appsody` directory that gets created under your home directory: `rm -rf ~/.appsody`. diff --git a/content/docs/installing/windows.md b/content/docs/installing/windows.md new file mode 100644 index 000000000..f74c66254 --- /dev/null +++ b/content/docs/installing/windows.md @@ -0,0 +1,35 @@ +--- +title: Installing on Windows +--- + +# Installing on Windows + +> Appsody runs only on Windows 10 Professional and Windows 10 Enterprise editions. If you are running Windows 10 Enterprise with authentication through Azure Active Directory, follow the additional instructions in [Appsody and Docker Desktop on Windows 10](/docs/docker-windows-aad). + +Follow these steps: + +1. Create a directory to install Appsody in. +2. Download the Appsody binaries for Windows from the [Appsody releases page](https://github.com/appsody/appsody/releases) into your newly created directory. The file is named `appsody-v.r.m-windows.tar.gz`, where `v.r.m` indicates the release tag. +3. To extract the files run: `tar -xvf appsody-v.r.m-windows.tar.gz`. +4. This is a nested zip file so if you use a GUI you might have to unzip twice. +5. Run the following setup script to create the `APPSODY_PATH` environment variable, set it to the directory where Appsody is installed, and configure your `PATH` environment variable: +``` +appsody-setup.bat +``` + +You can now follow the [Quick Start](/docs/getting-started/quick-start) instructions to create your first containerized development environment with a running *Hello World!* application. + +# Upgrading + +To upgrade Appsody on your system, follow these steps: +1. Download the Appsody binaries for Windows from [Appsody releases page](https://github.com/appsody/appsody/releases). The file is named `appsody-v.r.m-windows.tar.gz`, where `v.r.m` indicates the release tag. +2. Move the file to the directory where you stored the existing Appsody binaries. +3. To extract the files run: `tar -xvf appsody-v.r.m-windows.tar.gz`. +4. This is a nested zip file so if you use a GUI you might have to unzip twice. + +# Uninstalling + +To uninstall Appsody: +1. Delete the directory where you installed Appsody. +2. You might want to remove the `.appsody` directory that gets created under your home directory: `rm -rf ~/.appsody`. +3. Remove `APPSODY_PATH` from the `PATH` environment variable (see [Modifying the PATH on Windows 10](https://www.architectryan.com/2018/03/17/add-to-the-path-on-windows-10/)). You might also want to remove the `APPSODY_PATH` variable. diff --git a/content/docs/sidebar.yaml b/content/docs/sidebar.yaml index 80f54cb4c..039a3ba31 100644 --- a/content/docs/sidebar.yaml +++ b/content/docs/sidebar.yaml @@ -1,11 +1,19 @@ - title: Overview path: /docs -- title: Getting Started +- title: Installing items: - - title: Installation - path: /docs/getting-started/installation - - title: Quick Start - path: /docs/getting-started/quick-start + - title: Overview + path: /docs/installing/installing-appsody + - title: macOS + path: /docs/installing/macos + - title: Ubuntu + path: /docs/installing/ubuntu + - title: RHEL + path: /docs/installing/rhel + - title: Windows + path: /docs/installing/windows +- title: Getting Started + path: /docs/getting-started - title: Using Appsody items: - title: Initializing Projects diff --git a/gatsby-node.js b/gatsby-node.js index 65e934ce8..f1cd8eeff 100644 --- a/gatsby-node.js +++ b/gatsby-node.js @@ -18,6 +18,20 @@ exports.createPages = ({ actions, graphql }) => { // Redirects section + // The install doc was split and placed under its own installing menu + createRedirect({ + fromPath: `/docs/getting-started/installation`, + toPath: `/docs/installing/installing-appsody`, + isPermanent: true + }); + + // The getting-started doc was moved to the top level menu + createRedirect({ + fromPath: `/docs/getting-started/quick-start`, + toPath: `/docs/getting-started`, + isPermanent: true + }); + // The modify doc was merged with the create doc to form a develop doc createRedirect({ fromPath: `/docs/stacks/modify`,