Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Restructure the restructured Terminus Install page #9406

Merged
merged 9 commits into from
Feb 4, 2025
Merged

Restructure the restructured Terminus Install page #9406

Changes from 6 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
229adb0
Restructure the restructure
rachelwhitton Jan 30, 2025
964a439
Align headers
rachelwhitton Jan 30, 2025
be45aa7
Align with updated header
rachelwhitton Jan 30, 2025
5965e0d
Simpler headers, combine install and update subsections
rachelwhitton Jan 30, 2025
9d0dfff
Linux instead of ubuntu
rachelwhitton Jan 30, 2025
fb98612
Combine macos intro copy
rachelwhitton Jan 30, 2025
bfbfeff
Add alert for wls install pre-req
rachelwhitton Jan 31, 2025
c82ed78
Update source/content/terminus/02-install.md
rachelwhitton Feb 4, 2025
81e7ba4
Update source/content/terminus/02-install.md
rachelwhitton Feb 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
140 changes: 54 additions & 86 deletions source/content/terminus/02-install.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
rachelwhitton marked this conversation as resolved.
Show resolved Hide resolved

### 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
<Accordion title="Incompatible Operating Systems" id="incompatible-os" icon="info-sign">
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
</Accordion>

Terminus requires the following:
rachelwhitton marked this conversation as resolved.
Show resolved Hide resolved
- 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:
Expand All @@ -83,68 +51,68 @@ 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.

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/).
## 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.

1. Use your machine token to authenticate into Terminus, replacing `<[email protected]>` and `<machine_token>`:
Install Terminus by running the command below:

```bash{promptUser: user}
terminus auth:login --email=<[email protected]> --machine-token=<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:
<hr/>

```bash{promptUser: user}
terminus auth:login --email <[email protected]>
```
Update to the newest version of the [Homebrew installation](#macos) 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 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.

## Updating Terminus
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

<Alert title="Note" type="info">
```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
```
<hr/>

Terminus uses [Semantic versioning](https://semver.org/). Be sure to fully test compatibility with existing configurations before upgrading to new major releases.
Update the [standalone Terminus PHAR](#windows-and-linux) installation to the newest version by running the command below:

</Alert>
```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 `<[email protected]>` and `<machine_token>`:

### Update Standalone Terminus PHAR
```bash{promptUser: user}
terminus auth:login --email=<[email protected]> --machine-token=<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 <[email protected]>
```

### 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)