Skip to content

C
code-server

gzupanda / code-server
与 Fork 源项目一致

从无法访问的项目Fork

通知 2
Star 0
Fork 0
C
code-server

前往新版Gitcode，体验更适合开发者的 AI 搜索 >>

未验证 提交 c1450084 编写于 作者: K Katie Horne 提交者： GitHub
浏览文件
操作

Merge pull request #3756 from cdr/docs-edits 

refactor(docs): clean up and restructure
上级 a96e16e5 66b6590e
展开全部 隐藏空白更改
内联 并排
Showing with 1199 addition and 1038 deletion
docs/CONTRIBUTING.md
浏览文件 @ c1450084
......@@ -2,17 +2,16 @@
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
# Contributing
- [Pull Requests](#pull-requests)
- [Commits](#commits)
- [Requirements](#requirements)
- [Development Workflow](#development-workflow)
- [Updating VS Code](#updating-vs-code)
- [Notes about Changes](#notes-about-changes)
- [Build](#build)
- [Testing](#testing)
- [Unit Tests](#unit-tests)
- [Integration Tests](#integration-tests)
- [End-to-End Tests](#end-to-end-tests)
- [Creating pull requests](#creating-pull-requests)
- [Commits and commit history](#commits-and-commit-history)
- [Development workflow](#development-workflow)
- [Updates to VS Code](#updates-to-vs-code)
- [Build](#build)
- [Test](#test)
- [Unit tests](#unit-tests)
- [Integration tests](#integration-tests)
- [End-to-end tests](#end-to-end-tests)
- [Structure](#structure)
- [Modifications to VS Code](#modifications-to-vs-code)
- [Currently Known Issues](#currently-known-issues)
......@@ -21,41 +20,49 @@
- [Detailed CI and build process docs](../ci)
## Pull Requests
Please create a [GitHub Issue](https://github.com/cdr/code-server/issues) to address any issue. You can skip this if the proposed fix is minor.
In your Pull Requests (PR), link to the issue that the PR solves.
Please ensure that the base of your PR is the **main** branch.
### Commits
We prefer a clean commit history. This means you should squash all fixups and fixup-type commits before asking for review (cleanup, squash, force-push). If you need help with this, feel free to leave a comment in your PR and we'll guide you.
## Requirements
The prerequisites for contributing to code-server are almost the same as those for
[VS Code](https://github.com/Microsoft/vscode/wiki/How-to-Contribute#prerequisites).
There are several differences, however. Here is what is needed:
The prerequisites for contributing to code-server are almost the same as those
for [VS
Code](https://github.com/Microsoft/vscode/wiki/How-to-Contribute#prerequisites).
Here is what is needed:
- `node` v14.x
- `git` v2.x or greater
- [`yarn`](https://classic.yarnpkg.com/en/)
- used to install JS packages and run scripts
- Used to install JS packages and run scripts
- [`nfpm`](https://classic.yarnpkg.com/en/)
- used to build `.deb` and `.rpm` packages
- Used to build `.deb` and `.rpm` packages
- [`jq`](https://stedolan.github.io/jq/)
- used to build code-server releases
- Used to build code-server releases
- [`gnupg`](https://gnupg.org/index.html)
- all commits must be signed and verified
- see GitHub's ["Managing commit signature verification"](https://docs.github.com/en/github/authenticating-to-github/managing-commit-signature-verification) or follow [this tutorial](https://joeprevite.com/verify-commits-on-github)
- `build-essential` (Linux)
- `apt-get install -y build-essential` - used by VS Code
- All commits must be signed and verified; see GitHub's [Managing commit
signature
verification](https://docs.github.com/en/github/authenticating-to-github/managing-commit-signature-verification)
or follow [this tutorial](https://joeprevite.com/verify-commits-on-github)
- `build-essential` (Linux only - used by VS Code)
- Get this by running `apt-get install -y build-essential`
- `rsync` and `unzip`
- used for code-server releases
- Used for code-server releases
## Creating pull requests
## Development Workflow
Please create a [GitHub Issue](https://github.com/cdr/code-server/issues) that
includes context for issues that you see. You can skip this if the proposed fix
is minor.
In your pull requests (PR), link to the issue that the PR solves.
Please ensure that the base of your PR is the **main** branch.
### Commits and commit history
We prefer a clean commit history. This means you should squash all fixups and
fixup-type commits before asking for a review (e.g., clean up, squash, then force
push). If you need help with this, feel free to leave a comment in your PR, and
we'll guide you.
## Development workflow
```shell
yarn
......@@ -65,28 +72,30 @@ yarn watch
`yarn watch` will live reload changes to the source.
### Updating VS Code
### Updates to VS Code
Updating VS Code requires `git subtree`. On some rpm-based Linux distros, `git subtree` is not included by default, and needs to be installed separately.
To install, run `dnf install git-subtree` or `yum install git-subtree` as necessary.
Updating VS Code requires `git subtree`. On some RPM-based Linux distros, `git subtree` is not included by default and needs to be installed separately. To
install, run `dnf install git-subtree` or `yum install git-subtree`.
To update VS Code, follow these steps:
To update VS Code:
1. Run `yarn update:vscode`.
2. Enter a version. Ex. 1.53
3. This will open a draft PR for you.
4. There will be merge conflicts. First commit them.
1. We do this because if we don't, it will be impossible to review your PR.
5. Once they're all fixed, test code-server locally and make sure it all works.
6. Check the version of Node.js that the version of Electron shipped with VSCode uses, and update the version of Node.js if necessary.
#### Notes about Changes
2. Enter a version (e.g., `1.53`)
3. This will open a draft pull request for you.
4. There will be merge conflicts. Commit them first, since it will be impossible
for us to review your PR if you don't.
5. Fix the conflicts. Then, test code-server locally to make sure everything
works.
6. Check the Node.js version that's used by Electron (which is shipped with VS
Code. If necessary, update your version of Node.js to match.
- watch out for updates to `lib/vscode/src/vs/code/browser/workbench/workbench.html`. You may need to make changes to `src/browser/pages/vscode.html`
> Watch for updates to
> `lib/vscode/src/vs/code/browser/workbench/workbench.html`. You may need to
> make changes to `src/browser/pages/vscode.html`.
## Build
### Build
You can build using:
You can build as follows:
```shell
yarn build
......@@ -94,7 +103,7 @@ yarn build:vscode
yarn release
```
Run your build with:
Run your build:
```shell
cd release
......@@ -111,73 +120,88 @@ yarn test:standalone-release
yarn package
```
NOTE: On Linux, the currently running distro will become the minimum supported version.
In our GitHub Actions CI, we use CentOS 7 for maximum compatibility.
If you need your builds to support older distros, run the build commands
inside a Docker container with all the build requirements installed.
> On Linux, the currently running distro will become the minimum supported
> version. In our GitHub Actions CI, we use CentOS 7 for maximum compatibility.
> If you need your builds to support older distros, run the build commands
> inside a Docker container with all the build requirements installed.
## Testing
### Test
There are three kinds of tests in code-server:
1. unit tests
2. integration tests
3. end-to-end tests
1. Unit tests
2. Integration tests
3. End-to-end tests
### Unit Tests
### Unit tests
Our unit tests are written in TypeScript and run using [Jest, the testing framework](https://jestjs.io/).
Our unit tests are written in TypeScript and run using
[Jest](https://jestjs.io/), the testing framework].
These live under [test/unit](../test/unit).
We use unit tests for functions and things that can be tested in isolation.
### Integration Tests
### Integration tests
These are a work-in-progress. We build code-server and run a script called [test-standalone-release.sh`](../ci/build/test-standalone-release.sh)
which ensures that code-server's CLI is working.
These are a work in progress. We build code-server and run a script called
[test-standalone-release.sh](../ci/build/test-standalone-release.sh), which
ensures that code-server's CLI is working.
Integration for us means testing things that integrate and rely on each other. For instance, testing the CLI which requires that code-server be built and packaged.
Our integration tests look at components that rely on one another. For example,
testing the CLI requires us to build and package code-server.
### End-to-End Tests
### End-to-end tests
The end-to-end (e2e) are written in TypeScript and run using [Playwright](https://playwright.dev/).
The end-to-end (e2e) tests are written in TypeScript and run using
[Playwright](https://playwright.dev/).
These live under [test/e2e](../test/e2e).
Before the e2e tests run, we have a `globalSetup` that runs which makes it so you don't have to login before each test and can reuse the authentication state.
Before the e2e tests run, we run `globalSetup`, which eliminates the need to log
in before each test by preserving the authentication state.
Take a look at `codeServer.test.ts` to see how you use it (look at `test.use`).
Take a look at `codeServer.test.ts` to see how you would use it (see
`test.use`).
We also have a model where you can create helpers to use within tests. Take a look at [models/CodeServer.ts](../test/e2e/models/CodeServer.ts) to see an example.
We also have a model where you can create helpers to use within tests. See
[models/CodeServer.ts](../test/e2e/models/CodeServer.ts) for an example.
Generally speaking, e2e means testing code-server running in the browser, similar to how a user would interact with it. When running these tests with `yarn test:e2e`, you must have code-server running locally. In CI, this is taken care of for you.
Generally speaking, e2e means testing code-server while running in the browser
and interacting with it in a way that's similar to how a user would interact
with it. When running these tests with `yarn test:e2e`, you must have
code-server running locally. In CI, this is taken care of for you.
## Structure
The `code-server` script serves an HTTP API for login and starting a remote VS Code process.
The `code-server` script serves as an HTTP API for login and starting a remote VS
Code process.
The CLI code is in [src/node](../src/node) and the HTTP routes are implemented in
[src/node/routes](../src/node/routes).
The CLI code is in [src/node](../src/node) and the HTTP routes are implemented
in [src/node/routes](../src/node/routes).
Most of the meaty parts are in the VS Code portion of the codebase under [lib/vscode](../lib/vscode), which we described next.
Most of the meaty parts are in the VS Code portion of the codebase under
[lib/vscode](../lib/vscode), which we describe next.
### Modifications to VS Code
In v1 of code-server, we had a patch of VS Code that split the codebase into a front-end
and a server. The front-end consisted of all UI code, while the server ran the extensions
and exposed an API to the front-end for file access and all UI needs.
In v1 of code-server, we had a patch of VS Code that split the codebase into a
front-end and a server. The front-end consisted of the UI code, while the server
ran the extensions and exposed an API to the front-end for file access and all
UI needs.
Over time, Microsoft added support to VS Code to run it on the web. They have made
the front-end open source, but not the server. As such, code-server v2 (and later) uses
the VS Code front-end and implements the server. We do this by using a git subtree to fork and modify VS Code. This code lives under [lib/vscode](../lib/vscode).
Over time, Microsoft added support to VS Code to run it on the web. They have
made the front-end open source, but not the server. As such, code-server v2 (and
later) uses the VS Code front-end and implements the server. We do this by using
a Git subtree to fork and modify VS Code. This code lives under
[lib/vscode](../lib/vscode).
Some noteworthy changes in our version of VS Code:
Some noteworthy changes in our version of VS Code include:
- Adding our build file, which includes our code and VS Code's web code
- Allowing multiple extension directories (both user and built-in)
- Modifying the loader, websocket, webview, service worker, and asset requests to
use the URL of the page as a base (and TLS, if necessary for the websocket)
- Modifying the loader, WebSocket, webview, service worker, and asset requests to
use the URL of the page as a base (and TLS, if necessary for the WebSocket)
- Sending client-side telemetry through the server
- Allowing modification of the display language
- Making it possible for us to load code on the client
......@@ -191,7 +215,7 @@ us to ensure that our changes are still applied and work as intended. In the fut
we'd like to run VS Code unit tests against our builds to ensure that features
work as expected.
**Note**: We have [extension docs](../ci/README.md) on the CI and build system.
> We have [extension docs](../ci/README.md) on the CI and build system.
If the functionality you're working on does NOT depend on code from VS Code, please
move it out and into code-server.
......
docs/FAQ.md
浏览文件 @ c1450084
此差异已折叠。
docs/MAINTAINING.md
浏览文件 @ c1450084
......@@ -2,130 +2,157 @@
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
# Maintaining
- [Maintaining](#maintaining)
- [Workflow](#workflow)
- [Milestones](#milestones)
- [Triage](#triage)
- [Project Boards](#project-boards)
- [Versioning](#versioning)
- [Pull Requests](#pull-requests)
- [Merge Strategies](#merge-strategies)
- [Changelog](#changelog)
- [Release](#release)
- [Release Manager Rotation](#release-manager-rotation)
- [Publishing a release](#publishing-a-release)
- [Workflow](#workflow)
- [Milestones](#milestones)
- [Triage](#triage)
- [Project boards](#project-boards)
- [Versioning](#versioning)
- [Pull requests](#pull-requests)
- [Merge strategies](#merge-strategies)
- [Changelog](#changelog)
- [Releases](#releases)
- [Publishing a release](#publishing-a-release)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
# Maintaining
Current maintainers:
- @code-asher
- @oxy
- @jsjoeio
This document is meant to serve current and future maintainers of code-server, but also share openly our workflow for maintaining the project.
This document is meant to serve current and future maintainers of code-server,
as well as share our workflow for maintaining the project.
## Workflow
The workflow used by code-server maintainers is one that aims to be easy to understood by the community and easy enough for new maintainers to jump in and start contributing on day one.
The workflow used by code-server maintainers aims to be easy to understood by
the community and easy enough for new maintainers to jump in and start
contributing on day one.
### Milestones
We operate mainly using [milestones](https://github.com/cdr/code-server/milestones). This was heavily inspired by our friends over at [vscode](https://github.com/microsoft/vscode).
We operate mainly using
[milestones](https://github.com/cdr/code-server/milestones). This was heavily
inspired by our friends over at [vscode](https://github.com/microsoft/vscode).
Here are the milestones we use and how we use them:
- "Backlog" -> Work not yet planned for a specific release.
- "On Deck" -> Work under consideration for upcoming milestones.
- "Backlog Candidates" -> Work that is not yet accepted for the backlog. We wait for the community to weigh in.
- "<0.0.0>" -> Work to be done for that version.
- "Backlog Candidates" -> Work that is not yet accepted for the backlog. We wait
for the community to weigh in.
- "<0.0.0>" -> Work to be done for a specific version.
With this flow, any un-assigned issues are essentially in triage state and once triaged are either "Backlog" or "Backlog Candidates". They will eventually move to "On Deck" (or be closed). Lastly, they will end up on a version milestone where they will be worked on.
With this flow, any un-assigned issues are essentially in triage state. Once
triaged, issues are either "Backlog" or "Backlog Candidates". They will
eventually move to "On Deck" (or be closed). Lastly, they will end up on a
version milestone where they will be worked on.
### Triage
We use the following process for triaging GitHub issues:
1. a submitter creates an issue
1. add appropriate labels
1. if we need to look into it further, add "needs-investigation"
1. add to milestone
1. if it should be fixed soon, add to version milestone or "On Deck"
1. if not urgent, add to "Backlog"
1. otherwise, add to "Backlog Candidate" if it should be considered
1. Create an issue
1. Add appropriate labels to the issue (including "needs-investigation" if we
should look into it further)
1. Add the issue to a milestone
1. If it should be fixed soon, add to version milestone or "On Deck"
2. If not urgent, add to "Backlog"
3. Otherwise, add to "Backlog Candidate" for future consideration
### Project Boards
### Project boards
We use project boards for projects or goals that span multiple milestones.
Think of this as a place to put miscellaneous things (like testing, clean up stuff, etc). As a maintainer, random todos may come up here and there. This gives you a place to add notes temporarily before opening a new issue. Given that our release milestones function off of issues, we believe tasks should have dedicated issues.
Think of this as a place to put miscellaneous things (like testing, clean up
stuff, etc). As a maintainer, random tasks may come up here and there. The
project boards give you places to add temporary notes before opening a new
issue. Given that our release milestones function off of issues, we believe
tasks should have dedicated issues.
It also gives us a way to separate the issue triage from bigger-picture, long-term work.
Project boards also give us a way to separate the issue triage from
bigger-picture, long-term work.
## Versioning
`<major.minor.patch>`
The code-server project follows traditional [semantic versioning](https://semver.org/), with the objective of minimizing major changes that break backward compatibility. We increment the patch level for all releases, except when the upstream Visual Studio Code project increments its minor version or we change the plugin API in a backward-compatible manner. In those cases, we increment the minor version rather than the patch level.
The code-server project follows traditional [semantic
versioning](https://semver.org/), with the objective of minimizing major changes
that break backward compatibility. We increment the patch level for all
releases, except when the upstream Visual Studio Code project increments its
minor version or we change the plugin API in a backward-compatible manner. In
those cases, we increment the minor version rather than the patch level.
## Pull Requests
## Pull requests
Ideally, every PR should fix an issue. If it doesn't, make sure it's associated with a version milestone.
Ideally, every PR should fix an issue. If it doesn't, make sure it's associated
with a version milestone.
If a PR does fix an issue, don't add it to the version milestone. Otherwise, the version milestone will have duplicate information: the issue & the PR fixing the issue.
If a PR does fix an issue, don't add it to the version milestone. Otherwise, the
version milestone will have duplicate information: the issue and the PR fixing
the issue.
### Merge Strategies
### Merge strategies
For most things, we recommend "Squash and Merge". If you're updating `lib/vscode`, we suggest using the "Rebase and Merge" strategy. There may be times where "Create a merge commit" makes sense as well. Use your best judgement. If you're unsure, you can always discuss in the PR with the team.
The code-server project follows traditional [semantic versioning](ttps://semver.org/), with the objective of minimizing major changes that break backward compatibility. We increment the patch level for all releases, except when the upstream Visual Studio Code project increments its minor version or we change the plugin API in a backward-compatible manner. In those cases, we increment the minor version rather than the patch level.
For most things, we recommend the **squash and merge** strategy. If you're
updating `lib/vscode`, we suggest using the **rebase and merge** strategy. There
may be times where **creating a merge commit** makes sense as well. Use your
best judgment. If you're unsure, you can always discuss in the PR with the team.
### Changelog
To save time when creating a new release for code-server, we keep a running changelog at `CHANGELOG.md`.
To save time when creating a new release for code-server, we keep a running
changelog at `CHANGELOG.md`.
If either author or reviewer of a PR believe the change should be mentioned in the `CHANGELOG`, then it should be added.
If either the author or reviewer of a PR believes the change should be mentioned
in the changelog, then it should be added.
If there is not a "Next Version" when you modify `CHANGELOG`, please add it using the template you see near the top of `CHANGELOG`.
If there is not a **Next Version** when you modify `CHANGELOG.md`, please add it
using the template you see near the top of the changelog.
As for what you should write for your changelog item, we should asking yourself these two questions:
When writing your changelog item, ask yourself:
1. How do these changes affect code-server users?
2. What actions do they need to take? (if any)
If you need inspiration, we suggest looking at the [Emacs changelog](https://github.com/emacs-mirror/emacs/blob/master/etc/NEWS).
2. What actions do they need to take (if any)?
## Release
If you need inspiration, we suggest looking at the [Emacs
changelog](https://github.com/emacs-mirror/emacs/blob/master/etc/NEWS).
### Release Manager Rotation
## Releases
With each release, we rotate the role of "release manager" to ensure every maintainer goes through the process. This helps us keep documentation up-to-date and encourages us to continually review and improve the flow with each set of eyes.
With each release, we rotate the role of release manager to ensure every
maintainer goes through the process. This helps us keep documentation up-to-date
and encourages us to continually review and improve the flow.
If you're the current release manager, follow these steps:
1. Create a [release issue](../.github/ISSUE_TEMPLATE/release.md)
2. Fill out checklist
3. After release is published, close release milestone
1. Fill out checklist
1. Publish the release
1. After release is published, close release milestone
### Publishing a release
1. Run `yarn release:prep` and type in the new version i.e. 3.8.1
2. GitHub actions will generate the `npm-package`, `release-packages` and `release-images` artifacts.
1. You do not have to wait for these.
3. Run `yarn release:github-draft` to create a GitHub draft release from the template with
the updated version.
1. Summarize the major changes in the release notes and link to the relevant issues.
2. Change the @ to target the version branch. Example: `v3.9.0 @ Target: v3.9.0`
4. Wait for the artifacts in step 2 to build.
5. Run `yarn release:github-assets` to download the `release-packages` artifact.
- It will upload them to the draft release.
6. Run some basic sanity tests on one of the released packages.
- Especially make sure the terminal works fine.
7. Publish the release and merge the PR.
1. CI will automatically grab the artifacts and then:
1. Publish the NPM package from `npm-package`.
2. Publish the Docker Hub image from `release-images`.
8. Update the AUR package.
- Instructions on updating the AUR package are at [cdr/code-server-aur](https://github.com/cdr/code-server-aur).
9. Wait for the npm package to be published.
1. Run `yarn release:prep` and type in the new version (e.g., `3.8.1`)
1. GitHub Actions will generate the `npm-package`, `release-packages` and
`release-images` artifacts. You do not have to wait for this step to complete
before proceeding.
1. Run `yarn release:github-draft` to create a GitHub draft release from the
template with the updated version.
1. Summarize the major changes in the release notes and link to the relevant
issues.
1. Change the @ to target the version branch. Example: `v3.9.0 @ Target: v3.9.0`
1. Wait for the `npm-package`, `release-packages` and `release-images` artifacts
to build.
1. Run `yarn release:github-assets` to download the `release-packages` artifact.
They will upload them to the draft release.
1. Run some basic sanity tests on one of the released packages (pay special
attention to making sure the terminal works).
1. Publish the release and merge the PR. CI will automatically grab the
artifacts, publish the NPM package from `npm-package`, and publish the Docker
Hub image from `release-images`.
1. Update the AUR package. Instructions for updating the AUR package are at
[cdr/code-server-aur](https://github.com/cdr/code-server-aur).
1. Wait for the npm package to be published.
docs/README.md
浏览文件 @ c1450084
......@@ -2,7 +2,8 @@
[!["GitHub Discussions"](https://img.shields.io/badge/%20GitHub-%20Discussions-gray.svg?longCache=true&logo=github&colorB=purple)](https://github.com/cdr/code-server/discussions) [!["Join us on Slack"](https://img.shields.io/badge/join-us%20on%20slack-gray.svg?longCache=true&logo=slack&colorB=brightgreen)](https://cdr.co/join-community) [![Twitter Follow](https://img.shields.io/twitter/follow/CoderHQ?label=%40CoderHQ&style=social)](https://twitter.com/coderhq) [![codecov](https://codecov.io/gh/cdr/code-server/branch/main/graph/badge.svg?token=5iM9farjnC)](https://codecov.io/gh/cdr/code-server) [![See v3.10.2 docs](https://img.shields.io/static/v1?label=Docs&message=see%20v3.10.2%20&color=blue)](https://github.com/cdr/code-server/tree/v3.10.2/docs)
Run [VS Code](https://github.com/Microsoft/vscode) on any machine anywhere and access it in the browser.
Run [VS Code](https://github.com/Microsoft/vscode) on any machine anywhere and
access it in the browser.
![Screenshot](./assets/screenshot.png)
......@@ -10,26 +11,31 @@ Run [VS Code](https://github.com/Microsoft/vscode) on any machine anywhere and a
- Code on any device with a consistent development environment
- Use cloud servers to speed up tests, compilations, downloads, and more
- Preserve battery life when you're on the go; all intensive tasks run on your server
- Preserve battery life when you're on the go; all intensive tasks run on your
server
## Requirements
For a good experience, we recommend at least:
See [requirements](requirements.md) for minimum specs, as well as instructions
on how to set up a Google VM on which you can install code-server.
- 1 GB of RAM
- 2 cores
**TL;DR:** Linux machine with WebSockets enabled, 1 GB RAM, and 2 CPUs
You can use whatever linux distribution floats your boat but in our [guide](https://coder.com/docs/code-server/v3.10.2/guide) we assume Debian on Google Cloud.
## Getting started
## Getting Started
There are three ways to get started:
There are three ways you can get started:
1. Using the [install
script](https://github.com/cdr/code-server/blob/main/install.sh), which
automates most of the process. The script uses the system package manager if
possible.
2. Manually [installing
code-server](https://coder.com/docs/code-server/v3.10.2/install)
3. Using our one-click buttons and guides to [deploy code-server to a cloud
provider](https://github.com/cdr/deploy-code-server) ⚡
1. Using the [install script](https://github.com/cdr/code-server/blob/main/install.sh), which automates most of the process. The script uses the system package manager (if possible)
2. Manually installing code-server; see [Installation](https://coder.com/docs/code-server/v3.10.2/install) for instructions applicable to most use cases
3. Use our one-click buttons and guides to [deploy code-server to a popular cloud provider](https://github.com/cdr/deploy-code-server) ⚡
If you choose to use the install script, you can preview what occurs during the install process:
If you use the install script, you can preview what occurs during the install
process:
```bash
curl -fsSL https://code-server.dev/install.sh | sh -s -- --dry-run
......@@ -41,37 +47,43 @@ To install, run:
curl -fsSL https://code-server.dev/install.sh | sh
```
When done, the install script prints out instructions for running and starting code-server.
When done, the install script prints out instructions for running and starting
code-server.
We also have an in-depth [setup and configuration](https://coder.com/docs/code-server/v3.10.2/guide) guide.
We also have an in-depth [setup and
configuration](https://coder.com/docs/code-server/v3.10.2/guide) guide.
### code-server --link
We're working on a cloud platform that makes deploying and managing code-server easier.
Consider running code-server with the beta flag `--link` if you don't want to worry about
We're working on a cloud platform that makes deploying and managing code-server
easier. Consider running code-server with the beta flag `--link` if you don't
want to worry about:
- TLS
- Authentication
- Port Forwarding
- Port forwarding
```bash
$ code-server --link
Proxying code-server, you can access your IDE at https://valmar-jon.cdr.co
Proxying code-server, you can access your IDE at https://example.cdr.co
```
## FAQ
## Questions?
See [./FAQ.md](https://coder.com/docs/code-server/v3.10.2/FAQ).
See answers to [frequently asked
questions](https://coder.com/docs/code-server/v3.10.2/FAQ).
## Want to help?
See [CONTRIBUTING](https://coder.com/docs/code-server/v3.10.2/CONTRIBUTING) for details.
See [Contributing](https://coder.com/docs/code-server/v3.10.2/CONTRIBUTING) for
details.
## Hiring
Interested in [working at Coder](https://coder.com/careers)? Check out [our open positions](https://coder.com/careers#openings)!
Interested in [working at Coder](https://coder.com/careers)? Check out [our open
positions](https://coder.com/careers#openings)!
## For Organizations
Want remote development for your organization or enterprise? Visit
[our website](https://coder.com) to learn more about Coder.
Want remote development for your organization or enterprise? Visit [our
website](https://coder.com) to learn more about Coder.
docs/SECURITY.md
浏览文件 @ c1450084
# Security Policy
The code-server team (and Coder, the organization) care a lot about keeping the project secure and safe for end-users.
Coder and the code-server team want to keep the code-server project secure and safe for end-users.
## Tools
We use a combination of tools to help us stay on top of vulnerabilities.
We use the following tools to help us stay on top of vulnerability mitigation.
- [dependabot](https://dependabot.com/)
- Submits pull requests to upgrade dependencies. We use dependabot's version upgrades as well as security updates.
- Submits pull requests to upgrade dependencies. We use dependabot's version
upgrades as well as security updates.
- code-scanning
- [CodeQL](https://securitylab.github.com/tools/codeql/)
- Semantic code analysis engine that runs on a regular schedule (see `codeql-analysis.yml`)
- Semantic code analysis engine that runs on a regular schedule (see
`codeql-analysis.yml`)
- [trivy](https://github.com/aquasecurity/trivy)
- Comprehensive vulnerability scanner that runs on PRs into the default branch and scans both our container image and repository code (see `trivy-scan-repo` and `trivy-scan-image` jobs in `ci.yaml`)
- Comprehensive vulnerability scanner that runs on PRs into the default
branch and scans both our container image and repository code (see
`trivy-scan-repo` and `trivy-scan-image` jobs in `ci.yaml`)
- [`audit-ci`](https://github.com/IBM/audit-ci)
- Audits npm and Yarn dependencies in CI (see "Audit for vulnerabilities" step in `ci.yaml`) on PRs into the default branch and fails CI if moderate or higher vulnerabilities(see the `audit.sh` script) are present.
- Audits npm and Yarn dependencies in CI (see `Audit for vulnerabilities` step
in `ci.yaml`) on PRs into the default branch and fails CI if moderate or
higher vulnerabilities (see the `audit.sh` script) are present.
## Supported Versions
Coder sponsors development and maintenance of the code-server project. We will fix security issues within 90 days of receiving a report, and publish the fix in a subsequent release. The code-server project does not provide backports or patch releases for security issues at this time.
Coder sponsors the development and maintenance of the code-server project. We will fix security issues within 90 days of receiving a report and publish the fix in a subsequent release. The code-server project does not provide backports or patch releases for security issues at this time.
| Version | Supported |
| ----------------------------------------------------- | ------------------ |
......@@ -26,4 +32,4 @@ Coder sponsors development and maintenance of the code-server project. We will f
## Reporting a Vulnerability
To report a vulnerability, please send an email to security[@]coder.com and our security team will respond to you.
To report a vulnerability, please send an email to security[@]coder.com, and our security team will respond to you.
docs/guide.md
浏览文件 @ c1450084
此差异已折叠。
docs/install.md
浏览文件 @ c1450084
......@@ -2,96 +2,161 @@
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
# Install
- [Upgrading](#upgrading)
- [install.sh](#installsh)
- [Flags](#flags)
- [Detection Reference](#detection-reference)
- [Detection reference](#detection-reference)
- [yarn, npm](#yarn-npm)
- [Standalone releases](#standalone-releases)
- [Debian, Ubuntu](#debian-ubuntu)
- [Fedora, CentOS, RHEL, SUSE](#fedora-centos-rhel-suse)
- [Arch Linux](#arch-linux)
- [Termux](#termux)
- [Raspberry Pi](#raspberry-pi)
- [yarn, npm](#yarn-npm)
- [macOS](#macos)
- [Standalone Releases](#standalone-releases)
- [Docker](#docker)
- [helm](#helm)
- [Cloud Providers](#cloud-providers)
- [Troubleshooting Node Issues](#troubleshooting-node-issues)
- [Helm](#helm)
- [Raspberry Pi](#raspberry-pi)
- [Termux](#termux)
- [Cloud providers](#cloud-providers)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
This document demonstrates how to install `code-server` on
various distros and operating systems.
## Upgrading
When upgrading you can just install the new version over the old one. code-server
maintains all user data in `~/.local/share/code-server` so that it is preserved in between
installations.
This document demonstrates how to install `code-server` on various distros and
operating systems.
## install.sh
We have a [script](../install.sh) to install code-server for Linux, macOS and FreeBSD.
It tries to use the system package manager if possible.
The easiest way to install code-server is to use our [install
script](../install.sh) for Linux, macOS and FreeBSD. The install script
[attempts to use the system package manager](#detection-reference) if possible.
First run to print out the install process:
You can preview what occurs during the install process:
```bash
curl -fsSL https://code-server.dev/install.sh | sh -s -- --dry-run
```
Now to actually install:
To install, run:
```bash
curl -fsSL https://code-server.dev/install.sh | sh
```
The script will print out how to run and start using code-server.
You can modify the installation process by including one or more of the
following flags:
If you believe an install script used with `curl | sh` is insecure, please give
[this wonderful blogpost](https://sandstorm.io/news/2015-09-24-is-curl-bash-insecure-pgp-verified-install) by
[sandstorm.io](https://sandstorm.io) a read.
- `--dry-run`: echo the commands for the install process without running them.
- `--method`: choose the installation method.
- `--method=detect`: detect the package manager but fallback to
`--method=standalone`.
- `--method=standalone`: install a standalone release archive into `~/.local`.
- `--prefix=/usr/local`: install a standalone release archive system-wide.
- `--version=X.X.X`: install version `X.X.X` instead of latest version.
- `--help`: see usage docs.
If you'd still prefer manual installation despite the below [detection reference](#detection-reference) and `--dry-run`
then continue on for docs on manual installation. The [`install.sh`](../install.sh) script runs the _exact_ same
commands presented in the rest of this document.
When done, the install script prints out instructions for running and starting
code-server.
### Flags
> If you're concerned about the install script's use of `curl | sh` and the
> security implications, please see [this blog
> post](https://sandstorm.io/news/2015-09-24-is-curl-bash-insecure-pgp-verified-install)
> by [sandstorm.io](https://sandstorm.io).
- `--dry-run` to echo the commands for the install process without running them.
- `--method` to choose the installation method.
- `--method=detect` to detect the package manager but fallback to `--method=standalone`.
- `--method=standalone` to install a standalone release archive into `~/.local`.
- `--prefix=/usr/local` to install a standalone release archive system wide.
- `--version=X.X.X` to install version `X.X.X` instead of latest.
- `--help` to see full usage docs.
If you prefer to install code-server manually, despite the [detection
references](#detection-reference) and `--dry-run` feature, then continue on for
information on how to do this. The [`install.sh`](../install.sh) script runs the
_exact_ same commands presented in the rest of this document.
### Detection Reference
### Detection reference
- For Debian and Ubuntu it will install the latest deb package.
- For Fedora, CentOS, RHEL and openSUSE it will install the latest rpm package.
- For Arch Linux it will install the AUR package.
- For any unrecognized Linux operating system it will install the latest standalone release into `~/.local`.
- For Debian and Ubuntu, code-server will install the latest deb package.
- For Fedora, CentOS, RHEL and openSUSE, code-server will install the latest RPM
package.
- For Arch Linux, code-server will install the AUR package.
- For any unrecognized Linux operating system, code-server will install the
latest standalone release into `~/.local`.
- Add `~/.local/bin` to your `$PATH` to run code-server.
- Ensure that you add `~/.local/bin` to your `$PATH` to run code-server.
- For macOS it will install the Homebrew package.
- For macOS, code-server will install the Homebrew package (if you don't have
Homebrew installed, code-server will install the latest standalone release
into `~/.local`).
- If Homebrew is not installed it will install the latest standalone release into `~/.local`.
- Add `~/.local/bin` to your `$PATH` to run code-server.
- Ensure that you add `~/.local/bin` to your `$PATH` to run code-server.
- For FreeBSD, it will install the [npm package](#yarn-npm) with `yarn` or `npm`.
- For FreeBSD, code-server will install the [npm package](#yarn-npm) with `yarn`
or `npm`.
- If ran on an architecture with no releases, it will install the [npm package](#yarn-npm) with `yarn` or `npm`.
- We only have releases for amd64 and arm64 presently.
- The [npm package](#yarn-npm) builds the native modules on postinstall.
- If you're installing code-server onto architecture with no releases,
code-server will install the [npm package](#yarn-npm) with `yarn` or `npm`
- We currently offer releases for amd64 and arm64.
- The [npm package](#yarn-npm) builds the native modules on post-install.
## yarn, npm
We recommend installing with `yarn` or `npm` when:
1. You aren't using a machine with `amd64` or `arm64`.
2. You're on Linux with `glibc` < v2.17, `glibcxx` < v3.4.18 on `amd64`, `glibc`
< v2.23, or `glibcxx` < v3.4.21 on `arm64`.
3. You're running Alpine Linux or are using a non-glibc libc. See
[#1430](https://github.com/cdr/code-server/issues/1430#issuecomment-629883198)
for more information.
Installing code-server with `yarn` or `npm` builds native modules on install.
This process requires C dependencies; see our guide on [installing these
dependencies][./npm.md](./npm.md) for more information.
You must have Node.js v12 (or later) installed. See
[#1633](https://github.com/cdr/code-server/issues/1633).
To install:
```bash
yarn global add code-server
# Or: npm install -g code-server
code-server
# Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml
```
## Standalone releases
We publish self-contained `.tar.gz` archives for every release on
[GitHub](https://github.com/cdr/code-server/releases). The archives bundle the
node binary and node modules.
We create the standalone releases using the [npm package](#yarn-npm), and we
then create the remaining releases using the standalone version.
The only requirement to use the standalone release is `glibc` >= 2.17 and
`glibcxx` >= v3.4.18 on Linux (for macOS, there is no minimum system
requirement).
To use a standalone release:
1. Download the latest release archive for your system from
[GitHub](https://github.com/cdr/code-server/releases).
2. Unpack the release.
3. Run code-server by executing `./bin/code-server`.
You can add `./bin/code-server` to your `$PATH` so that you can execute
`code-server` without providing full path each time.
Here is a sample script for installing and using a standalone code-server
release on Linux:
```bash
mkdir -p ~/.local/lib ~/.local/bin
curl -fL https://github.com/cdr/code-server/releases/download/v$VERSION/code-server-$VERSION-linux-amd64.tar.gz \
| tar -C ~/.local/lib -xz
mv ~/.local/lib/code-server-$VERSION-linux-amd64 ~/.local/lib/code-server-$VERSION
ln -s ~/.local/lib/code-server-$VERSION/bin/code-server ~/.local/bin/code-server
PATH="~/.local/bin:$PATH"
code-server
# Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml
```
## Debian, Ubuntu
NOTE: The standalone arm64 .deb does not support Ubuntu <16.04.
Please upgrade or [build with yarn](#yarn-npm).
> The standalone arm64 .deb does not support Ubuntu 16.04 or earlier. Please
> upgrade or [build with yarn](#yarn-npm).
```bash
curl -fOL https://github.com/cdr/code-server/releases/download/v$VERSION/code-server_$VERSION_amd64.deb
......@@ -102,8 +167,8 @@ sudo systemctl enable --now code-server@$USER
## Fedora, CentOS, RHEL, SUSE
NOTE: The standalone arm64 .rpm does not support CentOS 7.
Please upgrade or [build with yarn](#yarn-npm).
> The standalone arm64 .rpm does not support CentOS 7. Please upgrade or [build
> with yarn](#yarn-npm).
```bash
curl -fOL https://github.com/cdr/code-server/releases/download/v$VERSION/code-server-$VERSION-amd64.rpm
......@@ -115,14 +180,14 @@ sudo systemctl enable --now code-server@$USER
## Arch Linux
```bash
# Installs code-server from the AUR using yay.
# Install code-server from the AUR using yay.
yay -S code-server
sudo systemctl enable --now code-server@$USER
# Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml
```
```bash
# Installs code-server from the AUR with plain makepkg.
# Install code-server from the AUR with plain makepkg.
git clone https://aur.archlinux.org/code-server.git
cd code-server
makepkg -si
......@@ -130,34 +195,6 @@ sudo systemctl enable --now code-server@$USER
# Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml
```
## Termux
Please see "Installation" in the [Termux docs](./termux.md#installation)
## Raspberry Pi
If you're running a Raspberry Pi, we recommend install code-server with `yarn` or `npm`. See [yarn-npm](#yarn-npm).
## yarn, npm
We recommend installing with `yarn` or `npm` when:
1. You aren't on `amd64` or `arm64`.
2. If you're on Linux with glibc < v2.17 or glibcxx < v3.4.18 on amd64, or glibc < v2.23 or glibcxx < v3.4.21 on arm64.
3. You're running Alpine Linux, or are using a non-glibc libc. See [#1430](https://github.com/cdr/code-server/issues/1430#issuecomment-629883198)
**note:** Installing via `yarn` or `npm` builds native modules on install and so requires C dependencies.
See [./npm.md](./npm.md) for installing these dependencies.
You will need at least node v12 installed. See [#1633](https://github.com/cdr/code-server/issues/1633).
```bash
yarn global add code-server
# Or: npm install -g code-server
code-server
# Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml
```
## macOS
```bash
......@@ -166,34 +203,6 @@ brew services start code-server
# Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml
```
## Standalone Releases
We publish self contained `.tar.gz` archives for every release on [github](https://github.com/cdr/code-server/releases).
They bundle the node binary and `node_modules`.
These are created from the [npm package](#yarn-npm) and the rest of the releases are created from these.
Only requirement is glibc >= 2.17 && glibcxx >= v3.4.18 on Linux and for macOS there is no minimum system requirement.
1. Download the latest release archive for your system from [github](https://github.com/cdr/code-server/releases).
2. Unpack the release.
3. You can run code-server by executing `./bin/code-server`.
You can add the code-server `bin` directory to your `$PATH` to easily execute `code-server`
without the full path every time.
Here is an example script for installing and using a standalone `code-server` release on Linux:
```bash
mkdir -p ~/.local/lib ~/.local/bin
curl -fL https://github.com/cdr/code-server/releases/download/v$VERSION/code-server-$VERSION-linux-amd64.tar.gz \
| tar -C ~/.local/lib -xz
mv ~/.local/lib/code-server-$VERSION-linux-amd64 ~/.local/lib/code-server-$VERSION
ln -s ~/.local/lib/code-server-$VERSION/bin/code-server ~/.local/bin/code-server
PATH="~/.local/bin:$PATH"
code-server
# Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml
```
## Docker
```bash
......@@ -214,33 +223,26 @@ docker run -it --name code-server -p 127.0.0.1:8080:8080 \
codercom/code-server:latest
```
Our official image supports `amd64` and `arm64`.
For `arm32` support there is a popular community maintained alternative:
[https://hub.docker.com/r/linuxserver/code-server](https://hub.docker.com/r/linuxserver/code-server)
Our official image supports `amd64` and `arm64`. For `arm32` support, you can
use a [community-maintained code-server
alternative](https://hub.docker.com/r/linuxserver/code-server).
## helm
## Helm
See [the chart](../ci/helm-chart).
You can install code-server via [Helm](../ci/helm-chart/README.md).
## Cloud Providers
We maintain one-click apps and install scripts for different cloud providers such as DigitalOcean, Railway, Heroku, Azure, etc. Check out the repository:
[https://github.com/cdr/deploy-code-server](https://github.com/cdr/deploy-code-server)
## Troubleshooting Node Issues
## Raspberry Pi
Occassionally, you may run into issues with node.
We recommend installing code-server onto Raspberry Pi with [`yarn` or
`npm`](#yarn-npm).
If you install code-server with `yarn`/`npm` and upgrade your node version, you may need to reinstall code-server to recompile native modules. Sometimes you can get around this by `cd`'ing into the `lib/vscode` directory under code-server and running `npm rebuild` to recompile those native modules.
## Termux
An example of this might look like:
Please see code-server's [Termux docs](./termux.md#installation) for more
information.
1. You installed code-server using `brew install code-server`
2. You `cd` into the directory `cd /usr/local/Cellar/code-server/<version>/libexec/lib/vscode/`
3. You recompile native modules by running `npm rebuild`
4. You restart code-server
## Cloud providers
If you get stuck or need help, post on our [GitHub Discussions page](https://github.com/cdr/code-server/discussions).
We maintain [one-click apps and install scripts for cloud
providers](https://github.com/cdr/deploy-code-server) such as DigitalOcean,
Railway, Heroku, and Azure.
docs/ipad.md
浏览文件 @ c1450084
......@@ -2,162 +2,200 @@
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
# iPad
- [Known Issues](#known-issues)
- [How to install PWA](#how-to-install-pwa)
- [How to access code-server with a self signed certificate on iPad?](#how-to-access-code-server-with-a-self-signed-certificate-on-ipad)
- [Servediter iPad App](#servediter-ipad-app)
- [Raspberry Pi USB-C Network](#raspberry-pi-usb-c-network)
- [Ctrl C Workaround](#ctrl-c-workaround)
- [Using the code-server progressive web app (PWA)](#using-the-code-server-progressive-web-app-pwa)
- [Access code-server with a self-signed certificate on an iPad](#access-code-server-with-a-self-signed-certificate-on-an-ipad)
- [Certificate requirements](#certificate-requirements)
- [Sharing a self-signed certificate with an iPad](#sharing-a-self-signed-certificate-with-an-ipad)
- [Access code-server using Servediter](#access-code-server-using-servediter)
- [Raspberry Pi USB-C network](#raspberry-pi-usb-c-network)
- [Recommendations](#recommendations)
- [By 2022 iPad coding more desirable on Arm Macs](#by-2022-ipad-coding-more-desirable-on-arm-macs)
- [Known issues](#known-issues)
- [Workaround for issue with `ctrl+c` not stopping a running process in the terminal](#workaround-for-issue-with-ctrlc-not-stopping-a-running-process-in-the-terminal)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## Known Issues
- Getting self signed certificates certificates to work is involved, see below.
- Keyboard issues
- May disappear sometimes [#1313](https://github.com/cdr/code-server/issues/1313), [#979](https://github.com/cdr/code-server/issues/979)
- Some short cuts expectations may not be met
- `command + n` opens new browser window instead of new file and difficult to even set to another quick key
- In general it's just note worthy you most likely will need to edit keyboard shortcuts
- No escape key by default on Magic Keyboard but everyone sets the globe key to be an escape key
- Opinion: It's actually an awesome joy having the escape key at bottom of keyboard
- Trackpad scrolling does not work [#1455](https://github.com/cdr/code-server/issues/1455)
- [Bug tracking of a WebKit fix here](https://bugs.webkit.org/show_bug.cgi?id=210071#c13)
- [tracking of WebKit patch](https://trac.webkit.org/changeset/270712/webkit)
- Alternative: Install line-jump extension and use keyboard to nav by jumping large amount of lines
- Alternative: Just use touch scrolling
- See [issues tagged with the iPad label](https://github.com/cdr/code-server/issues?q=is%3Aopen+is%3Aissue+label%3AiPad) for more.
- `ctrl+c` does not stop a long-running process in the browser
- Tracking upstream issue here: [#114009](https://github.com/microsoft/vscode/issues/114009)
- See [workaround](#ctrl-c-workaround)
Once you've installed code-server, you can access it from an iPad.
## How to install PWA
## Using the code-server progressive web app (PWA)
To install the code-server PWA, follow these steps:
To use code-server on an iPad, we recommend installing the code-server
progressive web app (PWA):
1. Open code-server in Safari
2. Click the Share icon
3. Click "Add to Home Screen"
1. Open code-server in Safari.
2. Click the **Share** icon.
3. Click **Add to Home Screen**.
Now when you open code-server from the home screen, you will be using the PWA.
The advantages of this are more screen real estate and access to top-level keyboard shortcuts because it's running like an app.
An example shortcut is the `cmd+w` to close an active file in the workbench. You can add this to your `keybindings.json` by doing the following:
You can now open code-server from the Home screen, and when you do, you'll be
using the PWA. Running code-server as a PWA gets you more screen real estate and
access to top-level keyboard shortcuts since its running like a native app.
1. Open up code-serer
2. `Command Palette > Open Keyboard Shortcuts (JSON)`
3. Add the following to your `keybindings.json`
For example, you can use `cmd+w` to close an active file in the workbench. You
can add this to `keybindings.json`:
```json
{
"key": "cmd+w",
"command": "workbench.action.closeActiveEditor"
}
```
1. Open code-server
2. Go to **Command Palette** > **Open Keyboard Shortcuts (JSON)**
3. Add the following to `keybindings.json`
Test out command by hitting `cmd+w` to close an active file
```json
{
"key": "cmd+w",
"command": "workbench.action.closeActiveEditor"
}
```
## How to access code-server with a self signed certificate on iPad?
4. Test the command by using `cmd+w` to close an active file.
Accessing a self signed certificate on iPad isn't as easy as accepting through all
the security warnings. Safari will prevent WebSocket connections unless the certificate
is installed as a profile on the device.
## Access code-server with a self-signed certificate on an iPad
The below assumes you are using the self signed certificate that code-server
generates for you. If not, that's fine but you'll have to make sure your certificate
abides by the following guidelines from Apple: https://support.apple.com/en-us/HT210176
If you've installed code-server and are [running it with a self-signed
certificate](./guide.md#using-a-self-signed-certificate), you may see multiple
security warnings from Safari. To fix this, you'll need to install the
self-signed certificate generated by code-server as a profile on your device (you'll also need to do this to
enable WebSocket connections).
**note**: Another undocumented requirement we noticed is that the certificate has to have `basicConstraints=CA:true`.
### Certificate requirements
The following instructions assume you have code-server installed and running
with a self signed certificate. If not, please first go through [./guide.md](./guide.md)!
- We're assuming that you're using the self-signed certificate code-server
generates for you (if not, make sure that your certificate [abides by the
guidelines issued by Apple](https://support.apple.com/en-us/HT210176)).
- We've noticed that the certificate has to include `basicConstraints=CA:true`.
- Your certificate must have a subject alt name that matches the hostname you'll
use to access code-server from the iPad. You can pass this name to code-server
so that it generates the certificate correctly using `--cert-host`.
**warning**: Your iPad must access code-server via a domain name. It could be local
DNS like `mymacbookpro.local` but it must be a domain name. Otherwise Safari will
refuse to allow WebSockets to connect.
### Sharing a self-signed certificate with an iPad
1. Your certificate **must** have a subject alt name that matches the hostname
at which you will access code-server from your iPad. You can pass this to code-server
so that it generates the certificate correctly with `--cert-host`.
2. Share your self signed certificate with the iPad.
- code-server will print the location of the certificate it has generated in the logs.
To share a self-signed certificate with an iPad:
```
[2020-10-30T08:55:45.139Z] info - Using generated certificate and key for HTTPS: ~/.local/share/code-server/mymbp_local.crt
```
1. Get the location of the certificate code-server generated; code-server prints
the certificate's location in its logs:
- You can mail it to yourself or if you have a Mac, it's easiest to just Airdrop to the iPad.
```console
[2020-10-30T08:55:45.139Z] info - Using generated certificate and key for HTTPS: ~/.local/share/code-server/mymbp_local.crt
```
3. When opening the `*.crt` file, you'll be prompted to go into settings to install.
4. Go to `Settings -> General -> Profile`, select the profile and then hit `Install`.
- It should say the profile is verified.
5. Go to `Settings -> About -> Certificate Trust Settings` and enable full trust for
the certificate. [more apple support here](https://support.apple.com/en-us/HT204477)
6. Now you can access code-server! 🍻
2. Send the certificate to the iPad, either by emailing it to yourself or using
Apple's Airdrop feature.
### Servediter iPad App
3. Open the `*.crt` file so that you're prompted to go into Settings to install.
If you are unable to get the self signed certificate working or you do not have a domain
name to use, you can use the Servediter iPad App instead!
4. Go to **Settings** > **General** > **Profile**, and select the profile. Tap **Install**.
**note**: This is not an officially supported app by the code-server team!
5. Go to **Settings** > **About** > **Certificate Trust Settings** and [enable
full trust for your certificate](https://support.apple.com/en-us/HT204477).
Download [Serveediter](https://apps.apple.com/us/app/servediter-for-code-server/id1504491325) from the
App Store and then input your server information. If you are running a local server or mabye a usb-c
connected Raspberry Pi, you will input your settings into "Self Hosted Server".
You should be able to access code-server without all of Safari's warnings now.
## Raspberry Pi USB-C Network
**warning**: Your iPad must access code-server via a domain name. It could be local
DNS like `mymacbookpro.local`, but it must be a domain name. Otherwise, Safari will
not allow WebSockets connections.
It is a bit out of scope for this project, however, great success is being reported using iPad on the go with just a single USB-C cable connected to a Raspberry Pi both powering and supplying direct network access. Many support articles already exist but the key steps boil down to turning on Network over USB-C on the Raspberry Pi itself and the rest of the steps are just like getting Code Server running any where else.
## Access code-server using Servediter
Resources worthy of review:
If you are unable to get the self-signed certificate working, or you do not have a domain
name to use, you can use [Servediter for code-server](https://apps.apple.com/us/app/servediter-for-code-server/id1504491325).
- [General intro to Pi as an iPad accessory](https://www.youtube.com/watch?v=IR6sDcKo3V8)
- [iPad with Pi FAQ](https://www.youtube.com/watch?v=SPSlyqo5Q2Q)
- [Technical guide to perform the steps](https://www.geeky-gadgets.com/connect-a-raspberry-pi-4-to-an-ipad-pro-21-01-2020/)
> Servediter for code-server is **not** officially supported by the code-server team!
> Here are my keys to success. I bought a 4" touch screen with fan included that attaches as a case to the Pi. I use the touch screen for anytime I have connection issues, otherwise I turn off the Pi screen. I gave my Pi a network name so I can easily connect at home on wifi or when on go with 1 usb-c cable that supplys both power and network connectivity. Lastly, not all usb-c cables are equal and not all will work so try different usb-c cables if you are going mad (confirm over wifi first then move to cable).
>
> -- <cite>[Acker Apple](http://github.com/ackerapple/)</cite>
To use Servediter:
## Ctrl C Workaround
1. Download the app from the App Store.
2. When prompted, provide your server information. If you are running a local
server or a [Raspberry Pi connected via USB-C](#raspberry-pi-usb-c-network), you will input your settings
into **Self Hosted Server**.
There is currently an issue with `ctrl+c` not stopping a running process in the integrated terminal. We have filed an issue upstream and are tracking [here](https://github.com/microsoft/vscode/issues/114009). As a temporary workaround, it works if you manually define the shortcut like so:
## Raspberry Pi USB-C network
1. Open Command Palette
2. Look for "Preferences: Open Keyboard Shortcuts (JSON)"
3. Add this:
We've heard of users having great success using code-server on an iPad connected
to a Raspberry Pi via USB-C (the Raspberry Pi provides both power and direct
network access). Setting this up requires you to turn on **Network over USB-C**
on the Raspberry Pi, then continuing with code-server as usual on the iPad.
```json
{
"key": "ctrl+c",
"command": "workbench.action.terminal.sendSequence",
"args": {
"text": "\u0003"
},
"when": "terminalFocus"
}
```
For more information, see:
Source: [StackOverflow](https://stackoverflow.com/a/52735954/3015595)
- [General introduction to Pi as an iPad
accessory](https://www.youtube.com/watch?v=IR6sDcKo3V8)
- [iPad with Pi FAQ](https://www.youtube.com/watch?v=SPSlyqo5Q2Q)
- [Technical guide to connecting a Raspberry Pi to an
iPad](https://www.geeky-gadgets.com/connect-a-raspberry-pi-4-to-an-ipad-pro-21-01-2020/)
You may also find the following tips from [Acker
Apple](http://github.com/ackerapple/) helpful:
> Here are my keys to success. I bought a 4" touch screen with fan included that
> attaches as a case to the Pi. I use the touch screen for anytime I have
> connection issues, otherwise I turn off the Pi screen. I gave my Pi a network
> name so I can easily connect at home on wifi or when on go with 1 usb-c cable
> that supplys both power and network connectivity. Lastly, not all usb-c cables
> are equal and not all will work so try different usb-c cables if you are going
> mad (confirm over wifi first then move to cable).
## Recommendations
Once you have code-server accessible to your iPad a few things could help save you time:
Once you can access code-server on your iPad, you may find the following tips
and tricks helpful:
- Use multi-task mode to make code changes and see the browser at the same time
- This prevents the iOS background from dropping an app's state if you are
switching between code-server and browser (with both in full-screen)
- Be sure you are using the debug/terminal that is built into VS Code so that
you don’t need another terminal app running
- This also prevents switching between full screen apps and losing your view
due to iOS' background app memory management
## Known issues
- Getting self-signed certificates to work [is an involved
process](#access-code-server-with-a-self-signed-certificate-on-an-ipad)
- Keyboard issues:
- The keyboard disappear sometimes
[#1313](https://github.com/cdr/code-server/issues/1313),
[#979](https://github.com/cdr/code-server/issues/979)
- Some expectations regarding shortcuts may not be met:
- `cmd + n` opens new browser window instead of new file, and it's difficult
to set alternative as a workaround
- In general, expect to edit your keyboard shortcuts
- There's no escape key by default on the Magic Keyboard, so most users set
the globe key to be an escape key
- Trackpad scrolling does not work
([#1455](https://github.com/cdr/code-server/issues/1455))
- Bug tracking of a WebKit fix
[here](https://bugs.webkit.org/show_bug.cgi?id=210071#c13)
- Tracking of [WebKit patch](https://trac.webkit.org/changeset/270712/webkit)
- Alternatives:
- Install line-jump extension and use keyboard to navigate by jumping large
amount of lines
- Use touch scrolling
- `ctrl+c` does not stop a long-running process in the browser
- Tracking upstream issue here:
[#114009](https://github.com/microsoft/vscode/issues/114009)
- See [workaround](#ctrl-c-workaround)
Additionally, see [issues in the code-server repo that are tagged with the iPad
label](https://github.com/cdr/code-server/issues?q=is%3Aopen+is%3Aissue+label%3AiPad)
for more information.
- Use multi task mode to make code changes and see browser at the same time
- Prevents iOs background dropping an App's state if you are full screen switching between code-server and browser
- Be sure you are using the debug/terminal that is built into VS Code so that you don’t need another terminal app running
- Again, prevents switching between full screen app and losing your view to iOs background app memory management
- You should be of a mindset willing to deal and adapt with differences in having an imperfect experience, for the perceived joyful benefits of interacting with your computer in more intuitive ways
### Workaround for issue with `ctrl+c` not stopping a running process in the terminal
## By 2022 iPad coding more desirable on Arm Macs
This's currently an issue with `ctrl+c` not stopping a running process in the
integrated terminal. We have filed an issue upstream and are tracking
[here](https://github.com/microsoft/vscode/issues/114009).
> This section is generalized opinions intended to inform fellow Apple product consumers of perceived over time changes coming down the line
In the meantime, you can manually define a shortcut as a workaround:
The general feeling from overall Apple movements recently, is that the Mac arm processors are in fact helping support the direction of having Macs with touch screens. Many great YouTube videos of interest call out highly suggestive evidence. In the past Apple has hard declared reasons of body fatigue and such as why not to encourage nor further developments on the iPad touch experience mixed with a keyboard/mouse/trackpad. Regardless, products and software have been released further supporting just that very experience.
1. Open the Command Palette
2. Look for **Preferences: Open Keyboard Shortcuts (JSON)**
3. Add the following snippet:
The iPad coding experience has been a joy for some of us that are willing to trade an imperfect experience for a uniquely effective focus driven experience. Note worthy, some of us think it's a trashy waste of time. This experience is undoubtably going to get better just by the work that can be seen by all parties, even in our own code-server attempt to make it better.
```json
{
"key": "ctrl+c",
"command": "workbench.action.terminal.sendSequence",
"args": {
"text": "\u0003"
},
"when": "terminalFocus"
}
```
Lastly, it is note worthy that if you have decided to incorporate a Raspberry Pi into you iPad coding experience, they are Arm processors. You are perfectly lined up with the future of Macs as well.
_Source: [StackOverflow](https://stackoverflow.com/a/52735954/3015595)_
docs/npm.md
浏览文件 @ c1450084
......@@ -2,23 +2,28 @@
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
# npm Install Requirements
- [Node.js version](#nodejs-version)
- [Ubuntu, Debian](#ubuntu-debian)
- [Fedora, CentOS, RHEL](#fedora-centos-rhel)
- [Alpine](#alpine)
- [macOS](#macos)
- [FreeBSD](#freebsd)
- [Issues with Node.js after version upgrades](#issues-with-nodejs-after-version-upgrades)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
If you're installing the npm module you'll need certain dependencies to build the native modules used by VS Code.
If you're installing code-server via `npm`, you'll need to install additional
dependencies required to build the native modules used by VS Code. This article
includes installing instructions based on your operating system.
- Node.js: version `= 14`. Other versions may work, but your mileage may vary.
## Node.js version
_Note: We use the same major version of Node.js that is shipped in VSCode's Electron. VS Code also lists Node.js requirements. See [here](https://github.com/microsoft/vscode/wiki/How-to-Contribute#prerequisites)._
We use the same major version of Node.js shipped with VSCode's Electron,
which is currently `14.x`. VS Code also [lists Node.js
requirements](https://github.com/microsoft/vscode/wiki/How-to-Contribute#prerequisites).
Related:
- [#1633](https://github.com/cdr/code-server/issues/1633)
Using other versions of Node.js [may lead to unexpected
behavior](https://github.com/cdr/code-server/issues/1633).
## Ubuntu, Debian
......@@ -58,3 +63,22 @@ xcode-select --install
pkg install -y git python npm-node14 yarn-node14 pkgconf
pkg install -y libinotify
```
## Issues with Node.js after version upgrades
Occasionally, you may run into issues with Node.js.
If you install code-server using `yarn` or `npm`, and you upgrade your Node.js
version, you may need to reinstall code-server to recompile native modules.
Sometimes, you can get around this by navigating into code-server's `lib/vscode`
directory and running `npm rebuild` to recompile the modules.
A step-by-step example of how you might do this is:
1. Install code-server: `brew install code-server`
2. Navigate into the directory: `cd /usr/local/Cellar/code-server/<version>/libexec/lib/vscode/`
3. Recompile the native modules: `npm rebuild`
4. Restart code-server
If you need further assistance, post on our [GitHub Discussions
page](https://github.com/cdr/code-server/discussions).
docs/requirements.md 0 → 100644
浏览文件 @ c1450084
# Requirements
You'll need a machine on which you can run code-server. You can use a physical
machine you have, or you can use a VM on GCP/AWS.
At the minimum, we recommend:
- 1 GB of RAM
- 2 CPU cores
You can use any Linux distribution, but [our
docs](https://coder.com/docs/code-server/v3.10.2/guide) assume that you're using
Debian hosted by Google Cloud (see the following section for instructions on
setting this up).
Your environment must have WebSockets enabled, since code-server uses WebSockets
for communication between the browser and the server.
## Set up a VM on Google Cloud
The following steps walk you through setting up a VM running Debian using Google
Cloud (though you are welcome to use any machine or VM provider).
If you're [signing up with Google](https://console.cloud.google.com/getting-started) for the first time, you should get a 12-month trial with
$300 of credits.
After you sign up and create a new Google Cloud Provider (GCP) project, create a
new Compute Engine VM instance:
1. Using the sidebar, navigate to **Compute Engine** > **VM Instances**.
2. Click **Create Instance**.
3. Provide a **name** for new instance.
4. Choose the **region** that's closest to you based on [GCP
ping](https://gcping.com/).
5. Choose a **zone** (any option is fine).
6. We recommend choose an **E2 series instance** from the [general-purpose
family](https://cloud.google.com/compute/docs/machine-types#general_purpose).
7. Change the instance type to **custom** and set at least **2 cores** and **2
GB of RAM**. You can add more resources if desired, though you can also edit
your instance at a later point.
8. Though optional, we highly recommend switching the persistent disk to an SSD
with at least 32 GB. To do so, click **change** under **Boot Disk**. Then,
change the type to **SSD Persistent Disk**, and set the size to **32**. (You
can also grow your disk at a later date).
9. Go to **Networking** > **Networking Interfaces** and edit the existing
interface to use a static internal IP. Click **Done** to save.
10. If you don't have a [project-wide SSH
key](https://cloud.google.com/compute/docs/instances/adding-removing-ssh-keys#project-wide),
go to **Security** > **SSH Keys** to add your public key.
11. Click **Create** to proceed.
Notes:
- To lower costs, you can shut down your server when you're not using it.
- We recommend using the `gcloud cli` to avoid using the GCP Dashboard if possible.
docs/termux.md
浏览文件 @ c1450084
......@@ -2,69 +2,70 @@
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
# Termux
- [Termux](#termux)
- [Installation](#installation)
- [Upgrading](#upgrading)
- [Known Issues](#known-issues)
- [Search issue](#search-issue)
- [Backspace not working](#backspace-not-working)
- [Install](#install)
- [Upgrade](#upgrade)
- [Known Issues](#known-issues)
- [Search doesn't work](#search-doesnt-work)
- [Backspace doesn't work](#backspace-doesnt-work)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
# Termux
Termux is an Android terminal application and Linux environment, which can also run code-server from your phone.
Termux is a terminal application and Linux environment that you can also use to
run code-server from your Android phone.
## Installation
## Install
1. Install Termux from [F-Droid](https://f-droid.org/en/packages/com.termux/)
2. Make sure it's up-to-date by running `apt update && apt upgrade`
3. Install required packages: `apt install build-essential python git nodejs yarn`
4. Install code-server: `yarn global add code-server`
5. Run code-server: `code-server` and navigate to localhost:8080 in your browser
1. Install Termux from [F-Droid](https://f-droid.org/en/packages/com.termux/).
1. Make sure it's up-to-date: `apt update && apt upgrade`
1. Install required packages: `apt install build-essential python git nodejs yarn`
1. Install code-server: `yarn global add code-server`
1. Run code-server: `code-server` and navigate to localhost:8080 in your browser
## Upgrading
## Upgrade
To upgrade run: `yarn global upgrade code-server --latest`
## Known Issues
### Search issue
The following details known issues and suggested workarounds for using
code-server with Termux.
There is a known issue with search not working on Android because it's missing `bin/rg`. To fix:
### Search doesn't work
There is a known issue with search not working on Android because it's missing
`bin/rg` ([context](https://github.com/cdr/code-server/issues/1730#issuecomment-721515979)). To fix this:
1. Install `ripgrep` with `pkg`
```sh
pkg install ripgrep
```
2. Make a soft link using `ln -s`
```sh
# run this command inside the code-server directory
ln -s $PREFIX/bin/rg ./lib/vscode/node_modules/vscode-ripgrep/bin/rg
```
1. Make a soft link using `ln -s`
For more context, see [comment](https://github.com/cdr/code-server/issues/1730#issuecomment-721515979).
```sh
# run this command inside the code-server directory
ln -s $PREFIX/bin/rg ./lib/vscode/node_modules/vscode-ripgrep/bin/rg
```
### Backspace not working
### Backspace doesn't work
There is a known issue with the backspace key not working correctly when using the on-screen keyboard on Android. This is due to an upstream issue. Read more:
When using Android's on-screen keyboard, the backspace key doesn't work
properly. This is a known upstream issue:
- [Issues with Backspace in Codespaces on Android (Surface Duo)](https://github.com/microsoft/vscode/issues/107602)
- [Issues with backspace in Codespaces on Android (Surface Duo)](https://github.com/microsoft/vscode/issues/107602)
- [Support mobile platforms](https://github.com/xtermjs/xterm.js/issues/1101)
Workaround #1: Modify Keyboard Dispatch Settings
There are two workarounds.
**Option 1:** Modify keyboard dispatch settings
1. Open the Command Palette
2. Search for "Preferences: Open Settings (JSON)"
2. Search for **Preferences: Open Settings (JSON)**
3. Add `"keyboard.dispatch": "keyCode"`
The backspace button should work now.
(Thanks to @Nefomemes for the suggestion! See [comment](https://github.com/cdr/code-server/issues/1141#issuecomment-789463707))
Workaround #2: use a Bluetooth keyboard.
The backspace button should work at this point.
For more context, see issues:
_Thanks to @Nefomemes for the [suggestion](https://github.com/cdr/code-server/issues/1141#issuecomment-789463707)!_
- [500 error: 3.9.2 not working on Android + Termux](https://github.com/cdr/code-server/issues/3036)
- [Issue #3079](https://github.com/cdr/code-server/issues/3079)
**Option 2:** Use a Bluetooth keyboard.
docs/triage.md
浏览文件 @ c1450084
# Triage
## Filter
Triaging code-server issues is done with the following issue filter:
```
```text
is:issue is:open no:project sort:created-asc -label:blocked -label:upstream -label:waiting-for-info -label:extension-request
```
This will show issues that:
1. Are open.
2. Have no assigned project.
3. Are not `blocked` or tagged for work by `upstream` (VS Code core team)
- If an upstream issue is detrimental to the code-server experience we may fix it in
our patch instead of waiting for the VS Code team to fix it.
- Someone should periodically go through these issues to see if they can be unblocked
though!
4. Are not in `waiting-for-info`.
5. Are not extension requests.
## Process
1. If an issue is a question/discussion it should be converted into a GitHub discussion.
2. Next, give the issue the appropriate labels and feel free to create new ones if
necessary.
- There are no hard and set rules for labels. We don't have many so look through and
see how they've been used throughout the repository. They all also have descriptions.
3. If more information is required, please ask the submitter and tag as
1. Have no assigned project.
1. Are not `blocked` or tagged for work by `upstream` (the VS Code core team).
If an upstream issue is detrimental to the code-server experience we may fix
it in our patch instead of waiting for the VS Code team to fix it. Someone
should periodically go through these issues to see if they can be unblocked!
1. Are not labeled `waiting-for-info`.
1. Are not extension requests.
## Triage process
1. If an issue is a question/discussion, it should be converted into a GitHub
discussion.
1. Otherwise, give the issue the appropriate labels (feel free to create new
ones if necessary). There are no hard and set rules for labels. We don't have
many so look through and see how they've been used throughout the repository.
They all also have descriptions.
1. If more information is required, please ask the submitter and tag as
`waiting-for-info` and wait.
4. Finally, the issue should be moved into the
[code-server](https://github.com/cdr/code-server/projects/1) project where we pick
out issues to fix and track their progress.
1. Finally, the issue should be moved into the
[code-server](https://github.com/cdr/code-server/projects/1) project where we
pick out issues to fix and track their progress.
We also use [milestones](https://github.com/cdr/code-server/milestones) to track what
issues are planned/or were closed for what release.
We also use [milestones](https://github.com/cdr/code-server/milestones) to track
what issues are planned/or were closed for what release.
docs/upgrade.md 0 → 100644
浏览文件 @ c1450084
# Upgrade
To upgrade code-server, install the new version over the old version. All user
data is in `~/.local/share/code-server`, so they are preserved between
installations.
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或