From fda00ef9e22f1cda23d471eabf7e872ab09d7525 Mon Sep 17 00:00:00 2001 From: Steve Persch Date: Wed, 29 Jan 2025 14:53:40 -0600 Subject: [PATCH 1/7] restructuring terminus install and update instructions --- source/content/terminus/02-install.md | 147 ++++++++------------------ 1 file changed, 46 insertions(+), 101 deletions(-) diff --git a/source/content/terminus/02-install.md b/source/content/terminus/02-install.md index a1aeee9d2a..3a7cde5b21 100644 --- a/source/content/terminus/02-install.md +++ b/source/content/terminus/02-install.md @@ -16,15 +16,15 @@ product: [terminus] integration: [--] --- -This section provides information on how to install and authenticate Terminus. +This section provides information on how to install, authenticate, and update Terminus. -Refer to [Current Terminus Release, Changelog, and Updates](/terminus/updates) if you are looking for instructions on **how to update Terminus** for your specific operating system. +## 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 +### Compatible Operating Systems Terminus has been tested on the following platforms: @@ -32,52 +32,20 @@ Terminus has been tested on the following platforms: - Windows 10 – WSL 2 Ubuntu 20.0 - Ubuntu 20.0 – this would include Ubuntu under Docker or VirtualBox -### 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 - -## Terminus Requirements - -### Package Manager - -**Ubuntu/WinWSL-Ubuntu** +### Homebrew Package Manager (Recommended for MacOS Users) -- [apt](https://ubuntu.com/server/docs/package-management) - -**MacOS** - -- [Homebrew](https://brew.sh/) - -### Required Packages - -- 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: - - mbstring - - XML - - [cURL](https://secure.php.net/manual/en/curl.setup.php) - - [CLI](http://www.php-cli.com) -- [Composer](https://getcomposer.org/download/) -- [Git](https://help.github.com/articles/set-up-git/) - - This may be needed for the plugin manager component. -- OpenSSH 7.8 or later - - 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. +The Terminus application is published to [Homebrew](https://brew.sh/), a package manager for MacOS. -## Install Terminus +Run the command below to install Terminus: -There are several ways to install Terminus, depending on your use case: +```bash{promptUser: user} +brew install pantheon-systems/external/terminus +``` -- Self-contained Terminus executable:[install terminus.phar](#standalone-terminus-phar) -- Mac:[install using Homebrew](#homebrew-installation) -- Contribute to the Terminus project: [download and install](https://github.com/pantheon-systems/terminus#installing-with-git) from the Git repository +### Direct Installation of Standalone Terminus PHAR (Recommended for Ubuntu and WSL Users) -### Standalone Terminus PHAR +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: @@ -95,23 +63,36 @@ The commands below will: sudo ln -s ~/terminus/terminus /usr/local/bin/terminus ``` -### MacOS Homebrew Installation +### Install from Git -The Terminus application is published to [Homebrew](https://brew.sh/). +If you are a developer contributoring to Terminus, you can install it from its [Git repository](https://github.com/pantheon-systems/terminus). -Run the command below to install Terminus: +### Requirements -```bash{promptUser: user} -brew install pantheon-systems/external/terminus -``` +- 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: + - mbstring + - XML + - [cURL](https://secure.php.net/manual/en/curl.setup.php) + - [CLI](http://www.php-cli.com) +- [Composer](https://getcomposer.org/download/) +- [Git](https://help.github.com/articles/set-up-git/) + - This may be needed for the plugin manager component. +- OpenSSH 7.8 or later + - 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. -### Ubuntu/WinWSL-Ubuntu Installation +### Incompatible Operating Systems -Follow the steps in the [Standalone Terminus PHAR](/terminus/install#standalone-terminus-phar) section. +Terminus does not work with the following platforms: -## Authenticate +- 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 -### Machine Token +## 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. @@ -133,33 +114,16 @@ You must log in with a machine token after the installation completes. A machine 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. -## Update Standalone Terminus -You can update the [standalone Terminus PHAR](/terminus/install#standalone-terminus-phar) installation to the newest version with the command below. +## Updating Terminus - + -The `self:update` command is only available for the standalone Terminus installation. Refer to the [command documentation](/terminus/commands/self-update) for available options. +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} -terminus self:update -``` - -## Update Terminus Installer PHAR - -You can update the Composer-managed version of Terminus that was installed with the [Terminus Installer PHAR](/terminus/install#terminus-installer-phar). - -1. Navigate to the directory where Terminus was originally installed. - -1. Run the following command: - - ```bash{promptUser: user} - curl -O https://raw.githubusercontent.com/pantheon-systems/terminus-installer/master/builds/installer.phar && php installer.phar update - ``` - -### Update Terminus Homebrew Installation +### Homebrew Package Manager (Recommended for MacOS Users) You can update to the newest version of the [Homebrew installation](/terminus/install#homebrew-installation) by running the command below: @@ -167,37 +131,18 @@ You can update to the newest version of the [Homebrew installation](/terminus/in brew upgrade pantheon-systems/external/terminus ``` - - -Terminus uses [Semantic versioning](https://semver.org/). Be sure to fully test compatibility with existing configurations before upgrading to new major releases. - - - -## Update Terminus with Plugin - -Use the [`self:plugin:update` command](/terminus/commands/self-plugin-update) if you use the Terminus plugin manager. - -## Troubleshooting - -### Nothing to install or update - -For Composer-managed Terminus installations, if the update command above returns an output that indicates no updates were found: +### Update Standalone Terminus PHAR -1. Delete the existing Terminus version (e.g. `$HOME/terminus`). +You can update the [standalone Terminus PHAR](/terminus/install#standalone-terminus-phar) installation to the newest version with the command below. -1. Re-run the install command: +```bash{promptUser: user} +terminus self:update +``` - ```bash{promptUser: user} - rm -rf $HOME/terminus - mkdir $HOME/terminus - cd $HOME/terminus - curl -O https://raw.githubusercontent.com/pantheon-systems/terminus-installer/master/builds/installer.phar - php installer.phar install - ``` -### Self:update not defined +## Installing and Updating Terminus Plugins -The `self:update` command is only available for standalone Terminus installed using the [standalone Terminus PHAR](/terminus/install#standalone-terminus-phar). If `self:update` returns a not defined error, use the [Terminus Installer PHAR](#update-terminus-installer-phar) update instructions above. +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 From 4380df8c03a7f79a82c9faf1d6ad4047fb360dfe Mon Sep 17 00:00:00 2001 From: Rachel Date: Thu, 30 Jan 2025 12:35:56 -0600 Subject: [PATCH 2/7] Update source/content/terminus/02-install.md Co-authored-by: Chris Reynolds --- source/content/terminus/02-install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/content/terminus/02-install.md b/source/content/terminus/02-install.md index 3a7cde5b21..23b01f9b93 100644 --- a/source/content/terminus/02-install.md +++ b/source/content/terminus/02-install.md @@ -16,7 +16,7 @@ product: [terminus] integration: [--] --- -This section provides information on how to install, authenticate, and update Terminus. +This page provides information on how to install, authenticate, and update Terminus. ## Installing Terminus From deb9db55cf82d1167efe8efabdec0328e17a4030 Mon Sep 17 00:00:00 2001 From: Rachel Date: Thu, 30 Jan 2025 12:36:06 -0600 Subject: [PATCH 3/7] Update source/content/terminus/02-install.md Co-authored-by: Chris Reynolds --- source/content/terminus/02-install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/content/terminus/02-install.md b/source/content/terminus/02-install.md index 23b01f9b93..98f5d4dde3 100644 --- a/source/content/terminus/02-install.md +++ b/source/content/terminus/02-install.md @@ -20,7 +20,7 @@ This page provides information on how to install, authenticate, and update Termi ## 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. +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. From 424bc2da187508e549282c5fa3c5fa0ceeb18eb8 Mon Sep 17 00:00:00 2001 From: Rachel Date: Thu, 30 Jan 2025 12:43:00 -0600 Subject: [PATCH 4/7] Update source/content/terminus/02-install.md Co-authored-by: Chris Reynolds --- source/content/terminus/02-install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/content/terminus/02-install.md b/source/content/terminus/02-install.md index 98f5d4dde3..b50335d8c0 100644 --- a/source/content/terminus/02-install.md +++ b/source/content/terminus/02-install.md @@ -42,7 +42,7 @@ Run the command below to install Terminus: brew install pantheon-systems/external/terminus ``` -### Direct Installation of Standalone Terminus PHAR (Recommended for Ubuntu and WSL Users) +### 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 prefer not to use Homebrew. From d5fe804d8067039c2a4c8f76ea9e4d7fb81009b9 Mon Sep 17 00:00:00 2001 From: Rachel Date: Thu, 30 Jan 2025 12:43:07 -0600 Subject: [PATCH 5/7] Update source/content/terminus/02-install.md Co-authored-by: Chris Reynolds --- source/content/terminus/02-install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/content/terminus/02-install.md b/source/content/terminus/02-install.md index b50335d8c0..b2f8264fac 100644 --- a/source/content/terminus/02-install.md +++ b/source/content/terminus/02-install.md @@ -45,7 +45,7 @@ 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 prefer not to use Homebrew. +This technique is also viable for MacOS users who are not using Homebrew. The commands below will: From a881402d5428d177926ac52da8424b6397fcd419 Mon Sep 17 00:00:00 2001 From: Rachel Date: Thu, 30 Jan 2025 12:43:17 -0600 Subject: [PATCH 6/7] Update source/content/terminus/02-install.md Co-authored-by: Chris Reynolds --- source/content/terminus/02-install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/content/terminus/02-install.md b/source/content/terminus/02-install.md index b2f8264fac..a11ec9718f 100644 --- a/source/content/terminus/02-install.md +++ b/source/content/terminus/02-install.md @@ -128,7 +128,7 @@ Terminus uses [Semantic versioning](https://semver.org/). Be sure to fully test You can update to the newest version of the [Homebrew installation](/terminus/install#homebrew-installation) by running the command below: ```bash{promptUser: user} -brew upgrade pantheon-systems/external/terminus +brew upgrade terminus ``` ### Update Standalone Terminus PHAR From dc825217181c4a03d399f1af09b95946c251b187 Mon Sep 17 00:00:00 2001 From: Rachel Date: Tue, 4 Feb 2025 13:06:49 -0600 Subject: [PATCH 7/7] Restructure the restructured Terminus Install page (#9406) * Restructure the restructure * Align headers * Align with updated header * Simpler headers, combine install and update subsections * Linux instead of ubuntu * Combine macos intro copy * Add alert for wls install pre-req * Update source/content/terminus/02-install.md Co-authored-by: Chris Reynolds * Update source/content/terminus/02-install.md Co-authored-by: Chris Reynolds --------- Co-authored-by: Chris Reynolds --- source/content/terminus/02-install.md | 144 +++++++++++--------------- 1 file changed, 59 insertions(+), 85 deletions(-) diff --git a/source/content/terminus/02-install.md b/source/content/terminus/02-install.md index a11ec9718f..5a8710157e 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 +- Windows 10 (WSL 2 Ubuntu 20.0+) +- Ubuntu 20.0 (Including Ubuntu under Docker or VirtualBox) - ```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,74 @@ 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 +[Homebrew](https://brew.sh/), a package manager for MacOS, is the recommended installation method for MacOS. However, the method [described below](#windows-and-linux) for Windows 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/). +Install Terminus by running the command below: -1. Use your machine token to authenticate into Terminus, replacing `` and ``: - - ```bash{promptUser: user} - terminus auth:login --email= --machine-token= - ``` - - - 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 auth:login --email - ``` +```bash{promptUser: user} +brew install pantheon-systems/external/terminus +``` -### 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. +Update to the newest version of the [Homebrew installation](#macos) by running the command below: +```bash{promptUser: user} +brew upgrade terminus +``` -## Updating Terminus +### Windows and Linux +Installing Terminus with a PHAR (a stand-alone executable PHP archive) is recommended for Linux and Windows users. This technique is also viable for MacOS users who prefer not to use Homebrew. - + -Terminus uses [Semantic versioning](https://semver.org/). Be sure to fully test compatibility with existing configurations before upgrading to new major releases. +[Terminus compatibility](#compatibility-and-requirements) for Windows requires installing the Windows Subsystem for Linux (WSL). [Install WSL](https://learn.microsoft.com/en-us/windows/wsl/) before proceeding to the steps below. -### Homebrew Package Manager (Recommended for MacOS Users) - -You can update to the newest version of the [Homebrew installation](/terminus/install#homebrew-installation) by running the command below: +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} -brew upgrade terminus +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 ``` +
-### Update Standalone Terminus PHAR - -You can update the [standalone Terminus PHAR](/terminus/install#standalone-terminus-phar) installation to the newest version with the command below. +Update the [standalone Terminus PHAR](#windows-and-linux) installation to the newest version by running the command below: ```bash{promptUser: user} terminus self:update ``` +## 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. + +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/). + +1. Use your machine token to authenticate into Terminus, replacing `` and ``: -## Installing and Updating Terminus Plugins + ```bash{promptUser: user} + terminus auth:login --email= --machine-token= + ``` -Terminus can be extended with plugins. Refer to the [Terminus Plugin Directory](https://pantheon.io/docs/terminus/plugins/) for a list of available plugins. +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: -## More Resources +```bash{promptUser: user} +terminus auth:login --email +``` + +### SSH Authentication (Optional, but recommended) + +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)