mirror of
https://github.com/coder/coder.git
synced 2026-09-24 15:04:27 +08:00
chore: separate install docs (#3859)
This commit is contained in:
Ben Potter
@@ -0,0 +1,76 @@
|
||||
# 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`).
|
||||
@@ -0,0 +1,71 @@
|
||||
Coder server's primary configuration is done via environment variables. For a full list
|
||||
of the options, run `coder server --help` on the host.
|
||||
|
||||
## Tunnel
|
||||
|
||||
For proof-of-concept deployments, you can set `CODER_TUNNEL=true` to run Coder on a unique `*.try.coder.app` URL.
|
||||
This is a quick way to allow users and workspaces outside your LAN to connect to Coder.
|
||||
|
||||
## Access URL
|
||||
|
||||
`CODER_ACCESS_URL` is required if you are not using the tunnel. Set this to the external URL
|
||||
that users and workspaces use to connect to Coder (e.g. https://coder.example.com). This
|
||||
should not be localhost.
|
||||
|
||||
## PostgreSQL Database
|
||||
|
||||
Coder uses a PostgreSQL database to store users, workspace metadata, and other deployment information.
|
||||
Use `CODER_PG_CONNECTION_URL` to set the database that Coder connects to. If unset, PostgreSQL binaries will be
|
||||
downloaded from Maven (https://repo1.maven.org/maven2) and store all data in the config root.
|
||||
|
||||
## System packages
|
||||
|
||||
If you've installed Coder via a [system package](../install/packages.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=
|
||||
```
|
||||
|
||||
To 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
|
||||
```
|
||||
|
||||
To restart Coder after applying system changes:
|
||||
|
||||
```sh
|
||||
sudo systemctl restart Coder
|
||||
```
|
||||
|
||||
## Up Next
|
||||
|
||||
- [Get started using Coder](../quickstart.md).
|
||||
- [Learn how to upgrade Coder](./upgrade.md).
|
||||
@@ -0,0 +1,5 @@
|
||||
Get started with Coder administration:
|
||||
|
||||
<children>
|
||||
This page is rendered on https://coder.com/docs/coder-oss/admin. Refer to the other documents in the `admin/` directory.
|
||||
</children>
|
||||
@@ -0,0 +1,43 @@
|
||||
# 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).
|
||||
|
||||
## 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).
|
||||
@@ -0,0 +1,112 @@
|
||||
# Users
|
||||
|
||||
This article walks you through the user roles available in Coder and creating and managing users.
|
||||
|
||||
## Roles
|
||||
|
||||
Coder offers these user roles in the community edition:
|
||||
|
||||
| | User Admin | Template Admin | Owner |
|
||||
| ------------------------------------------ | ---------- | -------------- |-------|
|
||||
| Add and remove Users | ✅ | | ✅ |
|
||||
| Change User roles | | | ✅ |
|
||||
| Manage Templates | | ✅ | ✅ |
|
||||
| View, update and delete **ALL** Workspaces | | ✅ | ✅ |
|
||||
| Execute and use **ALL** Workspaces | | | ✅ |
|
||||
|
||||
A user may have one or more roles. All users have an implicit Member role
|
||||
that may use personal workspaces.
|
||||
|
||||
## Create a user
|
||||
|
||||
To create a user with the web UI:
|
||||
|
||||
1. Log in as a user admin.
|
||||
2. Go to **Users** > **New user**.
|
||||
3. In the window that opens, provide the **username**, **email**, and
|
||||
**password** for the user (they can opt to change their password after their
|
||||
initial login).
|
||||
4. Click **Submit** to create the user.
|
||||
|
||||
The new user will appear in the **Users** list. Use the toggle to change their
|
||||
**Roles** if desired.
|
||||
|
||||
To create a user via the Coder CLI, run:
|
||||
|
||||
```console
|
||||
coder users create
|
||||
```
|
||||
|
||||
When prompted, provide the **username** and **email** for the new user.
|
||||
|
||||
You'll receive a response that includes the following; share the instructions
|
||||
with the user so that they can log into Coder:
|
||||
|
||||
```console
|
||||
Download the Coder command line for your operating system:
|
||||
https://github.com/coder/coder/releases
|
||||
|
||||
Run coder login https://<accessURL>.coder.app to authenticate.
|
||||
|
||||
Your email is: email@exampleCo.com
|
||||
Your password is: <redacted>
|
||||
|
||||
Create a workspace coder create !
|
||||
```
|
||||
|
||||
## Suspend a user
|
||||
|
||||
User admins can suspend a user, removing the user's access to Coder.
|
||||
|
||||
To suspend a user via the web UI:
|
||||
|
||||
1. Go to **Users**.
|
||||
2. Find the user you want to suspend, click the vertical ellipsis to the right,
|
||||
and click **Suspend**.
|
||||
3. In the confirmation dialog, click **Suspend**.
|
||||
|
||||
To suspend a user via the CLI, run:
|
||||
|
||||
```console
|
||||
coder users suspend <username|user_id>
|
||||
```
|
||||
|
||||
Confirm the user suspension by typing **yes** and pressing **enter**.
|
||||
|
||||
## Activate a suspended user
|
||||
|
||||
User admins can activate a suspended user, restoring their access to Coder.
|
||||
|
||||
To activate a user via the web UI:
|
||||
|
||||
1. Go to **Users**.
|
||||
2. Find the user you want to activate, click the vertical ellipsis to the right,
|
||||
and click **Activate**.
|
||||
3. In the confirmation dialog, click **Activate**.
|
||||
|
||||
To activate a user via the CLI, run:
|
||||
|
||||
```console
|
||||
coder users activate <username|user_id>
|
||||
```
|
||||
|
||||
Confirm the user activation by typing **yes** and pressing **enter**.
|
||||
|
||||
## Reset a password
|
||||
|
||||
To reset a user's via the web UI:
|
||||
|
||||
1. Go to **Users**.
|
||||
2. Find the user whose password you want to reset, click the vertical ellipsis to the right,
|
||||
and select **Reset password**.
|
||||
3. Coder displays a temporary password that you can send to the user; copy the
|
||||
password and click **Reset password**.
|
||||
|
||||
Coder will prompt the user to change their temporary password immediately after logging in.
|
||||
|
||||
You can also reset a password via the CLI:
|
||||
|
||||
```console
|
||||
# run `coder reset-password <username> --help` for usage instructions
|
||||
coder reset-password <username>
|
||||
```
|
||||
Reference in New Issue
Block a user