Merge pull request #1628 from cdr/docs

Revamp docs
coder · May 17, 2020 · e955da1 · e955da1
2 parents 8626bed + 52eecca
commit e955da1
Show file tree

Hide file tree

Showing 49 changed files with 1,325 additions and 497 deletions.
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -3,6 +3,24 @@ name: ci
 on: [push, pull_request]
 
 jobs:
+  fmt:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v1
+      - name: Run ./ci/steps/fmt.sh
+        uses: ./ci/container
+        with:
+          args: ./ci/steps/fmt.sh
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v1
+      - name: Run ./ci/steps/lint.sh
+        uses: ./ci/container
+        with:
+          args: ./ci/steps/lint.sh
+
   test:
     runs-on: ubuntu-latest
     steps:
@@ -88,3 +106,43 @@ jobs:
         with:
           name: release-packages
           path: ./release-packages
+
+  docker-amd64:
+    runs-on: ubuntu-latest
+    needs: linux-amd64
+    steps:
+      - uses: actions/checkout@v1
+      - name: Download release package
+        uses: actions/download-artifact@v2
+        with:
+          name: release-packages
+          path: ./release-packages
+      - name: Run ./ci/steps/build-docker-image.sh
+        uses: ./ci/container
+        with:
+          args: ./ci/steps/build-docker-image.sh
+      - name: Upload release image
+        uses: actions/upload-artifact@v2
+        with:
+          name: release-images
+          path: ./release-images
+
+  docker-arm64:
+    runs-on: ubuntu-arm64-latest
+    needs: linux-arm64
+    steps:
+      - uses: actions/checkout@v1
+      - name: Download release package
+        uses: actions/download-artifact@v2
+        with:
+          name: release-packages
+          path: ./release-packages
+      - name: Run ./ci/steps/build-docker-image.sh
+        uses: ./ci/container
+        with:
+          args: ./ci/steps/build-docker-image.sh
+      - name: Upload release image
+        uses: actions/upload-artifact@v2
+        with:
+          name: release-images
+          path: ./release-images
diff --git a/.github/workflows/publish.yaml b/.github/workflows/publish.yaml
@@ -13,29 +13,19 @@ jobs:
         uses: ./ci/container
         with:
           args: ./ci/steps/publish-npm.sh
-          env:
-            NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
 
-  docker-amd64:
+  docker:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v1
-      - name: Run ./ci/steps/publish-docker.sh
+      - name: Run ./ci/steps/push-docker-manifest.sh
         uses: ./ci/container
         with:
-          args: ./ci/steps/publish-docker.sh
-          env:
-            DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
-            DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}
-
-  docker-arm64:
-    runs-on: ubuntu-arm64-latest
-    steps:
-      - uses: actions/checkout@v1
-      - name: Run ./ci/steps/publish-docker.sh
-        uses: ./ci/container
-        with:
-          args: ./ci/steps/publish-docker.sh
-          env:
-            DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
-            DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}
+          args: ./ci/steps/push-docker-manifest.sh
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
+          DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}
diff --git a/.gitignore b/.gitignore
@@ -6,4 +6,5 @@ release/
 release-static/
 release-packages/
 release-gcp/
+release-images/
 node_modules
diff --git a/README.md b/README.md
@@ -1,47 +1,95 @@
 # code-server
 
-`code-server` is [VS Code](https://github.com/Microsoft/vscode) running on a
-remote server, accessible through the browser.
+Run [VS Code](https://github.com/Microsoft/vscode) on any machine anywhere and access it in the browser.
 
-Try it out:
+- **Code everywhere:** Code on your Chromebook, tablet, and laptop with a
+  consistent dev environment. Develop on a Linux machine and pick up from any
+  device with a web browser.
+- **Server-powered:** Take advantage of large cloud servers to speed up tests, compilations, downloads, and more.
+  Preserve battery life when you're on the go since all intensive tasks runs on your server.
+  Make use of a spare computer you have lying around and turn it into a full development environment.
+
+![Example gif](./doc/assets/code-server.gif)
+
+## Getting started
+
+For a full setup and walkthrough, please see [./doc/guide.md](./doc/guide.md).
+
+### Debian, Ubuntu
 
 ```bash
-docker run -it -p 127.0.0.1:8080:8080 -v "$PWD:/home/coder/project" -u "$(id -u):$(id -g)" codercom/code-server:latest
+curl -sSOL https://github.com/cdr/code-server/releases/download/3.3.0/code-server_3.3.0_amd64.deb
+sudo dpkg -i code-server_3.3.0_amd64.deb
+systemctl --user enable --now code-server
+# Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml
 ```
 
-- **Code anywhere:** Code on your Chromebook, tablet, and laptop with a
-  consistent dev environment. Develop on a Linux machine and pick up from any
-  device with a web browser.
-- **Server-powered:** Take advantage of large cloud servers to speed up tests,
-  compilations, downloads, and more. Preserve battery life when you're on the go
-  since all intensive computation runs on your server.
+### Fedora, Red Hat, SUSE
+
+```bash
+curl -sSOL https://github.com/cdr/code-server/releases/download/3.3.0/code-server-3.3.0-amd64.rpm
+sudo yum install -y code-server-3.3.0-amd64.rpm
+systemctl --user enable --now code-server
+# Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml
+```
+
+### npm
 
-![Example gif](/doc/assets/code-server.gif)
+We recommend installing from `npm` if we don't have a precompiled release for your machine's
+platform or architecture.
 
-## Getting Started
+**note:** Installing via `npm` builds native modules on install and so requires C dependencies.
+See [./doc/npm.md](./doc/npm.md) for installing these dependencies.
 
-### Requirements
+You will need at least node v12 installed. See [#1633](https://github.com/cdr/code-server/issues/1633).
 
-- 64-bit host.
-- At least 1GB of RAM.
-- 2 cores or more are recommended (1 core works but not optimally).
-- Secure connection over HTTPS or localhost (required for service workers and
-  clipboard support).
-- For Linux: GLIBC 2.17 or later and GLIBCXX 3.4.15 or later.
+```bash
+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
+brew install code-server
+brew services start code-server
+# Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml
+```
 
-### Run over SSH
+### Docker
 
-Use [sshcode](https://github.com/codercom/sshcode) for a simple setup.
+```bash
+# This will start a code-server container and expose it at http://127.0.0.1:8080.
+# It will also mount your current directory into the container as `/home/coder/project`
+# and forward your UID/GID so that all file system operations occur as your user outside
+# the container.
+docker run -it -p 127.0.0.1:8080:8080 \
+  -v "$PWD:/home/coder/project" \
+  -u "$(id -u):$(id -g)" \
+  codercom/code-server:latest
+```
+
+### Static releases
 
-### Digital Ocean
+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 compiled native modules.
 
-[![Create a Droplet](./doc/assets/droplet.svg)](https://marketplace.digitalocean.com/apps/code-server)
+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`.
 
-### Releases
+Add the code-server `bin` directory to your `$PATH` to easily execute `code-server` without the full path every time.
 
-1. [Download a release](https://github.com/cdr/code-server/releases). (Linux and macOS supported. Windows support planned.)
-2. Unpack the downloaded release then run the included `code-server` script.
-3. In your browser navigate to `localhost:8080`.
+Here is an example script for installing and using a static `code-server` release on Linux:
+
+```bash
+curl -sSL https://github.com/cdr/code-server/releases/download/3.3.0/code-server-3.3.0-linux-amd64.tar.gz | sudo tar -C /usr/local -xz
+sudo mv /usr/local/code-server-3.3.0-linux-amd64 /usr/local/code-server
+PATH="$PATH:/usr/local/code-server/bin"
+code-server
+# Now visit http://127.0.0.1:8080. Your password is in ~/.config/code-server/config.yaml
+```
 
 ## FAQ
 
@@ -53,5 +101,5 @@ See [./doc/CONTRIBUTING.md](./doc/CONTRIBUTING.md).
 
 ## Enterprise
 
-Visit [our enterprise page](https://coder.com) for more information about our
+Visit [our website](https://coder.com) for more information about our
 enterprise offerings.