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

restructuring terminus install and update instructions #9401

Merged
merged 7 commits into from
Feb 5, 2025
Merged

restructuring terminus install and update instructions #9401

Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
fda00ef
restructuring terminus install and update instructions
stevector Jan 29, 2025
4380df8
Update source/content/terminus/02-install.md
rachelwhitton Jan 30, 2025
deb9db5
Update source/content/terminus/02-install.md
rachelwhitton Jan 30, 2025
424bc2d
Update source/content/terminus/02-install.md
rachelwhitton Jan 30, 2025
d5fe804
Update source/content/terminus/02-install.md
rachelwhitton Jan 30, 2025
a881402
Update source/content/terminus/02-install.md
rachelwhitton Jan 30, 2025
dc82521
Restructure the restructured Terminus Install page (#9406)
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
147 changes: 46 additions & 101 deletions source/content/terminus/02-install.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,68 +16,36 @@ 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.
rachelwhitton marked this conversation as resolved.
Show resolved Hide resolved

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.
rachelwhitton marked this conversation as resolved.
Show resolved Hide resolved

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:

- MacOS
- 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)
rachelwhitton marked this conversation as resolved.
Show resolved Hide resolved

### 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.
rachelwhitton marked this conversation as resolved.
Show resolved Hide resolved

The commands below will:

Expand All @@ -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.

Expand All @@ -133,71 +114,35 @@ 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

<Alert title="Warning" type="danger" >
<Alert title="Note" type="info">

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.

</Alert>

```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:

```bash{promptUser: user}
brew upgrade pantheon-systems/external/terminus
rachelwhitton marked this conversation as resolved.
Show resolved Hide resolved
```

<Alert title="Note" type="info">

Terminus uses [Semantic versioning](https://semver.org/). Be sure to fully test compatibility with existing configurations before upgrading to new major releases.

</Alert>

## 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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we have a section for installing and updating terminus plugins, i would expect terminus self:plugin:update to be in the documentation, but in this case we just link out to the plugin directory.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I say delete this section from this page, it's already documented on another page.

If the steps were different based on terminus installed via PHAR vs homebrew, then it would be helpful to cover plugin installation/updates in those contexts but otherwise it's just adding noise instead of value I think


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

Expand Down