chore(docs): reorganize installation docs #11465
Conversation
matifali
commented
Jan 7, 2024
•
- Reorganize installation docs to remove duplication by making use of tabs.
- Added 1-click install methods as a table.
| ## 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" | ||
| ``` |
There was a problem hiding this comment.
Our install script now defaults to homebrew for macOS, so this issue will likely not exist anymore.
| ### 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 | ||
| ``` |
There was a problem hiding this comment.
Moving and merging this section to Uninstall instructions
docs/install/index.md
Outdated
| ## Windows | ||
|
|
||
| Install using | ||
| [`winget`](https://learn.microsoft.com/en-us/windows/package-manager/winget/#use-winget) | ||
| package manager | ||
|
|
||
| ```powershell | ||
| winget install Coder.Coder | ||
| ``` |
There was a problem hiding this comment.
We also have a .msi installer. Can we mention both under the Windows tab?
There was a problem hiding this comment.
We do not have a .msi but a .exe installer, and I have included that in the System packages section. I understood your idea to group all Windows installation methods.
I do not favor grouping based on OS type but with installation method. I want to have an organization similar to Terrfaorm installation docs where we can have sub-tabs within a tab.
There was a problem hiding this comment.
When I started working on this, I did reorganized it on the basis of OS. Let me know what you think.
docs/install/index.md
Outdated
| coder login <access url> | ||
| ``` | ||
|
|
||
| There are a number of other different methods to install and run Coder: |
There was a problem hiding this comment.
It feels strange to have this at the bottom. I suggest omit it and add something on the top
The following guide walks you through installing Coder on your workstation or virtual machine. For alternate methods, see the sidebar
There was a problem hiding this comment.
Agreed. In my refactors I didn't extend the landing page too much, just including the one-liner install and a child for the platform-specific local installations.
I'm worried about burying the children pages.
That being said, I like the idea of bringing the simple POC installation flow forward.
There was a problem hiding this comment.
In my opinion, the current structure is overly complicated and buries most things under child pages. I want to bring as much as possible to the front.
Also, the install script and Homebrew are shared between macOS and Linux, so I do not think we can group them as Linux and macOS but would go with the current naming, install script, and Homebrew.
docs/install/uninstall.md
Outdated
| @@ -6,40 +6,40 @@ To uninstall your Coder server, delete the following directories. | |||
|
|
|||
| ## Cached Coder releases | |||
|
|
|||
| ```console | |||
| ```shell | |||
| rm -rf ~/.cache/coder | |||
| ``` | |||
|
|
|||
| ## The Coder server binary and CLI | |||
|
|
|||
| Debian, Ubuntu: | |||
There was a problem hiding this comment.
I tried tabs but it looks better without them
docs/install/index.md
Outdated
| @@ -1,5 +1,133 @@ | |||
| There are a number of different methods to install and run Coder: | |||
| 1. Install Coder | |||
There was a problem hiding this comment.
I think our landing page should include some simple opening header before any bullets, specifically leading with the one-line install cmd.
The easiest way to install Coder is to use our install script for Linux and macOS.
$ curl -fsSL https://coder.com/install.sh | sh
There was a problem hiding this comment.
I agree, but I am still looking for a line to start it. We should not recommend isntall_Script as the easiest way. For most people who self-host stuff, docker/docker-compose is easier. It is very subjective and depends on the use case. Installation with the install script is only easy for someone installing Coder on a dedicated VM/host.