From 272962cfae74cff1ce228d8af3fbb84375afc38e Mon Sep 17 00:00:00 2001 From: Eric Paulsen Date: Wed, 10 Aug 2022 18:56:21 -0400 Subject: [PATCH] docs: add upgrade page & update getting started (#3439) --- docs/install.md | 10 +++----- docs/install/configure.md | 50 ++++++++++++++++++++++++++++++++++++++ docs/install/upgrade.md | 39 +++++++++++++++++++++++++++++ docs/manifest.json | 10 ++++++++ docs/quickstart/generic.md | 27 +++++++++++++------- docs/templates.md | 2 +- 6 files changed, 122 insertions(+), 16 deletions(-) create mode 100644 docs/install/configure.md create mode 100644 docs/install/upgrade.md diff --git a/docs/install.md b/docs/install.md index 64669f1d7f..d9652ad853 100644 --- a/docs/install.md +++ b/docs/install.md @@ -46,7 +46,7 @@ journalctl -u coder.service -b Before proceeding, please ensure that you have both Docker and the [latest version of Coder](https://github.com/coder/coder/releases) installed. -> See our [docker-compose](https://github.com/coder/coder/blob/93b78755a6d48191cc53c82654e249f25fc00ce9/docker-compose.yaml) file +> See our [docker-compose](https://github.com/coder/coder/blob/main/docker-compose.yaml) file > for additional information. 1. Clone the `coder` repository: @@ -87,8 +87,6 @@ Coder](https://github.com/coder/coder/releases) installed. 3. Follow the on-screen instructions to create your first template and workspace ---- - If the user is not in the Docker group, you will see the following error: ```sh @@ -130,7 +128,7 @@ We publish self-contained .zip and .tar.gz archives in [GitHub releases](https:/ coder server --postgres-url --access-url ``` -## Next steps +## Up Next -Once you've installed and started Coder, see the [quickstart](./quickstart.md) -for instructions on creating your first template and workspace. +- Learn how to [configure](./install/configure.md) Coder. +- Learn about [upgrading](./install/upgrade.md) Coder. diff --git a/docs/install/configure.md b/docs/install/configure.md new file mode 100644 index 0000000000..bbfd5526de --- /dev/null +++ b/docs/install/configure.md @@ -0,0 +1,50 @@ +# Configure + +This article documents the Coder server's primary configuration variables. For a full list +of the options, run `coder server --help` on the host. + +Once you've [installed](../install.md) Coder, you can configure the server by setting the following +variables in `/etc/coder.d/coder.env`: + +```sh +# String. Specifies the external URL (HTTP/S) to access Coder. Consumes $CODER_ACCESS_URL +CODER_ACCESS_URL=https://coder.example.com + +# String. Address to serve the API and dashboard. Consumes $CODER_ADDRESS (default "127.0.0.1:3000") +CODER_ADDRESS=127.0.0.1:3000 + +# String. The URL of a PostgreSQL database to connect to. If empty, PostgreSQL binaries +# will be downloaded from Maven (https://repo1.maven.org/maven2) and store all +# data in the config root. Access the built-in database with "coder server postgres-builtin-url". +# Consumes $CODER_PG_CONNECTION_URL. +CODER_PG_CONNECTION_URL="" + +# Boolean. Specifies if TLS will be enabled. Consumes $CODER_TLS_ENABLE. +CODER_TLS_ENABLE= + +# Specifies the path to the certificate for TLS. It requires a PEM-encoded file. +# To configure the listener to use a CA certificate, concatenate the primary +# certificate and the CA certificate together. The primary certificate should +# appear first in the combined file. Consumes $CODER_TLS_CERT_FILE. +CODER_TLS_CERT_FILE= + +# Specifies the path to the private key for the certificate. It requires a +# PEM-encoded file. Consumes $CODER_TLS_KEY_FILE. +CODER_TLS_KEY_FILE= +``` + +## Run Coder + +Now, run Coder as a system service on the host: + +```sh +# Use systemd to start Coder now and on reboot +sudo systemctl enable --now coder +# View the logs to ensure a successful start +journalctl -u coder.service -b +``` + +## Up Next + +- [Get started using Coder](./quickstart.md). +- [Learn how to upgrade Coder](./upgrade.md). diff --git a/docs/install/upgrade.md b/docs/install/upgrade.md new file mode 100644 index 0000000000..102efd1499 --- /dev/null +++ b/docs/install/upgrade.md @@ -0,0 +1,39 @@ +# Upgrade + +This article walks you through how to upgrade your Coder server. + +To upgrade your Coder server, simply reinstall Coder using your original method +of [install](../install.md). + +
+

+ Prior to upgrading a production Coder deployment, take a database snapshot since + Coder does not support rollbacks. +

+
+ +## Via install.sh + +If you installed Coder using the `install.sh` script, simply re-run the below +command on the host: + +```console +curl -L https://coder.com/install.sh | sh +``` + +The script will unpack the new `coder` binary version over the one currently installed. +Next, you can restart Coder with the following command (if running it as a system +service): + +```console +systemctl restart coder +``` + +## Via docker-compose + +If you installed using `docker-compose`, run the below command to upgrade the +Coder container: + +```console +docker-compose pull coder && docker-compose up coder -d +``` diff --git a/docs/manifest.json b/docs/manifest.json index 20176617a0..8644efc33e 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -29,6 +29,16 @@ "title": "Authentication", "description": "Learn how to set up authentication using GitHub or OpenID Connect.", "path": "./install/auth.md" + }, + { + "title": "Configuration", + "description": "Learn how to configure Coder", + "path": "./install/configure.md" + }, + { + "title": "Upgrade", + "description": "Learn how to upgrade Coder.", + "path": "./install/upgrade.md" } ] }, diff --git a/docs/quickstart/generic.md b/docs/quickstart/generic.md index b758a64c26..595777af9e 100644 --- a/docs/quickstart/generic.md +++ b/docs/quickstart/generic.md @@ -1,17 +1,22 @@ +# Getting Started + +This article will walk you through how to set up your first Coder user, and begin +using the templates to create and access your development workspaces. + ## Prerequisites -Please [install Coder](./install.md) before proceeding with the steps outlined in this article. +Please [install Coder](../install.md) before proceeding with the steps below. ## First time admin user setup -1. Run `coder login ` in a new terminal and follow the +1. Run `coder login ` in a new terminal and follow the interactive instructions to create your admin user and password. > If using `coder server --tunnel`, the Access URL appears in the terminal logs. -## Creating your first template and workspace +## Templates -In a new terminal window, run the following to copy a sample template: +To get started using templates, run the following command to generate a sample template: ```bash coder templates init @@ -25,7 +30,9 @@ specific usage (e.g., a template to **Develop code-server in Docker**): 1. Answer the CLI prompts; when done, confirm that you want to create your template. -Create a workspace using your template: +## Create a workspace + +Now, create a workspace using your template: ```bash coder create --template="yourTemplate" @@ -37,10 +44,8 @@ Connect to your workspace via SSH: coder ssh ``` -You can also access your workspace using the **access URL** you provided when -deploying Coder (if you're using a temporary deployment and you opted to use -Coder's tunnel, use the access URL you were provided). Log in with the admin -credentials provided to you by Coder. +To access your workspace in the Coder dashboard, navigate to the [configured access URL](../configure.md), +and log in with the admin credentials provided to you by Coder. ![Coder Web UI with code-server](../images/code-server.png) @@ -59,3 +64,7 @@ cd gcp-linux # modify this line as needed to access the template vim main.tf coder templates update gcp-linux # updates the template ``` + +## Up Next + +Learn about [templates](../templates.md). diff --git a/docs/templates.md b/docs/templates.md index 8a6c7af802..614cbd5702 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -98,7 +98,7 @@ inherited by all child processes of the agent, including SSH sessions. #### startup_script Use the Coder agent's `startup_script` to run additional commands like -installing IDEs, [cloning dotfile](./dotfiles.md#templates), and cloning project repos. +installing IDEs, [cloning dotfiles](./dotfiles.md#templates), and cloning project repos. ```hcl resource "coder_agent" "coder" {