opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-24 15:04:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

chore: separate install docs (#3859)

Browse Source
This commit is contained in:
Ben Potter
2022-09-08 14:41:00 -05:00
committed by GitHub
parent d38e645492
commit 3610f09c77
18 changed files with 454 additions and 301 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/install/auth.md
-76
View File
@@ -1,76 +0,0 @@
# Authentication
By default, Coder is accessible via password authentication.
The following steps explain how to set up GitHub OAuth or OpenID Connect.
## GitHub
### Step 1: Configure the OAuth application in GitHub
First, [register a GitHub OAuth app](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/). GitHub will ask you for the following Coder parameters:
- **Homepage URL**: Set to your Coder domain (e.g. `https://coder.domain.com`)
- **User Authorization Callback URL**: Set to `https://coder.domain.com/api/v2/users/oauth2/github/callback`
Note the Client ID and Client Secret generated by GitHub. You will use these
values in the next step.
### Step 2: Configure Coder with the OAuth credentials
Navigate to your Coder host and run the following command to start up the Coder
server:
```console
coder server --oauth2-github-allow-signups=true --oauth2-github-allowed-orgs="your-org" --oauth2-github-client-id="8d1...e05" --oauth2-github-client-secret="57ebc9...02c24c"
```
> For GitHub Enterprise support, specify the `--oauth2-github-enterprise-base-url` flag.
Alternatively, if you are running Coder as a system service, you can achieve the
same result as the command above by adding the following environment variables
to the `/etc/coder.d/coder.env` file:
```console
CODER_OAUTH2_GITHUB_ALLOW_SIGNUPS=true
CODER_OAUTH2_GITHUB_ALLOWED_ORGS="your-org"
CODER_OAUTH2_GITHUB_CLIENT_ID="8d1...e05"
CODER_OAUTH2_GITHUB_CLIENT_SECRET="57ebc9...02c24c"
```
Once complete, run `sudo service coder restart` to reboot Coder.
## OpenID Connect with Google
> We describe how to set up the most popular OIDC provider, Google, but any (Okta, Azure Active Directory, GitLab, Auth0, etc.) may be used.
### Step 1: Configure the OAuth application on Google Cloud
First, [register a Google OAuth app](https://support.google.com/cloud/answer/6158849?hl=en). Google will ask you for the following Coder parameters:
- **Authorized JavaScript origins**: Set to your Coder domain (e.g. `https://coder.domain.com`)
- **Redirect URIs**: Set to `https://coder.domain.com/api/v2/users/oidc/callback`
### Step 2: Configure Coder with the OpenID Connect credentials
Navigate to your Coder host and run the following command to start up the Coder
server:
```console
coder server --oidc-issuer-url="https://accounts.google.com" --oidc-email-domain="your-domain" --oidc-client-id="533...ent.com" --oidc-client-secret="G0CSP...7qSM"
```
Alternatively, if you are running Coder as a system service, you can achieve the
same result as the command above by adding the following environment variables
to the `/etc/coder.d/coder.env` file:
```console
CODER_OIDC_ISSUER_URL="https://accounts.google.com"
CODER_OIDC_EMAIL_DOMAIN="your-domain"
CODER_OIDC_CLIENT_ID="533...ent.com"
CODER_OIDC_CLIENT_SECRET="G0CSP...7qSM"
```
Once complete, run `sudo service coder restart` to reboot Coder.
> When a new user is created, the `preferred_username` claim becomes the username. If this claim is empty, the email address will be stripped of the domain, and become the username (e.g. `example@coder.com` becomes `example`).
docs/install/binary.md
+34
View File
@@ -0,0 +1,34 @@
Coder publishes self-contained .zip and .tar.gz archives in [GitHub releases](https://github.com/coder/coder/releases). The archives bundle `coder` binary.
1. Download the [release archive](https://github.com/coder/coder/releases) appropriate for your operating system
1. Unzip the folder you just downloaded, and move the `coder` executable to a location that's on your `PATH`
```sh
# ex. macOS and Linux
mv coder /usr/local/bin
```
> Windows users: see [this guide](https://answers.microsoft.com/en-us/windows/forum/all/adding-path-variable/97300613-20cb-4d85-8d0e-cc9d3549ba23) for adding folders to `PATH`.
1. Start a Coder server
```sh
# Automatically sets up an external access URL on *.try.coder.app
coder server --tunnel
# Requires a PostgreSQL instance and external access URL
coder server --postgres-url <url> --access-url <url>
```
> Set `CODER_ACCESS_URL` to the external URL that users and workspaces will use to
> connect to Coder. This is not required if you are using the tunnel. Learn more
> about Coder's [configuration options](../admin/configure.md).
1. Visit the Coder URL in the logs to set up your first account, or use the CLI.
## Next steps
- [Quickstart](../quickstart.md)
- [Configuring Coder](../admin/configure.md)
- [Templates](../templates.md)
docs/install/configure.md
-49
View File
@@ -1,49 +0,0 @@
# 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.
CODER_ACCESS_URL=https://coder.example.com
# String. Address to serve the API and dashboard.
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".
CODER_PG_CONNECTION_URL=
# Boolean. Specifies if TLS will be enabled.
CODER_TLS_ENABLE=
# String. 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.
CODER_TLS_CERT_FILE=
# String. Specifies the path to the private key for the certificate. It requires a
# PEM-encoded 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).
docs/install/docker.md
+84
View File
@@ -0,0 +1,84 @@
You can install and run Coder using the official Docker images published on [GitHub Container Registry](https://github.com/coder/coder/pkgs/container/coder).
## Requirements
Docker is required. See the [official installation documentation](https://docs.docker.com/install/).
## Run Coder with built-in database and tunnel (quick)
For proof-of-concept deployments, you can run a complete Coder instance with
with the following command:
```sh
export CODER_DATA=$HOME/.config/coderv2-docker
mkdir -p $CODER_DATA
docker run --rm -it \
-e CODER_TUNNEL=true \
-v $CODER_DATA:/home/coder/.config \
-v /var/run/docker.sock:/var/run/docker.sock \
ghcr.io/coder/coder:latest
```
Coder configuration is defined via environment variables.
Learn more about Coder's [configuration options](../admin/configure.md).
## Run Coder with access URL and external PostgreSQL (recommended)
For production deployments, we recommend using an external PostgreSQL database.
Set `ACCESS_URL` to the external URL that users and workspaces will use to
connect to Coder.
```sh
docker run --rm -it \
-e CODER_ACCESS_URL="https://coder.example.com" \
-e CODER_PG_CONNECTION_URL="postgresql://username:password@database/coder" \
-v /var/run/docker.sock:/var/run/docker.sock \
ghcr.io/coder/coder:latest
```
Coder configuration is defined via environment variables.
Learn more about Coder's [configuration options](../admin/configure.md).
## Run Coder with docker-compose
Coder's publishes a [docker-compose example](../../docker-compose.yaml) which includes
an PostgreSQL container and volume.
1. Install [Docker Compose](https://docs.docker.com/compose/install/)
2. Clone the `coder` repository:
```console
git clone https://github.com/coder/coder.git
```
3. Start Coder with `docker-compose up`:
In order to use cloud-based templates (e.g. Kubernetes, AWS), you must set `CODER_ACCESS_URL` to the external URL that users and workspaces will use to connect to Coder.
```console
cd coder
CODER_ACCESS_URL=https://coder.example.com
docker-compose up
```
> Without `CODER_ACCESS_URL` set, Coder will bind to `localhost:7080`. This will only work for Docker-based templates.
4. Follow the on-screen instructions log in and create your first template and workspace
## Troubleshooting
### Docker-based workspace is stuck in "Connecting..."
Ensure you have an externally-reachable `CODER_ACCESS_URL` set. See [troubleshooting templates](../templates.md#creating-and-troubleshooting-templates) for more steps.
### Permission denied while trying to connect to the Docker daemon socket
See Docker's official documentation to [Manage Docker as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user)
## Next steps
- [Quickstart](../quickstart.md)
- [Configuring Coder](../admin/configure.md)
- [Templates](../templates.md)
docs/install/index.md
+5
View File
@@ -0,0 +1,5 @@
There are a number of different methods to install Coder:
<children>
This page is rendered on https://coder.com/docs/coder-oss/install. Refer to the other documents in the `install/` directory for per-platform instructions.
</children>
docs/install/install.sh.md
+27
View File
@@ -0,0 +1,27 @@
The easiest way to install Coder is to use our [install script](https://github.com/coder/coder/blob/main/install.sh) for Linux and macOS.
To install, run:
```bash
curl -fsSL https://coder.com/install.sh | sh
```
You can preview what occurs during the install process:
```bash
curl -fsSL https://coder.com/install.sh | sh -s -- --dry-run
```
You can modify the installation process by including flags. Run the help command for reference:
```bash
curl -fsSL https://coder.com/install.sh | sh -s -- --help
```
After installing, use the instructions in your terminal to start the Coder server and create your first account.
## Next steps
- [Quickstart](../quickstart.md)
- [Configuring Coder](../admin/configure.md)
- [Templates](../templates.md)
docs/install/kubernetes.md
+161
View File
@@ -0,0 +1,161 @@
## Requirements
Before proceeding, please ensure that you have both Helm 3.5+ and the
[latest version of Coder](https://github.com/coder/coder/releases) installed.
You will also need to have a Kubernetes cluster running K8s 1.19+.
## Install Coder with Helm
> **Warning**: Helm support is new and not yet complete. There may be changes
> to the Helm chart between releases which require manual values updates. Please
> file an issue if you run into any issues.
1. Create a namespace for Coder, such as `coder`:
```console
$ kubectl create namespace coder
```
1. Create a PostgreSQL deployment. Coder does not manage a database server for
you.
- If you're in a public cloud such as
[Google Cloud](https://cloud.google.com/sql/docs/postgres/),
[AWS](https://aws.amazon.com/rds/postgresql/),
[Azure](https://docs.microsoft.com/en-us/azure/postgresql/), or
[DigitalOcean](https://www.digitalocean.com/products/managed-databases-postgresql),
you can use the managed PostgreSQL offerings they provide. Make sure that
the PostgreSQL service is running and accessible from your cluster. It
should be in the same network, same project, etc.
- You can install Postgres manually on your cluster using the
[Bitnami PostgreSQL Helm chart](https://github.com/bitnami/charts/tree/master/bitnami/postgresql#readme). There are some
[helpful guides](https://phoenixnap.com/kb/postgresql-kubernetes) on the
internet that explain sensible configurations for this chart. Example:
```sh
# Install PostgreSQL
helm repo add bitnami https://charts.bitnami.com/bitnami
helm install coder-db bitnami/postgresql \
--namespace coder \
--set auth.username=coder \
--set auth.password=coder \
--set auth.database=coder \
--set persistence.size=10Gi
```
The cluster-internal DB URL for the above database is:
```
postgres://coder:coder@postgres-postgresql.coder.svc.cluster.local:5432/coder?sslmode=disable
```
> Ensure you set up periodic backups so you don't lose data.
- You can use
[Postgres operator](https://github.com/zalando/postgres-operator) to
manage PostgreSQL deployments on your Kubernetes cluster.
1. Download the latest `coder_helm` package from
[GitHub releases](https://github.com/coder/coder/releases).
1. Create a secret with the database URL:
```sh
# Uses Bitnami PostgreSQL example. If you have another database,
# change to the proper URL.
kubectl create secret generic coder-db-url -n coder \
--from-literal=url="postgres://coder:coder@postgres-postgresql.coder.svc.cluster.local:5432/coder?sslmode=disable"
```
1. Create a `values.yaml` with the configuration settings you'd like for your
deployment. For example:
```yaml
coder:
# You can specify any environment variables you'd like to pass to Coder
# here. Coder consumes environment variables listed in
# `coder server --help`, and these environment variables are also passed
# to the workspace provisioner (so you can consume them in your Terraform
# templates for auth keys etc.).
#
# Please keep in mind that you should not set `CODER_ADDRESS`,
# `CODER_TLS_ENABLE`, `CODER_TLS_CERT_FILE` or `CODER_TLS_KEY_FILE` as
# they are already set by the Helm chart and will cause conflicts.
env:
- name: CODER_ACCESS_URL
value: "https://coder.example.com"
- name: CODER_PG_CONNECTION_URL
valueFrom:
secretKeyRef:
# You'll need to create a secret called coder-db-url with your
# Postgres connection URL like:
# postgres://coder:password@postgres:5432/coder?sslmode=disable
name: coder-db-url
key: url
# This env variable controls whether or not to auto-import the
# "kubernetes" template on first startup. This will not work unless
# coder.serviceAccount.workspacePerms is true.
- name: CODER_TEMPLATE_AUTOIMPORT
value: "kubernetes"
#tls:
# secretName: my-tls-secret-name
```
> You can view our
> [Helm README](https://github.com/coder/coder/blob/main/helm#readme) for
> details on the values that are available, or you can view the
> [values.yaml](https://github.com/coder/coder/blob/main/helm/values.yaml)
> file directly.
1. Run the following commands to install the chart in your cluster.
```sh
helm install coder ./coder_helm_x.y.z.tgz \
--namespace coder \
--values values.yaml
```
You can watch Coder start up by running `kubectl get pods`. Once Coder has
started, the `coder-*` pods should enter the `Running` state.
1. Log in to Coder
Use `kubectl get svc -n coder` to get the IP address of the
LoadBalancer. Visit this in the browser to set up your first account.
If you do not have a domain, you should set `CODER_ACCESS_URL`
to this URL in the Helm chart and upgrade Coder (see below).
This allows workspaces to connect to the proper Coder URL.
## Upgrading Coder via Helm
To upgrade Coder in the future or change values,
you can run the following command with a new `coder_helm_x.y.z.tgz` file from GitHub releases:
```console
$ helm upgrade coder ./coder_helm_x.y.z.tgz \
--namespace coder \
-f values.yaml
```
## Troubleshooting
You can view Coder's logs by getting the pod name from `kubectl get pods` and then running `kubectl logs <pod name>`. You can also
view these logs in your
Cloud's log management system if you are using managed Kubernetes.
### Kubernetes-based workspace is stuck in "Connecting..."
Ensure you have an externally-reachable `CODER_ACCESS_URL` set in your helm chart. If you do not have a domain set up,
this should be the IP address of Coder's LoadBalancer (`kubectl get svc -n coder`).
See [troubleshooting templates](../templates.md#creating-and-troubleshooting-templates) for more steps.
## Next steps
- [Quickstart](../quickstart.md)
- [Configuring Coder](../admin/configure.md)
- [Templates](../templates.md)
docs/install/packages.md
+42
View File
@@ -0,0 +1,42 @@
Coder publishes the following system packages [in GitHub releases](https://github.com/coder/coder/releases):
- .deb (Debian, Ubuntu)
- .rpm (Fedora, CentOS, RHEL, SUSE)
- .apk (Alpine)
Once installed, you can run Coder as a system service.
```sh
# Set up an access URL or enable CODER_TUNNEL
sudo vim /etc/coder.d/coder.env
# To systemd to start Coder now and on reboot
sudo systemctl enable --now coder
# View the logs to see Coder's URL and ensure a successful start
journalctl -u coder.service -b
```
> Set `CODER_ACCESS_URL` to the external URL that users and workspaces will use to
> connect to Coder. This is not required if you are using the tunnel. Learn more
> about Coder's [configuration options](../admin/configure.md).
Visit the Coder URL in the logs to set up your first account, or use the CLI:
```sh
coder login <access-url>
```
## Restarting Coder
After updating Coder or applying configuration changes, restart the server:
```sh
sudo systemctl restart coder
```
## Next steps
- [Quickstart](../quickstart.md)
- [Configuring Coder](../admin/configure.md)
- [Templates](../templates.md)
docs/install/upgrade.md
-43
View File
@@ -1,43 +0,0 @@
# Upgrade
This article walks you through how to upgrade your Coder server.
<blockquote class="danger">
<p>
Prior to upgrading a production Coder deployment, take a database snapshot since
Coder does not support rollbacks.
</p>
</blockquote>
To upgrade your Coder server, simply reinstall Coder using your original method
of [install](../install.md).
## Via install.sh
If you installed Coder using the `install.sh` script, 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
```
## Up Next
- [Learn how to configure Coder](./configure.md).