|
2 | 2 |
|
3 | 3 | ## Architecture |
4 | 4 |
|
5 | | -The Coder Gateway plugin uses Gateway APIs to SSH into the remote machine, |
6 | | -download the requested IDE backend, run the backend, then launches a client that |
7 | | -connects to that backend using a port forward over SSH. If the backend goes down |
8 | | -due to a crash or a workspace restart, it will restart the backend and relaunch |
9 | | -the client. |
| 5 | +The Coder Toolbox Gateway plugins provides some login pages, after which |
| 6 | +it configures SSH and gives Toolbox a list of environments with their |
| 7 | +host names. Toolbox then handles everything else. |
10 | 8 |
|
11 | | -There are three ways to get into a workspace: |
| 9 | +There are two ways to get into a workspace: |
12 | 10 |
|
13 | 11 | 1. Dashboard link. |
14 | | -2. "Connect to Coder" button. |
15 | | -3. Using a recent connection. |
16 | | - |
17 | | -Currently the first two will configure SSH but the third does not yet. |
| 12 | +2. Through Toolbox. |
18 | 13 |
|
19 | 14 | ## Development |
20 | 15 |
|
21 | | -To manually install a local build: |
22 | | - |
23 | | -1. Install [Jetbrains Gateway](https://www.jetbrains.com/remote-development/gateway/) |
24 | | -2. Run `./gradlew clean buildPlugin` to generate a zip distribution. |
25 | | -3. Locate the zip file in the `build/distributions` folder and follow [these |
26 | | - instructions](https://www.jetbrains.com/help/idea/managing-plugins.html#install_plugin_from_disk) |
27 | | - on how to install a plugin from disk. |
| 16 | +You can get the latest build of Toolbox with Gateway support from our shared |
| 17 | +Slack channel with JetBrains. Make sure you download the right version (check |
| 18 | +[./gradle/libs.versions.toml](./gradle/libs.versions.toml)). |
28 | 19 |
|
29 | | -Alternatively, `./gradlew clean runIde` will deploy a Gateway distribution (the |
30 | | -one specified in `gradle.properties` - `platformVersion`) with the latest plugin |
31 | | -changes deployed. |
| 20 | +To load the plugin into Toolbox, close Toolbox, run `./gradlew build copyPlugin`, |
| 21 | +then launch Toolbox again. |
32 | 22 |
|
33 | | -To simulate opening a workspace from the dashboard pass the Gateway link via |
34 | | -`--args`. For example: |
| 23 | +To simulate opening a workspace from the dashboard you can use something like |
| 24 | +`xdg-open` to launch a URL in this format: |
35 | 25 |
|
36 | 26 | ``` |
37 | | -./gradlew clean runIDE --args="jetbrains-gateway://connect#type=coder&workspace=dev&agent=coder&folder=/home/coder&url=https://dev.coder.com&token=<redacted>&ide_product_code=IU&ide_build_number=223.8836.41&ide_download_link=https://download.jetbrains.com/idea/ideaIU-2022.3.3.tar.gz" |
| 27 | +jetbrains://gateway/com.coder.gateway/connect?workspace=dev&agent=coder&url=https://dev.coder.com&token=<redacted> |
38 | 28 | ``` |
39 | 29 |
|
40 | | -Alternatively, if you have separately built the plugin and already installed it |
41 | | -in a Gateway distribution you can launch that distribution with the URL as the |
42 | | -first argument (no `--args` in this case). |
43 | | - |
44 | 30 | If your change is something users ought to be aware of, add an entry in the |
45 | 31 | changelog. |
46 | 32 |
|
47 | 33 | Generally we prefer that PRs be squashed into `main` but you can rebase or merge |
48 | 34 | if it is important to keep the individual commits (make sure to clean up the |
49 | 35 | commits first if you are doing this). |
50 | 36 |
|
| 37 | +We are using `ktlint` to format but this is not currently enforced. |
| 38 | + |
51 | 39 | ## Testing |
52 | 40 |
|
53 | 41 | Run tests with `./gradlew test`. By default this will test against |
54 | 42 | `https://dev.coder.com` but you can set `CODER_GATEWAY_TEST_DEPLOYMENT` to a URL |
55 | 43 | of your choice or to `mock` to use mocks only. |
56 | 44 |
|
57 | | -There are two ways of using the plugin: from standalone Gateway, and from within |
58 | | -an IDE (`File` > `Remote Development`). There are subtle differences so it |
59 | | -makes usually sense to test both. We should also be testing both the latest |
60 | | -stable and latest EAP. |
61 | | - |
62 | | -## Plugin compatibility |
63 | | - |
64 | | -`./gradlew runPluginVerifier` can check the plugin compatibility against the specified Gateway. The integration with Github Actions is commented until [this gradle intellij plugin issue](https://github.com/JetBrains/gradle-intellij-plugin/issues/1027) is fixed. |
| 45 | +Some investigation is needed to see what options we have for testing code |
| 46 | +directly tied to the UI, as currently that code is untested. |
65 | 47 |
|
66 | 48 | ## Releasing |
67 | 49 |
|
68 | | -1. Check that the changelog lists all the important changes. |
69 | | -2. Update the gradle.properties version. |
70 | | -3. Publish the resulting draft release after validating it. |
71 | | -4. Merge the resulting changelog PR. |
| 50 | +We do not yet have a release workflow yet, but it will look like: |
72 | 51 |
|
73 | | -## `main` vs `eap` branch |
74 | | - |
75 | | -Sometimes there can be API incompatibilities between the latest stable version |
76 | | -of Gateway and EAP ones (Early Access Program). |
77 | | - |
78 | | -If this happens, use the `eap` branch to make a separate release. Once it |
79 | | -becomes stable, update the versions in `main`. |
80 | | - |
81 | | -## Supported Coder versions |
82 | | - |
83 | | -`Coder Gateway` includes checks for compatibility with a specified version |
84 | | -range. A warning is raised when the Coder deployment build version is outside of |
85 | | -compatibility range. |
86 | | - |
87 | | -At the moment the upper range is 3.0.0 so the check essentially has no effect, |
88 | | -but in the future we may want to keep this updated. |
| 52 | +1. Check that the changelog lists all the important changes. |
| 53 | +2. Update the extension.json version and changelog header. |
| 54 | +3. Tag the commit made from the second step with the version. |
| 55 | +4. Publish the resulting draft release after validating it. |
0 commit comments