code-server/docs/npm.md

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- 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)
- [Windows](#windows)
- [Installing](#installing)
- [Troubleshooting](#troubleshooting)
  - [Issues with Node.js after version upgrades](#issues-with-nodejs-after-version-upgrades)
  - [Debugging install issues with npm](#debugging-install-issues-with-npm)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

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

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).

Using other versions of Node.js [may lead to unexpected
behavior](https://github.com/cdr/code-server/issues/1633).

## Ubuntu, Debian

```bash
sudo apt-get install -y \
  build-essential \
  pkg-config \
  python3
npm config set python python3
```

Proceed to [installing](#installing)

## Fedora, CentOS, RHEL

```bash
sudo yum groupinstall -y 'Development Tools'
sudo yum config-manager --set-enabled PowerTools # unnecessary on CentOS 7
sudo yum install -y python2
npm config set python python2
```

Proceed to [installing](#installing)

## Alpine

```bash
apk add alpine-sdk bash libstdc++ libc6-compat
npm config set python python3
```

Proceed to [installing](#installing)

## macOS

```bash
xcode-select --install
```

Proceed to [installing](#installing)

## FreeBSD

```sh
pkg install -y git python npm-node14 yarn-node14 pkgconf
pkg install -y libinotify
```

Proceed to [installing](#installing)

## Windows

Installing code-server requires all of the [prerequisites for VS Code development](https://github.com/Microsoft/vscode/wiki/How-to-Contribute#prerequisites). When installing the C++ compiler tool chain, we recommend using "Option 2: Visual Studio 2019" for best results.

Next, install code-server with:

```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
```

A `postinstall.sh` script will attempt to run. Select your terminal (e.g., Git bash) as the default application for `.sh` files. If an additional dialog does not appear, run the install command again.

If the `code-server` command is not found, you'll need to [add a directory to your PATH](https://www.architectryan.com/2018/03/17/add-to-the-path-on-windows-10/). To find the directory, use the following command:

```shell
yarn global bin
# Or: npm config get prefix
```

For help and additional troubleshooting, see [#1397](https://github.com/cdr/code-server/issues/1397).

## Installing

After adding the dependencies for your OS, install the code-server package globally:

```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
```

## Troubleshooting

If you need further assistance, post on our [GitHub Discussions
page](https://github.com/cdr/code-server/discussions).

### 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

### Debugging install issues with npm

`yarn` suppresses logs when running `yarn global add`, so to debug installation issues, install with `npm` instead:

```shell
# Uninstall
npm uninstall -g --unsafe-perm code-server > /dev/null 2>&1

# Install with logging
npm install --loglevel verbose -g --unsafe-perm code-server
```
Rename container and release-container to images and release-image 2020-06-04 00:07:42 +08:00			`<!-- START doctoc generated TOC please keep comment here to allow auto update -->`
			`<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->`
format 2021-08-23 02:50:49 +08:00			`# npm Install Requirements`
Document npm module install dependencies 2020-05-13 11:11:31 +08:00
refactor(docs): clean up and restructure 2021-07-08 00:00:51 +08:00			`- [Node.js version](#nodejs-version)`
feat: update node version engine in package.json 2021-03-10 05:47:23 +08:00			`- [Ubuntu, Debian](#ubuntu-debian)`
			`- [Fedora, CentOS, RHEL](#fedora-centos-rhel)`
			`- [Alpine](#alpine)`
			`- [macOS](#macos)`
			`- [FreeBSD](#freebsd)`
format 2021-08-23 02:50:49 +08:00			`- [Windows](#windows)`
			`- [Installing](#installing)`
			`- [Troubleshooting](#troubleshooting)`
			`- [Issues with Node.js after version upgrades](#issues-with-nodejs-after-version-upgrades)`
docs: add note about npm logging 2021-08-25 06:25:04 +08:00			`- [Debugging install issues with npm](#debugging-install-issues-with-npm)`
Rename container and release-container to images and release-image 2020-06-04 00:07:42 +08:00
			`<!-- END doctoc generated TOC please keep comment here to allow auto update -->`

refactor(docs): clean up and restructure 2021-07-08 00:00:51 +08:00			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.`
Document npm module install dependencies 2020-05-13 11:11:31 +08:00
refactor(docs): clean up and restructure 2021-07-08 00:00:51 +08:00			`## Node.js version`
docs(npm): update node requirements 2021-03-10 02:20:14 +08:00
refactor(docs): clean up and restructure 2021-07-08 00:00:51 +08:00			`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).`
docs(npm): update node requirements 2021-03-10 02:20:14 +08:00
refactor(docs): clean up and restructure 2021-07-08 00:00:51 +08:00			`Using other versions of Node.js [may lead to unexpected`
			`behavior](https://github.com/cdr/code-server/issues/1633).`
Require minimum node 12 2020-05-15 09:37:58 +08:00
Document npm module install dependencies 2020-05-13 11:11:31 +08:00			`## Ubuntu, Debian`

			```bash
			`sudo apt-get install -y \`
			`build-essential \`
			`pkg-config \`
doc: Update npm docs for debian sid There is no python package anymore, you have to explicitly pick which version of python to install and we need to inform npm of the executable name. 2020-08-27 01:54:42 +08:00			`python3`
			`npm config set python python3`
Document npm module install dependencies 2020-05-13 11:11:31 +08:00			```

clean up npm docs and add Windows 10 instructions 2021-08-23 01:36:41 +08:00			`Proceed to [installing](#installing)`

Add install.sh into README.md 2020-05-21 00:13:03 +08:00			`## Fedora, CentOS, RHEL`
Document npm module install dependencies 2020-05-13 11:11:31 +08:00
			```bash
			`sudo yum groupinstall -y 'Development Tools'`
Stop bundling libraries in release - Instead we now use CentOS 7 for the static build to guarantee that we only depend on libc v2.17 - For macOS we now pull in a static node binary and bundle that instead. 2020-06-03 23:41:13 +08:00			`sudo yum config-manager --set-enabled PowerTools # unnecessary on CentOS 7`
fix(lib/vscode): remove native-keymap and keytar (#2961) native-keymap and keytar are only used in the electron process, so we don't need them. This allows us to drop our dependencies on libx11-dev, libxkbfile-dev, and libsecret-dev. 2021-03-26 00:50:58 +08:00			`sudo yum install -y python2`
Document npm module install dependencies 2020-05-13 11:11:31 +08:00			`npm config set python python2`
			```

clean up npm docs and add Windows 10 instructions 2021-08-23 01:36:41 +08:00			`Proceed to [installing](#installing)`

doc/npm.md: Update docs for Alpine Linux (#2479) 2020-12-19 02:08:36 +08:00			`## Alpine`

			```bash
fix(lib/vscode): remove native-keymap and keytar (#2961) native-keymap and keytar are only used in the electron process, so we don't need them. This allows us to drop our dependencies on libx11-dev, libxkbfile-dev, and libsecret-dev. 2021-03-26 00:50:58 +08:00			`apk add alpine-sdk bash libstdc++ libc6-compat`
doc/npm.md: Update docs for Alpine Linux (#2479) 2020-12-19 02:08:36 +08:00			`npm config set python python3`
			```

clean up npm docs and add Windows 10 instructions 2021-08-23 01:36:41 +08:00			`Proceed to [installing](#installing)`

Document npm module install dependencies 2020-05-13 11:11:31 +08:00			`## macOS`
doc/npm.md: Fix formatting 2020-12-04 15:34:18 +08:00
Document npm module install dependencies 2020-05-13 11:11:31 +08:00			```bash
			`xcode-select --install`
			```
doc/npm.md: Document npm module dependencies for FreeBSD 2020-12-15 07:25:08 +08:00
clean up npm docs and add Windows 10 instructions 2021-08-23 01:36:41 +08:00			`Proceed to [installing](#installing)`

doc/npm.md: Document npm module dependencies for FreeBSD 2020-12-15 07:25:08 +08:00			`## FreeBSD`

			```sh
chore: update node to v14 (#3481) 2021-06-02 01:19:03 +08:00			`pkg install -y git python npm-node14 yarn-node14 pkgconf`
fix(lib/vscode): remove native-keymap and keytar (#2961) native-keymap and keytar are only used in the electron process, so we don't need them. This allows us to drop our dependencies on libx11-dev, libxkbfile-dev, and libsecret-dev. 2021-03-26 00:50:58 +08:00			`pkg install -y libinotify`
doc/npm.md: Document npm module dependencies for FreeBSD 2020-12-15 07:25:08 +08:00			```
refactor(docs): clean up and restructure 2021-07-08 00:00:51 +08:00
clean up npm docs and add Windows 10 instructions 2021-08-23 01:36:41 +08:00			`Proceed to [installing](#installing)`

			`## Windows`

			`Installing code-server requires all of the [prerequisites for VS Code development](https://github.com/Microsoft/vscode/wiki/How-to-Contribute#prerequisites). When installing the C++ compiler tool chain, we recommend using "Option 2: Visual Studio 2019" for best results.`

			`Next, install code-server with:`

			```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`
			```

Update docs/npm.md Co-authored-by: Katie Horne <katie@coder.com> 2021-08-24 00:06:34 +08:00			A `postinstall.sh` script will attempt to run. Select your terminal (e.g., Git bash) as the default application for `.sh` files. If an additional dialog does not appear, run the install command again.
clean up npm docs and add Windows 10 instructions 2021-08-23 01:36:41 +08:00
fix typo 2021-08-23 01:45:09 +08:00			If the `code-server` command is not found, you'll need to [add a directory to your PATH](https://www.architectryan.com/2018/03/17/add-to-the-path-on-windows-10/). To find the directory, use the following command:
clean up npm docs and add Windows 10 instructions 2021-08-23 01:36:41 +08:00
			```shell
			`yarn global bin`
			`# Or: npm config get prefix`
			```

			`For help and additional troubleshooting, see [#1397](https://github.com/cdr/code-server/issues/1397).`

			`## Installing`

Update docs/npm.md Co-authored-by: Katie Horne <katie@coder.com> 2021-08-24 00:06:44 +08:00			`After adding the dependencies for your OS, install the code-server package globally:`
clean up npm docs and add Windows 10 instructions 2021-08-23 01:36:41 +08:00
			```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`
			```

			`## Troubleshooting`

			`If you need further assistance, post on our [GitHub Discussions`
			`page](https://github.com/cdr/code-server/discussions).`

			`### Issues with Node.js after version upgrades`
refactor(docs): clean up and restructure 2021-07-08 00:00:51 +08:00
			`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`
docs: add note about npm logging 2021-08-25 06:25:04 +08:00
			`### Debugging install issues with npm`

docs: fix typos and wording in npm 2021-08-25 07:35:13 +08:00			`yarn` suppresses logs when running `yarn global add`, so to debug installation issues, install with `npm` instead:
docs: add note about npm logging 2021-08-25 06:25:04 +08:00
			```shell
			`# Uninstall`
			`npm uninstall -g --unsafe-perm code-server > /dev/null 2>&1`

			`# Install with logging`
			`npm install --loglevel verbose -g --unsafe-perm code-server`
			```