From 229adb0e9b779706469b4605efa9f0149950de07 Mon Sep 17 00:00:00 2001 From: Rachel Whitton Date: Thu, 30 Jan 2025 13:30:10 -0600 Subject: [PATCH] Restructure the restructure --- source/content/terminus/02-install.md | 140 ++++++++++---------------- 1 file changed, 55 insertions(+), 85 deletions(-) diff --git a/source/content/terminus/02-install.md b/source/content/terminus/02-install.md index a11ec9718f..aac5570754 100644 --- a/source/content/terminus/02-install.md +++ b/source/content/terminus/02-install.md @@ -14,61 +14,29 @@ cms: [drupal, wordpress] audience: [development] product: [terminus] integration: [--] +showtoc: true --- This page provides information on how to install, authenticate, and update Terminus. -## Installing Terminus - -Terminus is available for MacOS and Linux. Windows 10+ users can install the [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10), and then install Terminus in the Linux shell. - -Some Terminus commands use SSH authentication. You may want to [generate and add SSH keys](/ssh-keys/) to your account before you continue. - -### Compatible Operating Systems - +## Compatibility and Requirements Terminus has been tested on the following platforms: - MacOS - Windows 10 – WSL 2 Ubuntu 20.0 - Ubuntu 20.0 – this would include Ubuntu under Docker or VirtualBox -### Homebrew Package Manager (Recommended for MacOS Users) - -The Terminus application is published to [Homebrew](https://brew.sh/), a package manager for MacOS. - -Run the command below to install Terminus: - -```bash{promptUser: user} -brew install pantheon-systems/external/terminus -``` - -### Direct Installation of Standalone PHAR (Recommended for Ubuntu and WSL Users) - -Installing Terminus with a PHAR (a stand-alone executable PHP archive) is recommended for Ubuntu and Windows Subsystem for Linux (WSL) users. -This technique is also viable for MacOS users who are not using Homebrew. - -The commands below will: - -- Create a `terminus` folder in your home directory (`~/`) -- Get the latest release tag of Terminus -- Download and save the release as `~/terminus/terminus` -- Make the file executable -- Add a symlink to your local `bin` directory for the Terminus executable - - ```bash{promptUser: user} - mkdir -p ~/terminus && cd ~/terminus - curl -L https://github.com/pantheon-systems/terminus/releases/download/3.6.1/terminus.phar --output terminus - chmod +x terminus - ./terminus self:update - sudo ln -s ~/terminus/terminus /usr/local/bin/terminus - ``` - -### Install from Git + +Terminus does not work with the following platforms: -If you are a developer contributoring to Terminus, you can install it from its [Git repository](https://github.com/pantheon-systems/terminus). +- Windows 10 – Command Line +- Windows 10 – Git Bash (MingW) +- Ubuntu 18.0 and earlier versions +- Linux system with coreutils equal to or less than 8.28 -### Requirements + +Terminus requires the following: - PHP Version 7.4 or later - You can check your PHP version by running `php -v` from a terminal application. - You must have the [php-xml extension](https://secure.php.net/manual/en/dom.setup.php) for: @@ -83,68 +51,70 @@ If you are a developer contributoring to Terminus, you can install it from its [ - You can check your OpenSSH version by running `ssh -V` from a terminal application. - This package is required for executing nested Drush or WP-CLI commands. -### Incompatible Operating Systems - -Terminus does not work with the following platforms: - -- Windows 10 – Command Line -- Windows 10 – Git Bash (MingW) -- Ubuntu 18.0 and earlier versions -- Linux system with coreutils equal to or less than 8.28 - -## Authenticating with Terminus - -You must log in with a machine token after the installation completes. A machine token is used to securely authenticate your machine. Machine tokens provide the same access as your username and password, and do not expire. Refer to [Machine Tokens](/machine-tokens/) for more information. +## Installation and Update Methods +### MacOS Terminus Installation +Homebrew is the recommended installation method for MacOS, however the method [described below](#windows-wsl-and-ubuntu-terminus-installation) for Ubuntu and Linux can also be used by MacOS users who are not using Homebrew. -2. [Go to your Personal Settings](/personal-settings), select [Machine Tokens](https://dashboard.pantheon.io/users/#account/tokens/), then [Generate a Machine Token](https://dashboard.pantheon.io/login?destination=%2Fuser#account/tokens/create/terminus/). +The Terminus application is published to [Homebrew](https://brew.sh/), a package manager for MacOS. -1. Use your machine token to authenticate into Terminus, replacing `` and ``: +Install Terminus by running the command below: - ```bash{promptUser: user} - terminus auth:login --email= --machine-token= - ``` +```bash{promptUser: user} +brew install pantheon-systems/external/terminus +``` - - Machine tokens are keyed to the email address associated with your Pantheon user account. Future sessions are authenticated with your email address after a token has been used to authenticate Terminus: +### MacOS Terminus Updates - ```bash{promptUser: user} - terminus auth:login --email - ``` +Update to the newest version of the [Homebrew installation](#macos-terminus-installation) by running the command below: -### SSH Authentication - -Commands that execute remote instructions to tools like Drush or WP-CLI require SSH authentication. Refer to [Generate and Add SSH Keys](/ssh-keys/) to prevent password requests when executing these commands. +```bash{promptUser: user} +brew upgrade terminus +``` +### Windows (WSL) and Ubuntu Terminus Installation -## Updating Terminus +Installing Terminus with a PHAR (a stand-alone executable PHP archive) is recommended for Ubuntu and Windows Subsystem for Linux (WSL) users. This technique is also viable for MacOS users who prefer not to use Homebrew. - +The commands below will: +- Create a `terminus` folder in your home directory (`~/`) +- Get the latest release tag of Terminus +- Download and save the release as `~/terminus/terminus` +- Make the file executable +- Add a symlink to your local `bin` directory for the Terminus executable -Terminus uses [Semantic versioning](https://semver.org/). Be sure to fully test compatibility with existing configurations before upgrading to new major releases. +```bash{promptUser: user} +mkdir -p ~/terminus && cd ~/terminus +curl -L https://github.com/pantheon-systems/terminus/releases/download/3.6.1/terminus.phar --output terminus +chmod +x terminus +./terminus self:update +sudo ln -s ~/terminus/terminus /usr/local/bin/terminus +``` +### Ubuntu and Linux Terminus Updates +You can update the [standalone Terminus PHAR](#windows-wsl-and-ubuntu-terminus-installation) installation to the newest version with the command below. - +```bash{promptUser: user} +terminus self:update +``` -### Homebrew Package Manager (Recommended for MacOS Users) +## Authentication +### Login via Machine Token (Required) +You must log in with a machine token after the installation completes. A machine token is used to securely authenticate your machine. Machine tokens provide the same access as your username and password, and do not expire. Refer to [Machine Tokens](/machine-tokens/) for more information. -You can update to the newest version of the [Homebrew installation](/terminus/install#homebrew-installation) by running the command below: +1. [Go to your Personal Settings](/personal-settings), select [Machine Tokens](https://dashboard.pantheon.io/users/#account/tokens/), then [Generate a Machine Token](https://dashboard.pantheon.io/login?destination=%2Fuser#account/tokens/create/terminus/). -```bash{promptUser: user} -brew upgrade terminus -``` +1. Use your machine token to authenticate into Terminus, replacing `` and ``: -### Update Standalone Terminus PHAR + ```bash{promptUser: user} + terminus auth:login --email= --machine-token= + ``` -You can update the [standalone Terminus PHAR](/terminus/install#standalone-terminus-phar) installation to the newest version with the command below. +Machine tokens are keyed to the email address associated with your Pantheon user account. Future sessions are authenticated with your email address after a token has been used to authenticate Terminus: ```bash{promptUser: user} -terminus self:update +terminus auth:login --email ``` +### SSH Authentication (Optional, but recommended) -## Installing and Updating Terminus Plugins - -Terminus can be extended with plugins. Refer to the [Terminus Plugin Directory](https://pantheon.io/docs/terminus/plugins/) for a list of available plugins. - -## More Resources +Commands that execute remote instructions to tools like Drush or WP-CLI require SSH authentication. Refer to [Generate and Add SSH Keys](/ssh-keys/) to prevent password requests when executing these commands. -- [Developing on Pantheon Directly with SFTP Mode](/guides/sftp) -- [PHP on Pantheon](/guides/php)