opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-24 15:04:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

chore(docs): update docs for correct use of shell and console and enforce linewidth (#9245)

Browse Source
This commit is contained in:
Muhammad Atif Ali
2023-08-23 12:27:57 +03:00
committed by GitHub
parent ed2b1236c0
commit d37f6d80f7
96 changed files with 2838 additions and 1457 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ides/emacs-tramp.md
+62 -20
View File
@@ -1,6 +1,7 @@
# Emacs TRAMP
[Emacs TRAMP](https://www.emacswiki.org/emacs/TrampMode) is a method of running editing operations on a remote server.
[Emacs TRAMP](https://www.emacswiki.org/emacs/TrampMode) is a method of running
editing operations on a remote server.
## Connecting To A Workspace
@@ -10,13 +11,17 @@ To connect to your workspace first run:
coder config-ssh
```
Then you can connect to your workspace by its name in the format: `coder.<WORKSPACE NAME>`.
Then you can connect to your workspace by its name in the format:
`coder.<WORKSPACE NAME>`.
In Emacs type `C-x d` and then input: `/-:coder.<WORKSPACE NAME>:` and hit enter. This will open up Dired on the workspace's home directory.
In Emacs type `C-x d` and then input: `/-:coder.<WORKSPACE NAME>:` and hit
enter. This will open up Dired on the workspace's home directory.
### Using SSH
By default Emacs TRAMP is setup to use SCP to access files on the Coder workspace instance. However you might want to use SSH if you have a jumpbox or some other complex network setup.
By default Emacs TRAMP is setup to use SCP to access files on the Coder
workspace instance. However you might want to use SSH if you have a jumpbox or
some other complex network setup.
To do so set the following in your Emacs `init.el` file:
@@ -24,13 +29,17 @@ To do so set the following in your Emacs `init.el` file:
(setq tramp-default-method "ssh")
```
Then when you access the workspace instance via `/-:coder.<WORKSPACE NAME>` Emacs will use SSH. Setting `tramp-default-method` will also tell `ansi-term` mode the correct way to access the remote when directory tracking.
Then when you access the workspace instance via `/-:coder.<WORKSPACE NAME>`
Emacs will use SSH. Setting `tramp-default-method` will also tell `ansi-term`
mode the correct way to access the remote when directory tracking.
## Directory Tracking
### ansi-term
If you run your terminal in Emacs via `ansi-term` then you might run into a problem where while SSH-ed into a workspace Emacs will not change its `default-directory` to open files in the directory your shell is in.
If you run your terminal in Emacs via `ansi-term` then you might run into a
problem where while SSH-ed into a workspace Emacs will not change its
`default-directory` to open files in the directory your shell is in.
To fix this:
@@ -49,7 +58,8 @@ To fix this:
}
```
2. Next in the shell profile file on the workspace (ex., `~/.bashrc` for Bash and `~/.zshrc` for Zsh) add the following:
2. Next in the shell profile file on the workspace (ex., `~/.bashrc` for Bash
and `~/.zshrc` for Zsh) add the following:
```bash
ansi_term_announce_host() {
@@ -77,17 +87,24 @@ To fix this:
ansi_term_announce
```
Ansi Term expects the terminal running inside of it to send escape codes to inform Emacs of the hostname, user, and working directory. The above code sends these escape codes and associated data whenever the terminal logs in and whenever the directory changes.
Ansi Term expects the terminal running inside of it to send escape codes to
inform Emacs of the hostname, user, and working directory. The above code
sends these escape codes and associated data whenever the terminal logs in
and whenever the directory changes.
### eshell
The `eshell` mode will perform directory tracking by default, no additional configuration is needed.
The `eshell` mode will perform directory tracking by default, no additional
configuration is needed.
## Language Servers (Code Completion)
If you use [`lsp-mode`](https://emacs-lsp.github.io/lsp-mode) for code intelligence and completion some additional configuration is required.
If you use [`lsp-mode`](https://emacs-lsp.github.io/lsp-mode) for code
intelligence and completion some additional configuration is required.
In your Emacs `init.el` file you must register a LSP client and tell `lsp-mode` how to find it on the remote machine using the `lsp-register-client` function. For each LSP server you want to use in your workspace add the following:
In your Emacs `init.el` file you must register a LSP client and tell `lsp-mode`
how to find it on the remote machine using the `lsp-register-client` function.
For each LSP server you want to use in your workspace add the following:
```lisp
(lsp-register-client (make-lsp-client :new-connection (lsp-tramp-connection "<LSP SERVER BINARY>")
@@ -96,13 +113,27 @@ In your Emacs `init.el` file you must register a LSP client and tell `lsp-mode`
:server-id '<LANGUAGE SERVER ID>))
```
This tells `lsp-mode` to look for a language server binary named `<LSP SERVER BINARY>` for use in `<LANGUAGE MODE>` on a machine named `coder.<WORKSPACE NAME>`. Be sure to replace the values between angle brackets:
This tells `lsp-mode` to look for a language server binary named
`<LSP SERVER BINARY>` for use in `<LANGUAGE MODE>` on a machine named
`coder.<WORKSPACE NAME>`. Be sure to replace the values between angle brackets:
- `<LSP SERVER BINARY>` : The name of the language server binary, without any path components. For example to use the Deno Javascript language server use the value `deno`.
- `<LANGUAGE MODE>`: The name of the Emacs major mode for which the language server should be used. For example to enable the language server for Javascript development use the value `web-mode`.
- `<LANGUAGE SERVER ID>`: This is just the name that `lsp-mode` will use to refer to this language server. If you are ever looking for output buffers or files they may have this name in them.
- `<LSP SERVER BINARY>` : The name of the language server binary, without any
path components. For example to use the Deno Javascript language server use
the value `deno`.
- `<LANGUAGE MODE>`: The name of the Emacs major mode for which the language
server should be used. For example to enable the language server for
Javascript development use the value `web-mode`.
- `<LANGUAGE SERVER ID>`: This is just the name that `lsp-mode` will use to
refer to this language server. If you are ever looking for output buffers or
files they may have this name in them.
Calling the `lsp-register-client` function will tell `lsp-mode` the name of the LSP server binary. However this binary must be accessible via the path. If the language server binary is not in the path you must modify `tramp-remote-path` so that `lsp-mode` knows in what directories to look for the LSP server. To do this use TRAMP's connection profiles functionality. These connection profiles let you customize variables depending on what machine you are connected to. Add the following to your `init.el`:
Calling the `lsp-register-client` function will tell `lsp-mode` the name of the
LSP server binary. However this binary must be accessible via the path. If the
language server binary is not in the path you must modify `tramp-remote-path` so
that `lsp-mode` knows in what directories to look for the LSP server. To do this
use TRAMP's connection profiles functionality. These connection profiles let you
customize variables depending on what machine you are connected to. Add the
following to your `init.el`:
```lisp
(connection-local-set-profile-variables 'remote-path-lsp-servers
@@ -110,9 +141,20 @@ Calling the `lsp-register-client` function will tell `lsp-mode` the name of the
(connection-local-set-profiles '(:machine "coder.<WORKSPACE NAME>") 'remote-path-lsp-servers)
```
The `connection-local-set-profile-variables` function creates a new connection profile by the name `remote-path-lsp-servers`. The `connection-local-set-profiles` then indicates this `remote-path-lsp-servers` connection profile should be used when connecting to a server named `coder.<WORKSPACE NAME>`. Be sure to replace `<PATH TO ADD>` with the directory in which a LSP server is present.
The `connection-local-set-profile-variables` function creates a new connection
profile by the name `remote-path-lsp-servers`. The
`connection-local-set-profiles` then indicates this `remote-path-lsp-servers`
connection profile should be used when connecting to a server named
`coder.<WORKSPACE NAME>`. Be sure to replace `<PATH TO ADD>` with the directory
in which a LSP server is present.
TRAMP and `lsp-mode` are fickle friends, sometimes there is weird behavior. If you find that language servers are hanging in the `starting` state then [it might be helpful](https://github.com/emacs-lsp/lsp-mode/issues/2709#issuecomment-800868919) to set the `lsp-log-io` variable to `t`.
TRAMP and `lsp-mode` are fickle friends, sometimes there is weird behavior. If
you find that language servers are hanging in the `starting` state then
[it might be helpful](https://github.com/emacs-lsp/lsp-mode/issues/2709#issuecomment-800868919)
to set the `lsp-log-io` variable to `t`.
More details on configuring `lsp-mode` for TRAMP can be found [in the `lsp-mode` documentation](https://emacs-lsp.github.io/lsp-mode/page/remote/).
The [TRAMP `tramp-remote-path` documentation](https://www.gnu.org/software/emacs/manual/html_node/tramp/Remote-programs.html#Remote-programs) contains more examples and details of connection profiles.
More details on configuring `lsp-mode` for TRAMP can be found
[in the `lsp-mode` documentation](https://emacs-lsp.github.io/lsp-mode/page/remote/).
The
[TRAMP `tramp-remote-path` documentation](https://www.gnu.org/software/emacs/manual/html_node/tramp/Remote-programs.html#Remote-programs)
contains more examples and details of connection profiles.
docs/ides/gateway.md
+18 -15
View File
@@ -1,17 +1,17 @@
# JetBrains Gateway
JetBrains Gateway is a compact desktop app that allows you to work remotely with
a JetBrains IDE without even downloading one. [See JetBrains' website to learn
about and Gateway.](https://www.jetbrains.com/remote-development/gateway/)
a JetBrains IDE without even downloading one.
[See JetBrains' website to learn about and Gateway.](https://www.jetbrains.com/remote-development/gateway/)
Gateway can connect to a Coder workspace by using Coder's Gateway plugin or
manually setting up an SSH connection.
## Using Coder's JetBrains Gateway Plugin
> If you experience problems, please [create a GitHub
> issue](https://github.com/coder/coder/issues) or share in [our Discord
> channel](https://discord.gg/coder).
> If you experience problems, please
> [create a GitHub issue](https://github.com/coder/coder/issues) or share in
> [our Discord channel](https://discord.gg/coder).
1. [Install Gateway](https://www.jetbrains.com/help/idea/jetbrains-gateway.html)
1. Open Gateway and click the Coder icon to install the Coder plugin.
@@ -22,7 +22,8 @@ manually setting up an SSH connection.
![Gateway Connect to Coder](../images/gateway/plugin-connect-to-coder.png)
1. Enter your Coder deployment's Access Url and click "Connect" then paste the Session Token and click "OK"
1. Enter your Coder deployment's Access Url and click "Connect" then paste the
Session Token and click "OK"
![Gateway Session Token](../images/gateway/plugin-session-token.png)
@@ -37,7 +38,8 @@ manually setting up an SSH connection.
![Gateway IDE List](../images/gateway/plugin-select-ide.png)
1. Select the JetBrains IDE for your project and the project directory then
click "Start IDE and connect" ![Gateway Select IDE](../images/gateway/plugin-ide-list.png)
click "Start IDE and connect"
![Gateway Select IDE](../images/gateway/plugin-ide-list.png)
![Gateway IDE Opened](../images/gateway/gateway-intellij-opened.png)
@@ -99,7 +101,7 @@ Windows example:
macOS example:
```sh
```shell
keytool -import -alias coder -file cacert.pem -keystore /Applications/JetBrains\ Gateway.app/Contents/jbr/Contents/Home/lib/security/cacerts
```
@@ -150,12 +152,13 @@ keytool -import -alias coder -file cacert.pem -keystore /Applications/JetBrains\
![Gateway Continue](../images/gateway/gateway-continue.png)
1. Select the JetBrains IDE for your project and the project directory. SSH into your server to create a directory or check out code if you haven't already.
1. Select the JetBrains IDE for your project and the project directory. SSH into
your server to create a directory or check out code if you haven't already.
![Gateway Choose IDE](../images/gateway/gateway-choose-ide.png)
> Note the JetBrains IDE is remotely installed into `~/.
cache/JetBrains/RemoteDev/dist`
> Note the JetBrains IDE is remotely installed into
> `~/. cache/JetBrains/RemoteDev/dist`
1. Click "Download and Start IDE" to connect.
@@ -168,7 +171,7 @@ are air-gapped, and cannot reach jetbrains.com), run the following script in the
JetBrains IDE directory to point the default Gateway directory to the IDE
directory. This step must be done before configuring Gateway.
```sh
```shell
cd /opt/idea/bin
./remote-dev-server.sh registerBackendLocationForGateway
```
@@ -176,12 +179,12 @@ cd /opt/idea/bin
> Gateway only works with paid versions of JetBrains IDEs so the script will not
> be located in the `bin` directory of JetBrains Community editions.
[Here is the JetBrains
article](https://www.jetbrains.com/help/idea/remote-development-troubleshooting.html#setup:~:text=Can%20I%20point%20Remote%20Development%20to%20an%20existing%20IDE%20on%20my%20remote%20server%3F%20Is%20it%20possible%20to%20install%20IDE%20manually%3F)
[Here is the JetBrains article](https://www.jetbrains.com/help/idea/remote-development-troubleshooting.html#setup:~:text=Can%20I%20point%20Remote%20Development%20to%20an%20existing%20IDE%20on%20my%20remote%20server%3F%20Is%20it%20possible%20to%20install%20IDE%20manually%3F)
explaining this IDE specification.
## JetBrains Gateway in an offline environment
In networks that restrict access to the internet, you will need to leverage the
JetBrains Client Installer to download and save the IDE clients locally. Please
see the [JetBrains documentation for more information](https://www.jetbrains.com/help/idea/fully-offline-mode.html).
see the
[JetBrains documentation for more information](https://www.jetbrains.com/help/idea/fully-offline-mode.html).
docs/ides/remote-desktops.md
+14 -6
View File
@@ -1,6 +1,7 @@
# Remote Desktops
> Built-in remote desktop is on the roadmap ([#2106](https://github.com/coder/coder/issues/2106)).
> Built-in remote desktop is on the roadmap
> ([#2106](https://github.com/coder/coder/issues/2106)).
## VNC Desktop
@@ -13,10 +14,13 @@ Workspace requirements:
- VNC server (e.g. [tigervnc](https://tigervnc.org/))
- VNC client (e.g. [novnc](https://novnc.com/info.html))
Installation instructions vary depending on your workspace's operating
system, platform, and build system.
Installation instructions vary depending on your workspace's operating system,
platform, and build system.
As a starting point, see the [desktop-container](https://github.com/bpmct/coder-templates/tree/main/desktop-container) community template. It builds and provisions a Dockerized workspace with the following software:
As a starting point, see the
[desktop-container](https://github.com/bpmct/coder-templates/tree/main/desktop-container)
community template. It builds and provisions a Dockerized workspace with the
following software:
- Ubuntu 20.04
- TigerVNC server
@@ -25,9 +29,13 @@ As a starting point, see the [desktop-container](https://github.com/bpmct/coder-
## RDP Desktop
To use RDP with Coder, you'll need to install an [RDP client](https://docs.microsoft.com/en-us/windows-server/remote/remote-desktop-services/clients/remote-desktop-clients) on your local machine, and enable RDP on your workspace.
To use RDP with Coder, you'll need to install an
[RDP client](https://docs.microsoft.com/en-us/windows-server/remote/remote-desktop-services/clients/remote-desktop-clients)
on your local machine, and enable RDP on your workspace.
As a starting point, see the [gcp-windows-rdp](https://github.com/matifali/coder-templates/tree/main/gcp-windows-rdp) community template. It builds and provisions a Windows Server workspace on GCP.
As a starting point, see the
[gcp-windows-rdp](https://github.com/matifali/coder-templates/tree/main/gcp-windows-rdp)
community template. It builds and provisions a Windows Server workspace on GCP.
Use the following command to forward the RDP port to your local machine:
docs/ides/web-ides.md
+10 -5
View File
@@ -11,8 +11,8 @@ It's common to also let developers to connect via web IDEs.
In Coder, web IDEs are defined as
[coder_app](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app)
resources in the template. With our generic model, any web application can
be used as a Coder application. For example:
resources in the template. With our generic model, any web application can be
used as a Coder application. For example:
```hcl
# Add button to open Portainer in the workspace dashboard
@@ -36,7 +36,9 @@ resource "coder_app" "portainer" {
![code-server in a workspace](../images/code-server-ide.png)
[code-server](https://github.com/coder/coder) is our supported method of running VS Code in the web browser. A simple way to install code-server in Linux/macOS workspaces is via the Coder agent in your template:
[code-server](https://github.com/coder/coder) is our supported method of running
VS Code in the web browser. A simple way to install code-server in Linux/macOS
workspaces is via the Coder agent in your template:
```console
# edit your template
@@ -62,7 +64,9 @@ resource "coder_agent" "main" {
}
```
For advanced use, we recommend installing code-server in your VM snapshot or container image. Here's a Dockerfile which leverages some special [code-server features](https://coder.com/docs/code-server/):
For advanced use, we recommend installing code-server in your VM snapshot or
container image. Here's a Dockerfile which leverages some special
[code-server features](https://coder.com/docs/code-server/):
```Dockerfile
FROM codercom/enterprise-base:ubuntu
@@ -79,7 +83,8 @@ RUN code-server --install-extension eamodio.gitlens
# or use a process manager like supervisord
```
You'll also need to specify a `coder_app` resource related to the agent. This is how code-server is displayed on the workspace page.
You'll also need to specify a `coder_app` resource related to the agent. This is
how code-server is displayed on the workspace page.
```hcl
resource "coder_app" "code-server" {