mirror of
https://github.com/coder/coder.git
synced 2026-09-24 15:04:27 +08:00
chore(docs): update docs for correct use of shell and console and enforce linewidth (#9245)
This commit is contained in:
Muhammad Atif Ali
+14
-7
@@ -1,15 +1,22 @@
|
||||
Coder publishes self-contained .zip and .tar.gz archives in [GitHub releases](https://github.com/coder/coder/releases/latest). The archives bundle `coder` binary.
|
||||
Coder publishes self-contained .zip and .tar.gz archives in
|
||||
[GitHub releases](https://github.com/coder/coder/releases/latest). The archives
|
||||
bundle `coder` binary.
|
||||
|
||||
1. Download the [release archive](https://github.com/coder/coder/releases/latest) appropriate for your operating system
|
||||
1. Download the
|
||||
[release archive](https://github.com/coder/coder/releases/latest) 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`
|
||||
1. Unzip the folder you just downloaded, and move the `coder` executable to a
|
||||
location that's on your `PATH`
|
||||
|
||||
```console
|
||||
# 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`.
|
||||
> 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
|
||||
|
||||
@@ -21,9 +28,9 @@ Coder publishes self-contained .zip and .tar.gz archives in [GitHub releases](ht
|
||||
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).
|
||||
> 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.
|
||||
|
||||
|
||||
+19
-11
@@ -1,11 +1,12 @@
|
||||
## Recommendation
|
||||
|
||||
For production deployments, we recommend using an external [PostgreSQL](https://www.postgresql.org/) database (version 13 or higher).
|
||||
For production deployments, we recommend using an external
|
||||
[PostgreSQL](https://www.postgresql.org/) database (version 13 or higher).
|
||||
|
||||
## Basic configuration
|
||||
|
||||
Before starting the Coder server, prepare the database server by creating a role and a database.
|
||||
Remember that the role must have access to the created database.
|
||||
Before starting the Coder server, prepare the database server by creating a role
|
||||
and a database. Remember that the role must have access to the created database.
|
||||
|
||||
With `psql`:
|
||||
|
||||
@@ -19,8 +20,9 @@ With `psql -U coder`:
|
||||
CREATE DATABASE coder;
|
||||
```
|
||||
|
||||
Coder configuration is defined via [environment variables](../admin/configure.md).
|
||||
The database client requires the connection string provided via the `CODER_PG_CONNECTION_URL` variable.
|
||||
Coder configuration is defined via
|
||||
[environment variables](../admin/configure.md). The database client requires the
|
||||
connection string provided via the `CODER_PG_CONNECTION_URL` variable.
|
||||
|
||||
```console
|
||||
export CODER_PG_CONNECTION_URL="postgres://coder:secret42@localhost/coder?sslmode=disable"
|
||||
@@ -28,7 +30,9 @@ export CODER_PG_CONNECTION_URL="postgres://coder:secret42@localhost/coder?sslmod
|
||||
|
||||
## Custom schema
|
||||
|
||||
For installations with elevated security requirements, it's advised to use a separate [schema](https://www.postgresql.org/docs/current/ddl-schemas.html) instead of the public one.
|
||||
For installations with elevated security requirements, it's advised to use a
|
||||
separate [schema](https://www.postgresql.org/docs/current/ddl-schemas.html)
|
||||
instead of the public one.
|
||||
|
||||
With `psql -U coder`:
|
||||
|
||||
@@ -53,8 +57,10 @@ In this case the database client requires the modified connection string:
|
||||
export CODER_PG_CONNECTION_URL="postgres://coder:secret42@localhost/coder?sslmode=disable&search_path=myschema"
|
||||
```
|
||||
|
||||
The `search_path` parameter determines the order of schemas in which they are visited while looking for a specific table.
|
||||
The first schema named in the search path is called the current schema. By default `search_path` defines the following schemas:
|
||||
The `search_path` parameter determines the order of schemas in which they are
|
||||
visited while looking for a specific table. The first schema named in the search
|
||||
path is called the current schema. By default `search_path` defines the
|
||||
following schemas:
|
||||
|
||||
```sql
|
||||
SHOW search_path;
|
||||
@@ -64,7 +70,8 @@ search_path
|
||||
"$user", public
|
||||
```
|
||||
|
||||
Using the `search_path` in the connection string corresponds to the following `psql` command:
|
||||
Using the `search_path` in the connection string corresponds to the following
|
||||
`psql` command:
|
||||
|
||||
```sql
|
||||
ALTER ROLE coder SET search_path = myschema;
|
||||
@@ -74,8 +81,9 @@ ALTER ROLE coder SET search_path = myschema;
|
||||
|
||||
### Coder server fails startup with "current_schema: converting NULL to string is unsupported"
|
||||
|
||||
Please make sure that the schema selected in the connection string `...&search_path=myschema` exists
|
||||
and the role has granted permissions to access it. The schema should be present on this listing:
|
||||
Please make sure that the schema selected in the connection string
|
||||
`...&search_path=myschema` exists and the role has granted permissions to access
|
||||
it. The schema should be present on this listing:
|
||||
|
||||
```console
|
||||
psql -U coder -c '\dn'
|
||||
|
||||
+30
-18
@@ -1,15 +1,18 @@
|
||||
You can install and run Coder using the official Docker images published on [GitHub Container Registry](https://github.com/coder/coder/pkgs/container/coder).
|
||||
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/).
|
||||
Docker is required. See the
|
||||
[official installation documentation](https://docs.docker.com/install/).
|
||||
|
||||
> Note that the below steps are only supported on a Linux distribution. If on macOS, please [run Coder via the standalone binary](./binary.md).
|
||||
> Note that the below steps are only supported on a Linux distribution. If on
|
||||
> macOS, please [run Coder via the standalone binary](./binary.md).
|
||||
|
||||
## Run Coder with the built-in database (quick)
|
||||
|
||||
For proof-of-concept deployments, you can run a complete Coder instance with
|
||||
the following command.
|
||||
For proof-of-concept deployments, you can run a complete Coder instance with the
|
||||
following command.
|
||||
|
||||
```console
|
||||
export CODER_DATA=$HOME/.config/coderv2-docker
|
||||
@@ -27,8 +30,8 @@ ensure Coder has permissions to manage Docker via `docker.sock`. If the host
|
||||
systems `/var/run/docker.sock` is not group writeable or does not belong to the
|
||||
`docker` group, the above may not work as-is.</sup>
|
||||
|
||||
Coder configuration is defined via environment variables.
|
||||
Learn more about Coder's [configuration options](../admin/configure.md).
|
||||
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)
|
||||
|
||||
@@ -44,13 +47,14 @@ docker run --rm -it \
|
||||
ghcr.io/coder/coder:latest
|
||||
```
|
||||
|
||||
Coder configuration is defined via environment variables.
|
||||
Learn more about Coder's [configuration options](../admin/configure.md).
|
||||
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](https://github.com/coder/coder/blob/main/docker-compose.yaml) which includes
|
||||
an PostgreSQL container and volume.
|
||||
Coder's publishes a
|
||||
[docker-compose example](https://github.com/coder/coder/blob/main/docker-compose.yaml)
|
||||
which includes an PostgreSQL container and volume.
|
||||
|
||||
1. Install [Docker Compose](https://docs.docker.com/compose/install/)
|
||||
|
||||
@@ -62,9 +66,11 @@ an PostgreSQL container and volume.
|
||||
|
||||
3. Start Coder with `docker-compose up`:
|
||||
|
||||
In order to use cloud-based templates (e.g. Kubernetes, AWS), you must have an external URL that users and workspaces will use to connect to Coder.
|
||||
In order to use cloud-based templates (e.g. Kubernetes, AWS), you must have
|
||||
an external URL that users and workspaces will use to connect to Coder.
|
||||
|
||||
For proof-of-concept deployments, you can use [Coder's tunnel](../admin/configure.md#tunnel):
|
||||
For proof-of-concept deployments, you can use
|
||||
[Coder's tunnel](../admin/configure.md#tunnel):
|
||||
|
||||
```console
|
||||
cd coder
|
||||
@@ -72,7 +78,8 @@ an PostgreSQL container and volume.
|
||||
docker-compose up
|
||||
```
|
||||
|
||||
For production deployments, we recommend setting an [access URL](../admin/configure.md#access-url):
|
||||
For production deployments, we recommend setting an
|
||||
[access URL](../admin/configure.md#access-url):
|
||||
|
||||
```console
|
||||
cd coder
|
||||
@@ -80,19 +87,24 @@ an PostgreSQL container and volume.
|
||||
CODER_ACCESS_URL=https://coder.example.com docker-compose up
|
||||
```
|
||||
|
||||
4. Visit the web ui via the configured url. You can add `/login` to the base url to create the first user via the ui.
|
||||
4. Visit the web ui via the configured url. You can add `/login` to the base url
|
||||
to create the first user via the ui.
|
||||
|
||||
5. Follow the on-screen instructions log in and create your first template and workspace
|
||||
5. 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/index.md#troubleshooting-templates) for more steps.
|
||||
Ensure you have an externally-reachable `CODER_ACCESS_URL` set. See
|
||||
[troubleshooting templates](../templates/index.md#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)
|
||||
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
|
||||
|
||||
|
||||
@@ -1,4 +1,6 @@
|
||||
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.
|
||||
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:
|
||||
|
||||
@@ -12,15 +14,18 @@ You can preview what occurs during the install process:
|
||||
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:
|
||||
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 in-terminal instructions to start the Coder server manually via `coder server` or as a system package.
|
||||
After installing, use the in-terminal instructions to start the Coder server
|
||||
manually via `coder server` or as a system package.
|
||||
|
||||
By default, the Coder server runs on `http://127.0.0.1:3000` and uses a [public tunnel](../admin/configure.md#tunnel) for workspace connections.
|
||||
By default, the Coder server runs on `http://127.0.0.1:3000` and uses a
|
||||
[public tunnel](../admin/configure.md#tunnel) for workspace connections.
|
||||
|
||||
## Next steps
|
||||
|
||||
|
||||
+47
-34
@@ -1,9 +1,11 @@
|
||||
## Requirements
|
||||
|
||||
Before proceeding, please ensure that you have a Kubernetes cluster running K8s 1.19+ and have Helm 3.5+ installed.
|
||||
Before proceeding, please ensure that you have a Kubernetes cluster running K8s
|
||||
1.19+ and have Helm 3.5+ installed.
|
||||
|
||||
You'll also want to install the [latest version of Coder](https://github.com/coder/coder/releases/latest) locally in order
|
||||
to log in and manage templates.
|
||||
You'll also want to install the
|
||||
[latest version of Coder](https://github.com/coder/coder/releases/latest)
|
||||
locally in order to log in and manage templates.
|
||||
|
||||
## Install Coder with Helm
|
||||
|
||||
@@ -21,12 +23,13 @@ to log in and manage templates.
|
||||
[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 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
|
||||
[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:
|
||||
|
||||
@@ -49,9 +52,8 @@ to log in and manage templates.
|
||||
|
||||
> 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.
|
||||
You can use [Postgres operator](https://github.com/zalando/postgres-operator)
|
||||
to manage PostgreSQL deployments on your Kubernetes cluster.
|
||||
|
||||
1. Create a secret with the database URL:
|
||||
|
||||
@@ -116,22 +118,22 @@ to log in and manage templates.
|
||||
--values values.yaml
|
||||
```
|
||||
|
||||
You can watch Coder start up by running `kubectl get pods -n coder`. Once Coder has
|
||||
started, the `coder-*` pods should enter the `Running` state.
|
||||
You can watch Coder start up by running `kubectl get pods -n coder`. 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.
|
||||
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.
|
||||
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:
|
||||
To upgrade Coder in the future or change values, you can run the following
|
||||
command:
|
||||
|
||||
```console
|
||||
helm repo update
|
||||
@@ -144,7 +146,9 @@ helm upgrade coder coder-v2/coder \
|
||||
|
||||
### AWS
|
||||
|
||||
If you are deploying Coder on AWS EKS and service is set to `LoadBalancer`, AWS will default to the Classic load balancer. The load balancer external IP will be stuck in a pending status unless sessionAffinity is set to None.
|
||||
If you are deploying Coder on AWS EKS and service is set to `LoadBalancer`, AWS
|
||||
will default to the Classic load balancer. The load balancer external IP will be
|
||||
stuck in a pending status unless sessionAffinity is set to None.
|
||||
|
||||
```yaml
|
||||
coder:
|
||||
@@ -153,7 +157,8 @@ coder:
|
||||
sessionAffinity: None
|
||||
```
|
||||
|
||||
AWS recommends a Network load balancer in lieu of the Classic load balancer. Use the following `values.yaml` settings to request a Network load balancer:
|
||||
AWS recommends a Network load balancer in lieu of the Classic load balancer. Use
|
||||
the following `values.yaml` settings to request a Network load balancer:
|
||||
|
||||
```yaml
|
||||
coder:
|
||||
@@ -164,9 +169,9 @@ coder:
|
||||
```
|
||||
|
||||
By default, Coder will set the `externalTrafficPolicy` to `Cluster` which will
|
||||
mask client IP addresses in the Audit log. To preserve the source IP, you can either
|
||||
set this value to `Local`, or pass through the client IP via the X-Forwarded-For
|
||||
header. To configure the latter, set the following environment
|
||||
mask client IP addresses in the Audit log. To preserve the source IP, you can
|
||||
either set this value to `Local`, or pass through the client IP via the
|
||||
X-Forwarded-For header. To configure the latter, set the following environment
|
||||
variables:
|
||||
|
||||
```yaml
|
||||
@@ -180,17 +185,21 @@ coder:
|
||||
|
||||
### Azure
|
||||
|
||||
In certain enterprise environments, the [Azure Application Gateway](https://learn.microsoft.com/en-us/azure/application-gateway/ingress-controller-overview) was needed. The Application Gateway supports:
|
||||
In certain enterprise environments, the
|
||||
[Azure Application Gateway](https://learn.microsoft.com/en-us/azure/application-gateway/ingress-controller-overview)
|
||||
was needed. The Application Gateway supports:
|
||||
|
||||
- Websocket traffic (required for workspace connections)
|
||||
- TLS termination
|
||||
|
||||
## PostgreSQL Certificates
|
||||
|
||||
Your organization may require connecting to the database instance over SSL. To supply
|
||||
Coder with the appropriate certificates, and have it connect over SSL, follow the steps below:
|
||||
Your organization may require connecting to the database instance over SSL. To
|
||||
supply Coder with the appropriate certificates, and have it connect over SSL,
|
||||
follow the steps below:
|
||||
|
||||
1. Create the certificate as a secret in your Kubernetes cluster, if not already present:
|
||||
1. Create the certificate as a secret in your Kubernetes cluster, if not already
|
||||
present:
|
||||
|
||||
```console
|
||||
$ kubectl create secret tls postgres-certs -n coder --key="postgres.key" --cert="postgres.crt"
|
||||
@@ -216,20 +225,24 @@ coder:
|
||||
postgres://<user>:<password>@databasehost:<port>/<db-name>?sslmode=require&sslcert=$HOME/.postgresql/postgres.crt&sslkey=$HOME/.postgresql/postgres.key"
|
||||
```
|
||||
|
||||
> More information on connecting to PostgreSQL databases using certificates can be found [here](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-CLIENTCERT).
|
||||
> More information on connecting to PostgreSQL databases using certificates can
|
||||
> be found
|
||||
> [here](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-CLIENTCERT).
|
||||
|
||||
## 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
|
||||
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`).
|
||||
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/index.md#troubleshooting-templates) for more steps.
|
||||
See [troubleshooting templates](../templates/index.md#troubleshooting-templates)
|
||||
for more steps.
|
||||
|
||||
## Next steps
|
||||
|
||||
|
||||
+46
-18
@@ -1,8 +1,10 @@
|
||||
# Offline Deployments
|
||||
|
||||
All Coder features are supported in offline / behind firewalls / in air-gapped environments. However, some changes to your configuration are necessary.
|
||||
All Coder features are supported in offline / behind firewalls / in air-gapped
|
||||
environments. However, some changes to your configuration are necessary.
|
||||
|
||||
> This is a general comparison. Keep reading for a full tutorial running Coder offline with Kubernetes or Docker.
|
||||
> This is a general comparison. Keep reading for a full tutorial running Coder
|
||||
> offline with Kubernetes or Docker.
|
||||
|
||||
| | Public deployments | Offline deployments |
|
||||
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
@@ -16,16 +18,23 @@ All Coder features are supported in offline / behind firewalls / in air-gapped e
|
||||
|
||||
## Offline container images
|
||||
|
||||
The following instructions walk you through how to build a custom Coder server image for Docker or Kubernetes
|
||||
The following instructions walk you through how to build a custom Coder server
|
||||
image for Docker or Kubernetes
|
||||
|
||||
First, build and push a container image extending our official image with the following:
|
||||
First, build and push a container image extending our official image with the
|
||||
following:
|
||||
|
||||
- CLI config (.tfrc) for Terraform referring to [external mirror](https://www.terraform.io/cli/config/config-file#explicit-installation-method-configuration)
|
||||
- CLI config (.tfrc) for Terraform referring to
|
||||
[external mirror](https://www.terraform.io/cli/config/config-file#explicit-installation-method-configuration)
|
||||
- [Terraform Providers](https://registry.terraform.io) for templates
|
||||
- These could also be specified via a volume mount (Docker) or [network mirror](https://www.terraform.io/internals/provider-network-mirror-protocol). See below for details.
|
||||
- These could also be specified via a volume mount (Docker) or
|
||||
[network mirror](https://www.terraform.io/internals/provider-network-mirror-protocol).
|
||||
See below for details.
|
||||
|
||||
> Note: Coder includes the latest [supported version](https://github.com/coder/coder/blob/main/provisioner/terraform/install.go#L23-L24) of Terraform in the official Docker images.
|
||||
> If you need to bundle a different version of terraform, you can do so by customizing the image.
|
||||
> Note: Coder includes the latest
|
||||
> [supported version](https://github.com/coder/coder/blob/main/provisioner/terraform/install.go#L23-L24)
|
||||
> of Terraform in the official Docker images. If you need to bundle a different
|
||||
> version of terraform, you can do so by customizing the image.
|
||||
|
||||
Here's an example Dockerfile:
|
||||
|
||||
@@ -104,7 +113,9 @@ ENV TF_CLI_CONFIG_FILE=/opt/terraform/config.tfrc
|
||||
```
|
||||
|
||||
> If you are bundling Terraform providers into your Coder image, be sure the
|
||||
> provider version matches any templates or [example templates](https://github.com/coder/coder/tree/main/examples/templates) you intend to use.
|
||||
> provider version matches any templates or
|
||||
> [example templates](https://github.com/coder/coder/tree/main/examples/templates)
|
||||
> you intend to use.
|
||||
|
||||
```hcl
|
||||
# filesystem-mirror-example.tfrc
|
||||
@@ -126,7 +137,10 @@ provider_installation {
|
||||
|
||||
## Run offline via Docker
|
||||
|
||||
Follow our [docker-compose](./docker.md#run-coder-with-docker-compose) documentation and modify the docker-compose file to specify your custom Coder image. Additionally, you can add a volume mount to add providers to the filesystem mirror without re-building the image.
|
||||
Follow our [docker-compose](./docker.md#run-coder-with-docker-compose)
|
||||
documentation and modify the docker-compose file to specify your custom Coder
|
||||
image. Additionally, you can add a volume mount to add providers to the
|
||||
filesystem mirror without re-building the image.
|
||||
|
||||
First, make a create an empty plugins directory:
|
||||
|
||||
@@ -158,11 +172,17 @@ services:
|
||||
# ...
|
||||
```
|
||||
|
||||
> The [terraform providers mirror](https://www.terraform.io/cli/commands/providers/mirror) command can be used to download the required plugins for a Coder template. This can be uploaded into the `plugins` directory on your offline server.
|
||||
> The
|
||||
> [terraform providers mirror](https://www.terraform.io/cli/commands/providers/mirror)
|
||||
> command can be used to download the required plugins for a Coder template.
|
||||
> This can be uploaded into the `plugins` directory on your offline server.
|
||||
|
||||
## Run offline via Kubernetes
|
||||
|
||||
We publish the Helm chart for download on [GitHub Releases](https://github.com/coder/coder/releases/latest). Follow our [Kubernetes](./kubernetes.md) documentation and modify the Helm values to specify your custom Coder image.
|
||||
We publish the Helm chart for download on
|
||||
[GitHub Releases](https://github.com/coder/coder/releases/latest). Follow our
|
||||
[Kubernetes](./kubernetes.md) documentation and modify the Helm values to
|
||||
specify your custom Coder image.
|
||||
|
||||
```yaml
|
||||
# values.yaml
|
||||
@@ -188,12 +208,20 @@ coder:
|
||||
|
||||
## Offline docs
|
||||
|
||||
Coder also provides offline documentation in case you want to host it on your own server. The docs are exported as static files that you can host on any web server, as demonstrated in the example below:
|
||||
Coder also provides offline documentation in case you want to host it on your
|
||||
own server. The docs are exported as static files that you can host on any web
|
||||
server, as demonstrated in the example below:
|
||||
|
||||
1. Go to the release page. In this case, we want to use the [latest version](https://github.com/coder/coder/releases/latest).
|
||||
2. Download the documentation files from the "Assets" section. It is named as `coder_docs_<version>.tgz`.
|
||||
1. Go to the release page. In this case, we want to use the
|
||||
[latest version](https://github.com/coder/coder/releases/latest).
|
||||
2. Download the documentation files from the "Assets" section. It is named as
|
||||
`coder_docs_<version>.tgz`.
|
||||
3. Extract the file and move its contents to your server folder.
|
||||
4. If you are using NodeJS, you can execute the following command: `cd docs && npx http-server .`
|
||||
5. Set the [CODER_DOCS_URL](../cli/server#--docs-url) environment variable to use the URL of your hosted docs. This way, the Coder UI will reference the documentation from your specified URL.
|
||||
4. If you are using NodeJS, you can execute the following command:
|
||||
`cd docs && npx http-server .`
|
||||
5. Set the [CODER_DOCS_URL](../cli/server.md#--docs-url) environment variable to
|
||||
use the URL of your hosted docs. This way, the Coder UI will reference the
|
||||
documentation from your specified URL.
|
||||
|
||||
With these steps, you'll have the Coder documentation hosted on your server and accessible for your team to use.
|
||||
With these steps, you'll have the Coder documentation hosted on your server and
|
||||
accessible for your team to use.
|
||||
|
||||
+53
-48
@@ -2,10 +2,11 @@
|
||||
|
||||
Before proceeding, please ensure that you have an OpenShift cluster running K8s
|
||||
1.19+ (OpenShift 4.7+) and have Helm 3.5+ installed. In addition, you'll need to
|
||||
install the OpenShift CLI (`oc`) to authenticate to your cluster and create OpenShift
|
||||
resources.
|
||||
install the OpenShift CLI (`oc`) to authenticate to your cluster and create
|
||||
OpenShift resources.
|
||||
|
||||
You'll also want to install the [latest version of Coder](https://github.com/coder/coder/releases/latest)
|
||||
You'll also want to install the
|
||||
[latest version of Coder](https://github.com/coder/coder/releases/latest)
|
||||
locally in order to log in and manage templates.
|
||||
|
||||
## Install Coder with OpenShift
|
||||
@@ -26,11 +27,12 @@ oc new-project coder
|
||||
|
||||
### 2. Configure SecurityContext values
|
||||
|
||||
Depending upon your configured Security Context Constraints (SCC), you'll need to modify
|
||||
some or all of the following `securityContext` values from the default values:
|
||||
Depending upon your configured Security Context Constraints (SCC), you'll need
|
||||
to modify some or all of the following `securityContext` values from the default
|
||||
values:
|
||||
|
||||
The below values are modified from Coder defaults and allow the Coder deployment to run
|
||||
under the SCC `restricted-v2`.
|
||||
The below values are modified from Coder defaults and allow the Coder deployment
|
||||
to run under the SCC `restricted-v2`.
|
||||
|
||||
> Note: `readOnlyRootFilesystem: true` is not technically required under
|
||||
> `restricted-v2`, but is often mandated in OpenShift environments.
|
||||
@@ -45,8 +47,8 @@ coder:
|
||||
seccompProfile: RuntimeDefault # Unchanged from default
|
||||
```
|
||||
|
||||
- For `runAsUser` / `runAsGroup`, you can retrieve the correct values for project UID and project GID with the following
|
||||
command:
|
||||
- For `runAsUser` / `runAsGroup`, you can retrieve the correct values for
|
||||
project UID and project GID with the following command:
|
||||
|
||||
```console
|
||||
oc get project coder -o json | jq -r '.metadata.annotations'
|
||||
@@ -56,12 +58,12 @@ coder:
|
||||
}
|
||||
```
|
||||
|
||||
Alternatively, you can set these values to `null` to allow OpenShift to automatically select
|
||||
the correct value for the project.
|
||||
Alternatively, you can set these values to `null` to allow OpenShift to
|
||||
automatically select the correct value for the project.
|
||||
|
||||
- For `readOnlyRootFilesystem`, consult the SCC under which Coder needs to run.
|
||||
In the below example, the `restricted-v2` SCC does not require a read-only root filesystem,
|
||||
while `restricted-custom` does:
|
||||
In the below example, the `restricted-v2` SCC does not require a read-only
|
||||
root filesystem, while `restricted-custom` does:
|
||||
|
||||
```console
|
||||
oc get scc -o wide
|
||||
@@ -70,34 +72,34 @@ coder:
|
||||
restricted-v2 false ["NET_BIND_SERVICE"] MustRunAs MustRunAsRange MustRunAs RunAsAny <no value> false ["configMap","downwardAPI","emptyDir","ephemeral","persistentVolumeClaim","projected","secret"]
|
||||
```
|
||||
|
||||
If you are unsure, we recommend setting `readOnlyRootFilesystem` to `true` in an OpenShift
|
||||
environment.
|
||||
If you are unsure, we recommend setting `readOnlyRootFilesystem` to `true` in
|
||||
an OpenShift environment.
|
||||
|
||||
- For `seccompProfile`: in some environments, you may need to set this to `null` to allow OpenShift
|
||||
to pick its preferred value.
|
||||
- For `seccompProfile`: in some environments, you may need to set this to `null`
|
||||
to allow OpenShift to pick its preferred value.
|
||||
|
||||
### 3. Configure the Coder service, connection URLs, and cache values
|
||||
|
||||
To establish a connection to PostgreSQL, set the `CODER_PG_CONNECTION_URL` value.
|
||||
[See our Helm documentation](./kubernetes.md) on configuring the PostgreSQL connection
|
||||
URL as a secret. Additionally, if accessing Coder over a hostname, set the `CODER_ACCESS_URL`
|
||||
value.
|
||||
To establish a connection to PostgreSQL, set the `CODER_PG_CONNECTION_URL`
|
||||
value. [See our Helm documentation](./kubernetes.md) on configuring the
|
||||
PostgreSQL connection URL as a secret. Additionally, if accessing Coder over a
|
||||
hostname, set the `CODER_ACCESS_URL` value.
|
||||
|
||||
By default, Coder creates the cache directory in `/home/coder/.cache`. Given the
|
||||
OpenShift-provided UID and `readOnlyRootFS` security context constraint, the Coder
|
||||
container does not have permission to write to this directory.
|
||||
OpenShift-provided UID and `readOnlyRootFS` security context constraint, the
|
||||
Coder container does not have permission to write to this directory.
|
||||
|
||||
To fix this, you can mount a temporary volume in the pod and set
|
||||
the `CODER_CACHE_DIRECTORY` environment variable to that location.
|
||||
In the below example, we mount this under `/tmp` and set the cache location to
|
||||
`/tmp/coder`. This enables Coder to run with `readOnlyRootFilesystem: true`.
|
||||
To fix this, you can mount a temporary volume in the pod and set the
|
||||
`CODER_CACHE_DIRECTORY` environment variable to that location. In the below
|
||||
example, we mount this under `/tmp` and set the cache location to `/tmp/coder`.
|
||||
This enables Coder to run with `readOnlyRootFilesystem: true`.
|
||||
|
||||
> Note: Depending on the number of templates and provisioners you use, you may
|
||||
> need to increase the size of the volume, as the `coder` pod will be automatically
|
||||
> restarted when this volume fills up.
|
||||
> need to increase the size of the volume, as the `coder` pod will be
|
||||
> automatically restarted when this volume fills up.
|
||||
|
||||
Additionally, create the Coder service as a `ClusterIP`. In the next step,
|
||||
you will create an OpenShift route that points to the service HTTP target port.
|
||||
Additionally, create the Coder service as a `ClusterIP`. In the next step, you
|
||||
will create an OpenShift route that points to the service HTTP target port.
|
||||
|
||||
```yaml
|
||||
coder:
|
||||
@@ -128,8 +130,8 @@ coder:
|
||||
readOnly: false
|
||||
```
|
||||
|
||||
> Note: OpenShift provides a Developer Catalog offering you can use to
|
||||
> install PostgreSQL into your cluster.
|
||||
> Note: OpenShift provides a Developer Catalog offering you can use to install
|
||||
> PostgreSQL into your cluster.
|
||||
|
||||
### 4. Create the OpenShift route
|
||||
|
||||
@@ -165,8 +167,8 @@ oc apply -f route.yaml
|
||||
|
||||
### 5. Install Coder
|
||||
|
||||
You can now install Coder using the values you've set from the above steps. To do
|
||||
so, run the series of `helm` commands below:
|
||||
You can now install Coder using the values you've set from the above steps. To
|
||||
do so, run the series of `helm` commands below:
|
||||
|
||||
```console
|
||||
helm repo add coder-v2 https://helm.coder.com/v2
|
||||
@@ -176,8 +178,8 @@ helm install coder coder-v2/coder \
|
||||
--values values.yaml
|
||||
```
|
||||
|
||||
> Note: If the Helm installation fails with a Kubernetes RBAC error, check the permissions
|
||||
> of your OpenShift user using the `oc auth can-i` command.
|
||||
> Note: If the Helm installation fails with a Kubernetes RBAC error, check the
|
||||
> permissions of your OpenShift user using the `oc auth can-i` command.
|
||||
>
|
||||
> The below permissions are the minimum required:
|
||||
>
|
||||
@@ -212,9 +214,9 @@ helm install coder coder-v2/coder \
|
||||
|
||||
### 6. Create an OpenShift-compatible image
|
||||
|
||||
While the deployment is spinning up, we will need to create some images that
|
||||
are compatible with OpenShift. These images can then be run without modifying
|
||||
the Security Context Constraints (SCCs) in OpenShift.
|
||||
While the deployment is spinning up, we will need to create some images that are
|
||||
compatible with OpenShift. These images can then be run without modifying the
|
||||
Security Context Constraints (SCCs) in OpenShift.
|
||||
|
||||
1. Determine the UID range for the project:
|
||||
|
||||
@@ -230,15 +232,18 @@ the Security Context Constraints (SCCs) in OpenShift.
|
||||
}
|
||||
```
|
||||
|
||||
Note the `uid-range` and `supplemental-groups`. In this case, the project `coder`
|
||||
has been allocated 10,000 UIDs and GIDs, both starting at `1000680000`.
|
||||
Note the `uid-range` and `supplemental-groups`. In this case, the project
|
||||
`coder` has been allocated 10,000 UIDs and GIDs, both starting at
|
||||
`1000680000`.
|
||||
|
||||
In this example, we will pick both UID and GID `1000680000`.
|
||||
|
||||
1. Create a `BuildConfig` referencing the source image you want to customize.
|
||||
This will automatically kick off a `Build` that will remain pending until step 3.
|
||||
This will automatically kick off a `Build` that will remain pending until
|
||||
step 3.
|
||||
|
||||
> For more information, please consult the [OpenShift Documentation](https://docs.openshift.com/container-platform/4.12/cicd/builds/understanding-buildconfigs.html).
|
||||
> For more information, please consult the
|
||||
> [OpenShift Documentation](https://docs.openshift.com/container-platform/4.12/cicd/builds/understanding-buildconfigs.html).
|
||||
|
||||
```console
|
||||
oc create -f - <<EOF
|
||||
@@ -289,8 +294,8 @@ the Security Context Constraints (SCCs) in OpenShift.
|
||||
oc create imagestream enterprise-base
|
||||
```
|
||||
|
||||
The `Build` created in the previous step should now begin.
|
||||
Once completed, you should see output similar to the following:
|
||||
The `Build` created in the previous step should now begin. Once completed,
|
||||
you should see output similar to the following:
|
||||
|
||||
```console
|
||||
oc get imagestreamtag
|
||||
@@ -310,8 +315,8 @@ cd ./openshift-k8s
|
||||
Edit `main.tf` and update the following fields of the Kubernetes pod resource:
|
||||
|
||||
- `spec.security_context`: remove this field.
|
||||
- `spec.container.image`: update this field to the newly built image hosted
|
||||
on the OpenShift image registry from the previous step.
|
||||
- `spec.container.image`: update this field to the newly built image hosted on
|
||||
the OpenShift image registry from the previous step.
|
||||
- `spec.container.security_context`: remove this field.
|
||||
|
||||
Finally, create the template:
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
1. Download and install one of the following system packages from [GitHub releases](https://github.com/coder/coder/releases/latest):
|
||||
1. Download and install one of the following system packages from
|
||||
[GitHub releases](https://github.com/coder/coder/releases/latest):
|
||||
|
||||
- .deb (Debian, Ubuntu)
|
||||
- .rpm (Fedora, CentOS, RHEL, SUSE)
|
||||
@@ -17,9 +18,9 @@
|
||||
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).
|
||||
> 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:
|
||||
|
||||
|
||||
@@ -30,7 +30,8 @@ Alpine:
|
||||
sudo apk del coder
|
||||
```
|
||||
|
||||
If you installed Coder manually or used the install script on an unsupported operating system, you can remove the binary directly:
|
||||
If you installed Coder manually or used the install script on an unsupported
|
||||
operating system, you can remove the binary directly:
|
||||
|
||||
```console
|
||||
sudo rm /usr/local/bin/coder
|
||||
@@ -45,9 +46,8 @@ sudo rm /etc/coder.d/coder.env
|
||||
## Coder settings and the optional built-in PostgreSQL database
|
||||
|
||||
> There is a `postgres` directory within the `coderv2` directory that has the
|
||||
> database engine and database. If you want to reuse the database, consider
|
||||
> not performing the following step or copying the directory to another
|
||||
> location.
|
||||
> database engine and database. If you want to reuse the database, consider not
|
||||
> performing the following step or copying the directory to another location.
|
||||
|
||||
### macOS
|
||||
|
||||
|
||||
@@ -1,8 +1,12 @@
|
||||
# Windows
|
||||
|
||||
Use the Windows installer to download the CLI and add Coder to `PATH`. Alternatively, you can install Coder on Windows via a [standalone binary](./binary.md).
|
||||
Use the Windows installer to download the CLI and add Coder to `PATH`.
|
||||
Alternatively, you can install Coder on Windows via a
|
||||
[standalone binary](./binary.md).
|
||||
|
||||
1. Download the Windows installer from [GitHub releases](https://github.com/coder/coder/releases/latest) or from `winget`
|
||||
1. Download the Windows installer from
|
||||
[GitHub releases](https://github.com/coder/coder/releases/latest) or from
|
||||
`winget`
|
||||
|
||||
```powershell
|
||||
winget install Coder.Coder
|
||||
@@ -22,9 +26,9 @@ Use the Windows installer to download the CLI and add Coder to `PATH`. Alternati
|
||||
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).
|
||||
> 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).
|
||||
|
||||
4. Visit the Coder URL in the logs to set up your first account, or use the CLI.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user