From 66e024a0150e9f333d84295d715fc515b7515217 Mon Sep 17 00:00:00 2001 From: David Myers Date: Sun, 23 Aug 2020 04:40:37 -0400 Subject: [PATCH] Update macOS doc (#1865) * Update macOS doc * Small change --- README.md | 15 +++++------ docs/deploy-from-macos.md | 53 +++++++++++++-------------------------- 2 files changed, 24 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 9e29895..ded70d7 100644 --- a/README.md +++ b/README.md @@ -40,19 +40,16 @@ The easiest way to get an Algo server running is to run it on your local system 3. **Install Algo's core dependencies.** Algo requires that **Python 3.6 or later** and at least one supporting package are installed on your system. - - **macOS:** Apple does not provide a suitable version of Python 3 with macOS. Here are two ways to obtain one: - * Use the [Homebrew](https://brew.sh) package manager. After installing Homebrew install Python 3 by running `brew install python3`. - - * Download and install the latest stable [Python package](https://www.python.org/downloads/mac-osx/). Be sure to run the included *Install Certificates* command from Finder. - - See [Deploy from macOS](docs/deploy-from-macos.md) for more detailed information on installing Python 3 on macOS. - - Once Python 3 is installed on your Mac, from Terminal run: + - **macOS:** Catalina includes Python 3 as part of the optional Command Line Developer Tools package. From Terminal run: ```bash - python3 -m pip install --upgrade virtualenv + python3 -m pip install --user --upgrade virtualenv ``` + If prompted, install the Command Line Developer Tools and re-run the above command. + + See [Deploy from macOS](docs/deploy-from-macos.md) for information on installing Python 3 on macOS versions prior to Catalina. + - **Linux:** Recent releases of Ubuntu, Debian, and Fedora come with Python 3 already installed. Make sure your system is up-to-date and install the supporting package(s): * Ubuntu and Debian: ```bash diff --git a/docs/deploy-from-macos.md b/docs/deploy-from-macos.md index ae6d757..ba2855b 100644 --- a/docs/deploy-from-macos.md +++ b/docs/deploy-from-macos.md @@ -2,25 +2,29 @@ While you can't turn a macOS system in an AlgoVPN, you can install the Algo scripts on a macOS system and use them to deploy your AlgoVPN to a cloud provider. -Algo uses [Ansible](https://www.ansible.com) which requires Python 3. macOS does not include a version of Python 3 that you can use with Algo. (It does include an obsolete version of Python 2 installed as `/usr/bin/python` which you should ignore.) - -You'll need to install Python 3 before you can run Algo. Python 3 is available from several different packagers, three of which are listed below. +Algo uses [Ansible](https://www.ansible.com) which requires Python 3. macOS includes an obsolete version of Python 2 installed as `/usr/bin/python` which you should ignore. ## macOS 10.15 Catalina -Catalina comes with `/usr/bin/python3` installed. This file, and certain others like `/usr/bin/git`, start out as stub files that prompt you to install the Developer Command Line Tools the first time you run them. Having `git` installed can be useful but whether or not you choose to install the Command Line Tools you **cannot** use this version of Python 3 with Algo at this time. Instead install one of the versions below. +Catalina comes with Python 3 installed as `/usr/bin/python3`. This file, and certain others like `/usr/bin/git`, start out as stub files that prompt you to install the Command Line Developer Tools package the first time you run them. This is the easiest way to install Python 3 on Catalina. + +Note that Python 3 from Command Line Developer Tools prior to the release for Xcode 11.5 on 2020-05-20 might not work with Algo. If Software Update does not offer to update an older version of the tools you can download a newer version from [here](https://developer.apple.com/download/more/) (Apple ID login required). + +## macOS prior to 10.15 Catalina + +You'll need to install Python 3 before you can run Algo. Python 3 is available from different packagers, two of which are listed below. -## Ansible and SSL Validation +### Ansible and SSL Validation Ansible validates SSL network connections using OpenSSL but macOS includes LibreSSL which behaves differently. Therefore each version of Python below includes or depends on its own copy of OpenSSL. -OpenSSL needs access to a list of trusted CA certificates in order to validate SSL connections. Each packager handles initializing this certificate store differently. If you see the error `CERTIFICATE_VERIFY_FAILED` when running Algo make sure you've followed the packager-specific instructions correctly, and that you're not inadvertently running Catalina's `/usr/bin/python3`. +OpenSSL needs access to a list of trusted CA certificates in order to validate SSL connections. Each packager handles initializing this certificate store differently. If you see the error `CERTIFICATE_VERIFY_FAILED` when running Algo make sure you've followed the packager-specific instructions correctly. -## Install Python 3 +### Choose a packager and install Python 3 Choose one of the packagers below as your source for Python 3. Avoid installing versions from multiple packagers on the same Mac as you may encounter conflicts. In particular they might fight over creating symbolic links in `/usr/local/bin`. -### Option 1: Install using the Homebrew package manager +#### Option 1: Install using the Homebrew package manager If you're comfortable using the command line in Terminal the [Homebrew](https://brew.sh) project is a great source of software for macOS. @@ -28,22 +32,22 @@ First install Homebrew using the instructions on the [Homebrew](https://brew.sh) The install command below takes care of initializing the CA certificate store. -#### Installation +##### Installation ``` brew install python3 ``` After installation open a new tab or window in Terminal and verify that the command `which python3` returns `/usr/local/bin/python3`. -#### Removal +##### Removal ``` brew uninstall python3 ``` -### Option 2: Install a package from Python.org +#### Option 2: Install the package from Python.org -If you don't want to install a package manager you can download a Python package for macOS from [python.org](https://www.python.org/downloads/mac-osx/). +If you don't want to install a package manager you can download the Python package for macOS from [python.org](https://www.python.org/downloads/mac-osx/). -#### Installation +##### Installation Download the most recent version of Python and install it like any other macOS package. Then initialize the CA certificate store from Finder by double-clicking on the file `Install Certificates.command` found in the `/Applications/Python 3.8` folder. @@ -51,7 +55,7 @@ When you double-click on `Install Certificates.command` a new Terminal window wi After installation open a new tab or window in Terminal and verify that the command `which python3` returns either `/usr/local/bin/python3` or `/Library/Frameworks/Python.framework/Versions/3.8/bin/python3`. -#### Removal +##### Removal Unfortunately the python.org package does not include an uninstaller and removing it requires several steps: @@ -60,24 +64,3 @@ Unfortunately the python.org package does not include an uninstaller and removin 3. In Terminal, undo the changes to your `PATH` by running: ```mv ~/.bash_profile.pysave ~/.bash_profile``` 4. In Terminal, remove the dozen or so symbolic links the package created in `/usr/local/bin`. Or just leave them because installing another version of Python will overwrite most of them. - -### Option 3: Install using the Macports package manager - -[Macports](https://www.macports.org) is another command line based package manager like Homebrew. Most users will find Macports far more complex than Homebrew, but developers might find Macports more flexible. If you search for "Macports vs. Homebrew" you will find many opinions. - -First install Macports per the [instructions](https://www.macports.org/install.php). - -In addition to installing Python you'll need to install the package containing the CA certificates. - -#### Installation -``` -sudo port install python38 -sudo port install curl-ca-bundle -``` -After installation open a new tab or window in Terminal and verify that the command `which python3` returns `/opt/local/bin/python3`. - -#### Removal -``` -sudo port uninstall python38 -sudo port uninstall curl-ca-bundle -```