refactor: improve flag interpretation for install.sh (#9554)

2026-06-02 20:48:20 +00:00 · 2023-09-06 12:57:28 -06:00
parent b15bfa41c2
commit 4ed8dd0d6c
2 changed files with 160 additions and 28 deletions
@@ -34,6 +34,87 @@ manually via `coder server` or as a system package.
 By default, the Coder server runs on `http://127.0.0.1:3000` and uses a
 [public tunnel](../admin/configure.md#tunnel) for workspace connections.

+## `PATH` conflicts
+
+It's possible to end up in situations where you have multiple `coder` binaries
+in your `PATH`, and your system may use a version that you don't intend. Your
+`PATH` is a variable that tells your shell where to look for programs to run.
+
+You can check where all of the versions are by running `which -a coder`.
+
+For example, a common conflict on macOS might be between a version installed by
+Homebrew, and a version installed manually to the /usr/local/bin directory.
+
+```console
+$ which -a coder
+/usr/local/bin/coder
+/opt/homebrew/bin/coder
+```
+
+Whichever binary comes first in this list will be used when running `coder`
+commands.
+
+### Reordering your `PATH`
+
+If you use bash or zsh, you can update your `PATH` like this:
+
+```shell
+# You might want to add this line to the end of your ~/.bashrc or ~/.zshrc file!
+export PATH="/opt/homebrew/bin:$PATH"
+```
+
+If you use fish, you can update your `PATH` like this:
+
+```shell
+# You might want to add this line to the end of your ~/.config/fish/config.fish file!
+fish_add_path "/opt/homebrew/bin"
+```
+
+> ℹ If you ran install.sh with a `--prefix` flag, you can replace
+> `/opt/homebrew` with whatever value you used there. Make sure to leave the
+> `/bin` at the end!
+
+Now we can observe that the order has changed:
+
+```console
+$ which -a coder
+/opt/homebrew/bin/coder
+/usr/local/bin/coder
+```
+
+### Removing unneeded binaries
+
+If you want to uninstall a version of `coder` that you installed with a package
+manager, you can run whichever one of these commands applies:
+
+```shell
+# On macOS, with Homebrew installed
+brew uninstall coder
+```
+
+```shell
+# On Debian/Ubuntu based systems
+sudo dpkg -r coder
+```
+
+```shell
+# On Fedora/RHEL-like systems
+sudo rpm -e coder
+```
+
+```shell
+# On Alpine
+sudo apk del coder
+```
+
+If the conflicting binary is not installed by your system package manager, you
+can just delete it.
+
+```shell
+# You might not need `sudo`, depending on the location
+sudo rm /usr/local/bin/coder
+```
+
 ## Next steps

 - [Configuring Coder](../admin/configure.md)
@@ -104,18 +104,29 @@ Standalone release has been installed into $STANDALONE_INSTALL_PREFIX/bin/$STAND

 EOF

-	if [ "$STANDALONE_INSTALL_PREFIX" != /usr/local ]; then
+	CODER_COMMAND="$(command -v "$STANDALONE_BINARY_NAME")"
+
+	if [ ! "$CODER_COMMAND" ]; then
 		cath <<EOF
 Extend your path to use Coder:
-PATH="$STANDALONE_INSTALL_PREFIX/bin:\$PATH"
+
+  $ PATH="$STANDALONE_INSTALL_PREFIX/bin:\$PATH"
+
+EOF
+	elif [ "$CODER_COMMAND" != "$STANDALONE_BINARY_LOCATION" ]; then
+		echo_path_conflict "$CODER_COMMAND" "$STANDALONE_INSTALL_PREFIX"
+	else
+		cath <<EOF
+To run a Coder server:
+
+  $ $STANDALONE_BINARY_NAME server
+
+To connect to a Coder deployment:
+
+  $ $STANDALONE_BINARY_NAME login <deployment url>

 EOF
 	fi
-	cath <<EOF
-Run Coder:
-  $STANDALONE_BINARY_NAME server
-
-EOF
 }

 echo_brew_postinstall() {
@@ -124,8 +135,15 @@ echo_brew_postinstall() {
 		return
 	fi

+	CODER_COMMAND="$(command -v "coder")"
+	BREW_PREFIX="$(brew --prefix)"
+
+	if [ "$CODER_COMMAND" != "$BREW_PREFIX/bin/coder" ]; then
+		echo_path_conflict "$CODER_COMMAND" "$BREW_PREFIX"
+	fi
+
 	cath <<EOF
-brew formula has been installed.
+Homebrew formula has been installed.

 To run a Coder server:

@@ -157,7 +175,6 @@ To run a Coder server:
  # Or just run the server directly
  $ coder server

-  Default URL: http://127.0.0.1:3000
  Configuring Coder: https://coder.com/docs/v2/latest/admin/configure

 To connect to a Coder deployment:
@@ -169,18 +186,33 @@ EOF

 echo_dryrun_postinstall() {
 	cath <<EOF
-
 Dry-run complete.

 To install Coder, re-run this script without the --dry-run flag.
+
+EOF
+}
+
+echo_path_conflict() {
+	cath <<EOF
+There is another binary in your PATH that conflicts with the binary we've installed.
+
+  $1
+
+This is likely because of an existing installation of Coder. See our documentation for suggests on how to resolve this.
+
+	https://coder.com/docs/v2/latest/install/install.sh#path-conflicts
+
 EOF
 }

 main() {
 	TERRAFORM_VERSION="1.3.4"
+
 	if [ "${TRACE-}" ]; then
 		set -x
 	fi
+
 	unset \
 		DRY_RUN \
 		METHOD \
@@ -188,9 +220,11 @@ main() {
 		ALL_FLAGS \
 		RSH_ARGS \
 		EDGE \
-		RSH
+		RSH \
+		WITH_TERRAFORM

 	ALL_FLAGS=""
+
 	while [ "$#" -gt 0 ]; do
 		case "$1" in
 		-*)
@@ -245,7 +279,7 @@ main() {
 			exit 0
 			;;
 		--with-terraform)
-			METHOD=with_terraform
+			WITH_TERRAFORM=1
 			;;
 		--)
 			shift
@@ -275,8 +309,29 @@ main() {
 		return
 	fi

+	# These can be overridden for testing but shouldn't normally be used as it can
+	# result in a broken coder.
+	OS=${OS:-$(os)}
+	ARCH=${ARCH:-$(arch)}
+	TERRAFORM_ARCH=${TERRAFORM_ARCH:-$(terraform_arch)}
+
+	# We can't reasonably support installing specific versions of Coder through
+	# Homebrew, so if we're on macOS and the `--version` flag was set, we should
+	# "detect" standalone to be the appropriate installation method. This check
+	# needs to occur before we set `VERSION` to a default of the latest release.
+	if [ "$OS" = "darwin" ] && [ "${VERSION-}" ]; then
+		METHOD=standalone
+	fi
+
+	# If we've been provided a flag which is specific to the standalone installation
+	# method, we should "detect" standalone to be the appropriate installation method.
+	# This check needs to occur before we set these variables with defaults.
+	if [ "${STANDALONE_INSTALL_PREFIX-}" ] || [ "${STANDALONE_BINARY_NAME-}" ]; then
+		METHOD=standalone
+	fi
+
 	METHOD="${METHOD-detect}"
-	if [ "$METHOD" != detect ] && [ "$METHOD" != with_terraform ] && [ "$METHOD" != standalone ]; then
+	if [ "$METHOD" != detect ] && [ "$METHOD" != standalone ]; then
 		echoerr "Unknown install method \"$METHOD\""
 		echoerr "Run with --help to see usage."
 		exit 1
@@ -285,15 +340,10 @@ main() {
 	# These are used by the various install_* functions that make use of GitHub
 	# releases in order to download and unpack the right release.
 	CACHE_DIR=$(echo_cache_dir)
-	STANDALONE_INSTALL_PREFIX=${STANDALONE_INSTALL_PREFIX:-/usr/local}
 	TERRAFORM_INSTALL_PREFIX=${TERRAFORM_INSTALL_PREFIX:-/usr/local}
+	STANDALONE_INSTALL_PREFIX=${STANDALONE_INSTALL_PREFIX:-/usr/local}
 	STANDALONE_BINARY_NAME=${STANDALONE_BINARY_NAME:-coder}
 	VERSION=${VERSION:-$(echo_latest_version)}
-	# These can be overridden for testing but shouldn't normally be used as it can
-	# result in a broken coder.
-	OS=${OS:-$(os)}
-	ARCH=${ARCH:-$(arch)}
-	TERRAFORM_ARCH=${TERRAFORM_ARCH:-$(terraform_arch)}

 	distro_name

@@ -302,6 +352,11 @@ main() {
 		echoh
 	fi

+	# Start by installing Terraform, if requested
+	if [ "${WITH_TERRAFORM-}" = 1 ]; then
+		with_terraform
+	fi
+
 	# Standalone installs by pulling pre-built releases from GitHub.
 	if [ "$METHOD" = standalone ]; then
 		if has_standalone; then
@@ -313,10 +368,6 @@ main() {
 			exit 1
 		fi
 	fi
-	if [ "$METHOD" = with_terraform ]; then
-		# Install terraform then continue the script
-		with_terraform
-	fi

 	# DISTRO can be overridden for testing but shouldn't normally be used as it
 	# can result in a broken coder.
@@ -429,7 +480,7 @@ with_terraform() {
 install_macos() {
 	# If there is no `brew` binary available, just default to installing standalone
 	if command_exists brew; then
-		echoh "Installing v$VERSION of the coder formula from coder/coder."
+		echoh "Installing coder with Homebrew from the coder/coder tap."
 		echoh

 		sh_c brew install coder/coder/coder
@@ -505,16 +556,16 @@ install_standalone() {
 		"$sh_c" unzip -d "$CACHE_DIR" -o "$CACHE_DIR/coder_${VERSION}_${OS}_${ARCH}.zip"
 	fi

-	COPY_LOCATION="$STANDALONE_INSTALL_PREFIX/bin/$STANDALONE_BINARY_NAME"
+	STANDALONE_BINARY_LOCATION="$STANDALONE_INSTALL_PREFIX/bin/$STANDALONE_BINARY_NAME"

 	# Remove the file if it already exists to
 	# avoid https://github.com/coder/coder/issues/2086
-	if [ -f "$COPY_LOCATION" ]; then
-		"$sh_c" rm "$COPY_LOCATION"
+	if [ -f "$STANDALONE_BINARY_LOCATION" ]; then
+		"$sh_c" rm "$STANDALONE_BINARY_LOCATION"
 	fi

 	# Copy the binary to the correct location.
-	"$sh_c" cp "$CACHE_DIR/coder" "$COPY_LOCATION"
+	"$sh_c" cp "$CACHE_DIR/coder" "$STANDALONE_BINARY_LOCATION"

 	echo_standalone_postinstall
 }