mirror of
https://github.com/coder/coder.git
synced 2026-09-21 20:51:01 +08:00
docs: restructure docs (#14421)
Closes #13434 Supersedes #14182 --------- Co-authored-by: Ethan <39577870+ethanndickson@users.noreply.github.com> Co-authored-by: Ethan Dickson <ethan@coder.com> Co-authored-by: Ben Potter <ben@coder.com> Co-authored-by: Stephen Kirby <58410745+stirby@users.noreply.github.com> Co-authored-by: Stephen Kirby <me@skirby.dev> Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com> Co-authored-by: Edward Angert <EdwardAngert@users.noreply.github.com>
This commit is contained in:
Muhammad Atif Ali
co-authored by
Ethan
Ethan Dickson
Ben Potter
Stephen Kirby
Stephen Kirby
EdwardAngert
Edward Angert
Ethan
Ethan Dickson
Ben Potter
Stephen Kirby
Stephen Kirby
EdwardAngert
Edward Angert
parent
288df75686
commit
419eba5fb6
@@ -0,0 +1,95 @@
|
||||
# Appearance (enterprise) (premium)
|
||||
|
||||
Customize the look of your Coder deployment to meet your enterprise
|
||||
requirements.
|
||||
|
||||
You can access the Appearance settings by navigating to
|
||||
`Deployment > Appearance`.
|
||||
|
||||
|
||||
|
||||
## Application Name
|
||||
|
||||
Specify a custom application name to be displayed on the login page. The default
|
||||
is Coder.
|
||||
|
||||
## Logo URL
|
||||
|
||||
Specify a custom URL for your enterprise's logo to be displayed on the sign in
|
||||
page and in the top left corner of the dashboard. The default is the Coder logo.
|
||||
|
||||
## Announcement Banners
|
||||
|
||||
|
||||
|
||||
Announcement Banners let admins post important messages to all site users. Only
|
||||
Site Owners may set the announcement banners.
|
||||
|
||||
Example: Use multiple announcement banners for concurrent deployment-wide
|
||||
updates, such as maintenance or new feature rollout.
|
||||
|
||||
|
||||
|
||||
Example: Adhere to government network classification requirements and notify
|
||||
users of which network their Coder deployment is on.
|
||||
|
||||
|
||||
|
||||
## OIDC Login Button Customization
|
||||
|
||||
[Use environment variables to customize](../users/oidc-auth.md#oidc-login-customization)
|
||||
the text and icon on the OIDC button on the Sign In page.
|
||||
|
||||
## Support Links
|
||||
|
||||
Support links let admins adjust the user dropdown menu to include links
|
||||
referring to internal company resources. The menu section replaces the original
|
||||
menu positions: documentation, report a bug to GitHub, or join the Discord
|
||||
server.
|
||||
|
||||
|
||||
|
||||
### Icons
|
||||
|
||||
The link icons are optional, and can be set to any url or
|
||||
[builtin icon](../templates/extending-templates/icons.md#bundled-icons),
|
||||
additionally `bug`, `chat`, and `docs` are available as three special icons.
|
||||
|
||||
### Configuration
|
||||
|
||||
#### Kubernetes
|
||||
|
||||
To configure support links in your Coder Kubernetes deployment, update your Helm
|
||||
chart values as follows:
|
||||
|
||||
```yaml
|
||||
coder:
|
||||
env:
|
||||
- name: CODER_SUPPORT_LINKS
|
||||
value: >
|
||||
[{"name": "Hello GitHub", "target": "https://github.com/coder/coder",
|
||||
"icon": "bug"},
|
||||
{"name": "Hello Slack", "target":
|
||||
"https://codercom.slack.com/archives/C014JH42DBJ", "icon":
|
||||
"/icon/slack.svg"},
|
||||
{"name": "Hello Discord", "target": "https://discord.gg/coder", "icon":
|
||||
"/icon/discord.svg"},
|
||||
{"name": "Hello Foobar", "target": "https://foo.com/bar", "icon":
|
||||
"/emojis/1f3e1.png"}]
|
||||
```
|
||||
|
||||
#### System package
|
||||
|
||||
if running as a system service, set an environment variable
|
||||
`CODER_SUPPORT_LINKS` in `/etc/coder.d/coder.env` as follows,
|
||||
|
||||
```env
|
||||
CODER_SUPPORT_LINKS='[{"name": "Hello GitHub", "target": "https://github.com/coder/coder", "icon": "bug"}, {"name": "Hello Slack", "target": "https://codercom.slack.com/archives/C014JH42DBJ", "icon": "https://raw.githubusercontent.com/coder/coder/main/site/static/icon/slack.svg"}, {"name": "Hello Discord", "target": "https://discord.gg/coder", "icon": "https://raw.githubusercontent.com/coder/coder/main/site/static/icon/discord.svg"}, {"name": "Hello Foobar", "target": "https://discord.gg/coder", "icon": "/emojis/1f3e1.png"}]'
|
||||
```
|
||||
|
||||
For CLI, use,
|
||||
|
||||
```shell
|
||||
export CODER_SUPPORT_LINKS='[{"name": "Hello GitHub", "target": "https://github.com/coder/coder", "icon": "bug"}, {"name": "Hello Slack", "target": "https://codercom.slack.com/archives/C014JH42DBJ", "icon": "https://raw.githubusercontent.com/coder/coder/main/site/static/icon/slack.svg"}, {"name": "Hello Discord", "target": "https://discord.gg/coder", "icon": "https://raw.githubusercontent.com/coder/coder/main/site/static/icon/discord.svg"}, {"name": "Hello Foobar", "target": "https://discord.gg/coder", "icon": "/emojis/1f3e1.png"}]'
|
||||
coder-server
|
||||
```
|
||||
@@ -0,0 +1,153 @@
|
||||
# Configure Control Plane Access
|
||||
|
||||
Coder server's primary configuration is done via environment variables. For a
|
||||
full list of the options, run `coder server --help` or see our
|
||||
[CLI documentation](../../reference/cli/server.md).
|
||||
|
||||
## 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.
|
||||
|
||||
> Access URL should be an external IP address or domain with DNS records
|
||||
> pointing to Coder.
|
||||
|
||||
### Tunnel
|
||||
|
||||
If an access URL is not specified, Coder will create a publicly accessible URL
|
||||
to reverse proxy your deployment for simple setup.
|
||||
|
||||
## Address
|
||||
|
||||
You can change which port(s) Coder listens on.
|
||||
|
||||
```shell
|
||||
# Listen on port 80
|
||||
export CODER_HTTP_ADDRESS=0.0.0.0:80
|
||||
|
||||
# Enable TLS and listen on port 443)
|
||||
export CODER_TLS_ENABLE=true
|
||||
export CODER_TLS_ADDRESS=0.0.0.0:443
|
||||
|
||||
## Redirect from HTTP to HTTPS
|
||||
export CODER_REDIRECT_TO_ACCESS_URL=true
|
||||
|
||||
# Start the Coder server
|
||||
coder server
|
||||
```
|
||||
|
||||
## Wildcard access URL
|
||||
|
||||
`CODER_WILDCARD_ACCESS_URL` is necessary for
|
||||
[port forwarding](../networking/port-forwarding.md#dashboard) via the dashboard
|
||||
or running [coder_apps](../templates/index.md) on an absolute path. Set this to
|
||||
a wildcard subdomain that resolves to Coder (e.g. `*.coder.example.com`).
|
||||
|
||||
If you are providing TLS certificates directly to the Coder server, either
|
||||
|
||||
1. Use a single certificate and key for both the root and wildcard domains.
|
||||
2. Configure multiple certificates and keys via
|
||||
[`coder.tls.secretNames`](https://github.com/coder/coder/blob/main/helm/coder/values.yaml)
|
||||
in the Helm Chart, or
|
||||
[`--tls-cert-file`](../../reference/cli/server.md#--tls-cert-file) and
|
||||
[`--tls-key-file`](../../reference/cli/server.md#--tls-key-file) command line
|
||||
options (these both take a comma separated list of files; list certificates
|
||||
and their respective keys in the same order).
|
||||
|
||||
## TLS & Reverse Proxy
|
||||
|
||||
The Coder server can directly use TLS certificates with `CODER_TLS_ENABLE` and
|
||||
accompanying configuration flags. However, Coder can also run behind a
|
||||
reverse-proxy to terminate TLS certificates from LetsEncrypt, for example.
|
||||
|
||||
- [Apache](./web-server/apache/index.md)
|
||||
- [Caddy](./web-server/caddy/index.md)
|
||||
- [NGINX](./web-server/nginx/index.md)
|
||||
|
||||
### Kubernetes TLS configuration
|
||||
|
||||
Below are the steps to configure Coder to terminate TLS when running on
|
||||
Kubernetes. You must have the certificate `.key` and `.crt` files in your
|
||||
working directory prior to step 1.
|
||||
|
||||
1. Create the TLS secret in your Kubernetes cluster
|
||||
|
||||
```shell
|
||||
kubectl create secret tls coder-tls -n <coder-namespace> --key="tls.key" --cert="tls.crt"
|
||||
```
|
||||
|
||||
> You can use a single certificate for the both the access URL and wildcard
|
||||
> access URL. The certificate CN must match the wildcard domain, such as
|
||||
> `*.example.coder.com`.
|
||||
|
||||
1. Reference the TLS secret in your Coder Helm chart values
|
||||
|
||||
```yaml
|
||||
coder:
|
||||
tls:
|
||||
secretName:
|
||||
- coder-tls
|
||||
|
||||
# Alternatively, if you use an Ingress controller to terminate TLS,
|
||||
# set the following values:
|
||||
ingress:
|
||||
enable: true
|
||||
secretName: coder-tls
|
||||
wildcardSecretName: coder-tls
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
> Postgres 13 is the minimum supported version.
|
||||
|
||||
If you are using the built-in PostgreSQL deployment and need to use `psql` (aka
|
||||
the PostgreSQL interactive terminal), output the connection URL with the
|
||||
following command:
|
||||
|
||||
```console
|
||||
coder server postgres-builtin-url
|
||||
psql "postgres://coder@localhost:49627/coder?sslmode=disable&password=feU...yI1"
|
||||
```
|
||||
|
||||
### Migrating from the built-in database to an external database
|
||||
|
||||
To migrate from the built-in database to an external database, follow these
|
||||
steps:
|
||||
|
||||
1. Stop your Coder deployment.
|
||||
2. Run `coder server postgres-builtin-serve` in a background terminal.
|
||||
3. Run `coder server postgres-builtin-url` and copy its output command.
|
||||
4. Run `pg_dump <built-in-connection-string> > coder.sql` to dump the internal
|
||||
database to a file.
|
||||
5. Restore that content to an external database with
|
||||
`psql <external-connection-string> < coder.sql`.
|
||||
6. Start your Coder deployment with
|
||||
`CODER_PG_CONNECTION_URL=<external-connection-string>`.
|
||||
|
||||
## Configuring Coder behind a proxy
|
||||
|
||||
To configure Coder behind a corporate proxy, set the environment variables
|
||||
`HTTP_PROXY` and `HTTPS_PROXY`. Be sure to restart the server. Lowercase values
|
||||
(e.g. `http_proxy`) are also respected in this case.
|
||||
|
||||
## External Authentication
|
||||
|
||||
Coder supports external authentication via OAuth2.0. This allows enabling
|
||||
integrations with git providers, such as GitHub, GitLab, and Bitbucket etc.
|
||||
|
||||
External authentication can also be used to integrate with external services
|
||||
like JFrog Artifactory and others.
|
||||
|
||||
Please refer to the [external authentication](../external-auth.md) section for
|
||||
more information.
|
||||
|
||||
## Up Next
|
||||
|
||||
- [Learn how to setup and manage templates](../templates/index.md)
|
||||
- [Setup external provisioners](../provisioners.md)
|
||||
@@ -0,0 +1,44 @@
|
||||
# Telemetry
|
||||
|
||||
<blockquote class="info">
|
||||
TL;DR: disable telemetry by setting <code>CODER_TELEMETRY=false</code>.
|
||||
</blockquote>
|
||||
|
||||
Coder collects telemetry from all installations by default. We believe our users
|
||||
should have the right to know what we collect, why we collect it, and how we use
|
||||
the data.
|
||||
|
||||
## What we collect
|
||||
|
||||
You can find a full list of the data we collect in our source code
|
||||
[here](https://github.com/coder/coder/blob/main/coderd/telemetry/telemetry.go).
|
||||
In particular, look at the struct types such as `Template` or `Workspace`.
|
||||
|
||||
As a rule, we **do not collect** the following types of information:
|
||||
|
||||
- Any data that could make your installation less secure
|
||||
- Any data that could identify individual users
|
||||
|
||||
For example, we do not collect parameters, environment variables, or user email
|
||||
addresses.
|
||||
|
||||
## Why we collect
|
||||
|
||||
Telemetry helps us understand which features are most valuable, what use cases
|
||||
to focus on, and which bugs to fix first.
|
||||
|
||||
Most cloud-based software products collect far more data than we do. They often
|
||||
offer little transparency and configurability. It's hard to imagine our favorite
|
||||
SaaS products existing without their creators having a detailed understanding of
|
||||
user interactions. We want to wield some of that product development power to
|
||||
build self-hosted, open-source software.
|
||||
|
||||
## Security
|
||||
|
||||
In the event we discover a critical security issue with Coder, we will use
|
||||
telemetry to identify affected installations and notify their administrators.
|
||||
|
||||
## Toggling
|
||||
|
||||
You can turn telemetry on or off using either the `CODER_TELEMETRY=[true|false]`
|
||||
environment variable or the `--telemetry=[true|false]` command-line flag.
|
||||
@@ -0,0 +1,28 @@
|
||||
# Redirect HTTP to HTTPS
|
||||
<VirtualHost *:80>
|
||||
ServerName coder.example.com
|
||||
ServerAlias *.coder.example.com
|
||||
Redirect permanent / https://coder.example.com/
|
||||
</VirtualHost>
|
||||
|
||||
<VirtualHost *:443>
|
||||
ServerName coder.example.com
|
||||
ServerAlias *.coder.example.com
|
||||
ErrorLog ${APACHE_LOG_DIR}/error.log
|
||||
CustomLog ${APACHE_LOG_DIR}/access.log combined
|
||||
|
||||
ProxyPass / http://127.0.0.1:3000/ upgrade=any # required for websockets
|
||||
ProxyPassReverse / http://127.0.0.1:3000/
|
||||
ProxyRequests Off
|
||||
ProxyPreserveHost On
|
||||
|
||||
RewriteEngine On
|
||||
# Websockets are required for workspace connectivity
|
||||
RewriteCond %{HTTP:Connection} Upgrade [NC]
|
||||
RewriteCond %{HTTP:Upgrade} websocket [NC]
|
||||
RewriteRule /(.*) ws://127.0.0.1:3000/$1 [P,L]
|
||||
|
||||
SSLCertificateFile /etc/letsencrypt/live/coder.example.com/fullchain.pem
|
||||
SSLCertificateKeyFile /etc/letsencrypt/live/coder.example.com/privkey.pem
|
||||
</VirtualHost>
|
||||
|
||||
@@ -0,0 +1,172 @@
|
||||
# How to use Apache as a reverse-proxy with LetsEncrypt
|
||||
|
||||
## Requirements
|
||||
|
||||
1. Start a Coder deployment and be sure to set the following
|
||||
[configuration values](../../index.md):
|
||||
|
||||
```env
|
||||
CODER_HTTP_ADDRESS=127.0.0.1:3000
|
||||
CODER_ACCESS_URL=https://coder.example.com
|
||||
CODER_WILDCARD_ACCESS_URL=*coder.example.com
|
||||
```
|
||||
|
||||
Throughout the guide, be sure to replace `coder.example.com` with the domain
|
||||
you intend to use with Coder.
|
||||
|
||||
2. Configure your DNS provider to point your coder.example.com and
|
||||
\*.coder.example.com to your server's public IP address.
|
||||
|
||||
> For example, to use `coder.example.com` as your subdomain, configure
|
||||
> `coder.example.com` and `*.coder.example.com` to point to your server's
|
||||
> public ip. This can be done by adding A records in your DNS provider's
|
||||
> dashboard.
|
||||
|
||||
3. Install Apache (assuming you're on Debian/Ubuntu):
|
||||
|
||||
```shell
|
||||
sudo apt install apache2
|
||||
```
|
||||
|
||||
4. Enable the following Apache modules:
|
||||
|
||||
```shell
|
||||
sudo a2enmod proxy
|
||||
sudo a2enmod proxy_http
|
||||
sudo a2enmod ssl
|
||||
sudo a2enmod rewrite
|
||||
```
|
||||
|
||||
5. Stop Apache service and disable default site:
|
||||
|
||||
```shell
|
||||
sudo a2dissite 000-default.conf
|
||||
sudo systemctl stop apache2
|
||||
```
|
||||
|
||||
## Install and configure LetsEncrypt Certbot
|
||||
|
||||
1. Install LetsEncrypt Certbot: Refer to the
|
||||
[CertBot documentation](https://certbot.eff.org/instructions?ws=apache&os=ubuntufocal&tab=wildcard).
|
||||
Be sure to pick the wildcard tab and select your DNS provider for
|
||||
instructions to install the necessary DNS plugin.
|
||||
|
||||
## Create DNS provider credentials
|
||||
|
||||
> This example assumes you're using CloudFlare as your DNS provider. For other
|
||||
> providers, refer to the
|
||||
> [CertBot documentation](https://eff-certbot.readthedocs.io/en/stable/using.html#dns-plugins).
|
||||
|
||||
1. Create an API token for the DNS provider you're using: e.g.
|
||||
[CloudFlare](https://developers.cloudflare.com/fundamentals/api/get-started/create-token)
|
||||
with the following permissions:
|
||||
|
||||
- Zone - DNS - Edit
|
||||
|
||||
2. Create a file in `.secrets/certbot/cloudflare.ini` with the following
|
||||
content:
|
||||
|
||||
```ini
|
||||
dns_cloudflare_api_token = YOUR_API_TOKEN
|
||||
```
|
||||
|
||||
```shell
|
||||
mkdir -p ~/.secrets/certbot
|
||||
touch ~/.secrets/certbot/cloudflare.ini
|
||||
nano ~/.secrets/certbot/cloudflare.ini
|
||||
```
|
||||
|
||||
3. Set the correct permissions:
|
||||
|
||||
```shell
|
||||
sudo chmod 600 ~/.secrets/certbot/cloudflare.ini
|
||||
```
|
||||
|
||||
## Create the certificate
|
||||
|
||||
1. Create the wildcard certificate:
|
||||
|
||||
```shell
|
||||
sudo certbot certonly --dns-cloudflare --dns-cloudflare-credentials ~/.secrets/certbot/cloudflare.ini -d coder.example.com -d *.coder.example.com
|
||||
```
|
||||
|
||||
## Configure Apache
|
||||
|
||||
> This example assumes Coder is running locally on `127.0.0.1:3000` and that
|
||||
> you're using `coder.example.com` as your subdomain.
|
||||
|
||||
1. Create Apache configuration for Coder:
|
||||
|
||||
```shell
|
||||
sudo nano /etc/apache2/sites-available/coder.conf
|
||||
```
|
||||
|
||||
2. Add the following content:
|
||||
|
||||
```apache
|
||||
# Redirect HTTP to HTTPS
|
||||
<VirtualHost *:80>
|
||||
ServerName coder.example.com
|
||||
ServerAlias *.coder.example.com
|
||||
Redirect permanent / https://coder.example.com/
|
||||
</VirtualHost>
|
||||
|
||||
<VirtualHost *:443>
|
||||
ServerName coder.example.com
|
||||
ServerAlias *.coder.example.com
|
||||
ErrorLog ${APACHE_LOG_DIR}/error.log
|
||||
CustomLog ${APACHE_LOG_DIR}/access.log combined
|
||||
|
||||
ProxyPass / http://127.0.0.1:3000/ upgrade=any # required for websockets
|
||||
ProxyPassReverse / http://127.0.0.1:3000/
|
||||
ProxyRequests Off
|
||||
ProxyPreserveHost On
|
||||
|
||||
RewriteEngine On
|
||||
# Websockets are required for workspace connectivity
|
||||
RewriteCond %{HTTP:Connection} Upgrade [NC]
|
||||
RewriteCond %{HTTP:Upgrade} websocket [NC]
|
||||
RewriteRule /(.*) ws://127.0.0.1:3000/$1 [P,L]
|
||||
|
||||
SSLCertificateFile /etc/letsencrypt/live/coder.example.com/fullchain.pem
|
||||
SSLCertificateKeyFile /etc/letsencrypt/live/coder.example.com/privkey.pem
|
||||
</VirtualHost>
|
||||
```
|
||||
|
||||
> Don't forget to change: `coder.example.com` by your (sub)domain
|
||||
|
||||
3. Enable the site:
|
||||
|
||||
```shell
|
||||
sudo a2ensite coder.conf
|
||||
```
|
||||
|
||||
4. Restart Apache:
|
||||
|
||||
```shell
|
||||
sudo systemctl restart apache2
|
||||
```
|
||||
|
||||
## Refresh certificates automatically
|
||||
|
||||
1. Create a new file in `/etc/cron.weekly`:
|
||||
|
||||
```shell
|
||||
sudo touch /etc/cron.weekly/certbot
|
||||
```
|
||||
|
||||
2. Make it executable:
|
||||
|
||||
```shell
|
||||
sudo chmod +x /etc/cron.weekly/certbot
|
||||
```
|
||||
|
||||
3. And add this code:
|
||||
|
||||
```shell
|
||||
#!/bin/sh
|
||||
sudo certbot renew -q
|
||||
```
|
||||
|
||||
And that's it, you should now be able to access Coder at your sub(domain) e.g.
|
||||
`https://coder.example.com`.
|
||||
@@ -0,0 +1,15 @@
|
||||
{
|
||||
on_demand_tls {
|
||||
ask http://example.com
|
||||
}
|
||||
}
|
||||
|
||||
coder.example.com, *.coder.example.com {
|
||||
reverse_proxy localhost:3000
|
||||
tls {
|
||||
on_demand
|
||||
issuer acme {
|
||||
email email@example.com
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,57 @@
|
||||
version: "3.9"
|
||||
services:
|
||||
coder:
|
||||
image: ghcr.io/coder/coder:${CODER_VERSION:-latest}
|
||||
environment:
|
||||
CODER_PG_CONNECTION_URL: "postgresql://${POSTGRES_USER:-username}:${POSTGRES_PASSWORD:-password}@database/${POSTGRES_DB:-coder}?sslmode=disable"
|
||||
CODER_HTTP_ADDRESS: "0.0.0.0:7080"
|
||||
# You'll need to set CODER_ACCESS_URL to an IP or domain
|
||||
# that workspaces can reach. This cannot be localhost
|
||||
# or 127.0.0.1 for non-Docker templates!
|
||||
CODER_ACCESS_URL: "${CODER_ACCESS_URL}"
|
||||
# Optional) Enable wildcard apps/dashboard port forwarding
|
||||
CODER_WILDCARD_ACCESS_URL: "${CODER_WILDCARD_ACCESS_URL}"
|
||||
# If the coder user does not have write permissions on
|
||||
# the docker socket, you can uncomment the following
|
||||
# lines and set the group ID to one that has write
|
||||
# permissions on the docker socket.
|
||||
#group_add:
|
||||
# - "998" # docker group on host
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
depends_on:
|
||||
database:
|
||||
condition: service_healthy
|
||||
database:
|
||||
image: "postgres:14.2"
|
||||
ports:
|
||||
- "5432:5432"
|
||||
environment:
|
||||
POSTGRES_USER: ${POSTGRES_USER:-username} # The PostgreSQL user (useful to connect to the database)
|
||||
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-password} # The PostgreSQL password (useful to connect to the database)
|
||||
POSTGRES_DB: ${POSTGRES_DB:-coder} # The PostgreSQL default database (automatically created at first launch)
|
||||
volumes:
|
||||
- coder_data:/var/lib/postgresql/data # Use "docker volume rm coder_coder_data" to reset Coder
|
||||
healthcheck:
|
||||
test:
|
||||
[
|
||||
"CMD-SHELL",
|
||||
"pg_isready -U ${POSTGRES_USER:-username} -d ${POSTGRES_DB:-coder}",
|
||||
]
|
||||
interval: 5s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
caddy:
|
||||
image: caddy:2.6.2
|
||||
ports:
|
||||
- "80:80"
|
||||
- "443:443"
|
||||
- "443:443/udp"
|
||||
volumes:
|
||||
- $PWD/Caddyfile:/etc/caddy/Caddyfile
|
||||
- caddy_data:/data
|
||||
- caddy_config:/config
|
||||
volumes:
|
||||
coder_data:
|
||||
caddy_data:
|
||||
caddy_config:
|
||||
@@ -0,0 +1,187 @@
|
||||
# Caddy
|
||||
|
||||
This is an example configuration of how to use Coder with
|
||||
[caddy](https://caddyserver.com/docs). To use Caddy to generate TLS
|
||||
certificates, you'll need a domain name that resolves to your Caddy server.
|
||||
|
||||
## Getting started
|
||||
|
||||
### With docker-compose
|
||||
|
||||
1. [Install Docker](https://docs.docker.com/engine/install/) and
|
||||
[Docker Compose](https://docs.docker.com/compose/install/)
|
||||
|
||||
1. Start with our example configuration
|
||||
|
||||
```shell
|
||||
# Create a project folder
|
||||
cd $HOME
|
||||
mkdir coder-with-caddy
|
||||
cd coder-with-caddy
|
||||
|
||||
# Clone coder/coder and copy the Caddy example
|
||||
git clone https://github.com/coder/coder /tmp/coder
|
||||
mv /tmp/coder/docs/admin/setup/web-server/caddy $(pwd)
|
||||
```
|
||||
|
||||
1. Modify the [Caddyfile](./Caddyfile) and change the following values:
|
||||
|
||||
- `localhost:3000`: Change to `coder:7080` (Coder container on Docker
|
||||
network)
|
||||
- `email@example.com`: Email to request certificates from LetsEncrypt/ZeroSSL
|
||||
(does not have to be Coder admin email)
|
||||
- `coder.example.com`: Domain name you're using for Coder.
|
||||
- `*.coder.example.com`: Domain name for wildcard apps, commonly used for
|
||||
[dashboard port forwarding](../../../networking/port-forwarding.md). This
|
||||
is optional and can be removed.
|
||||
|
||||
1. Start Coder. Set `CODER_ACCESS_URL` and `CODER_WILDCARD_ACCESS_URL` to the
|
||||
domain you're using in your Caddyfile.
|
||||
|
||||
```shell
|
||||
export CODER_ACCESS_URL=https://coder.example.com
|
||||
export CODER_WILDCARD_ACCESS_URL=*.coder.example.com
|
||||
docker compose up -d # Run on startup
|
||||
```
|
||||
|
||||
### Standalone
|
||||
|
||||
1. If you haven't already, [install Coder](../../../../install/index.md)
|
||||
|
||||
2. Install [Caddy Server](https://caddyserver.com/docs/install)
|
||||
|
||||
3. Copy our sample [Caddyfile](./Caddyfile) and change the following values:
|
||||
|
||||
> If you're installed Caddy as a system package, update the default Caddyfile
|
||||
> with `vim /etc/caddy/Caddyfile`
|
||||
|
||||
- `email@example.com`: Email to request certificates from LetsEncrypt/ZeroSSL
|
||||
(does not have to be Coder admin email)
|
||||
- `coder.example.com`: Domain name you're using for Coder.
|
||||
- `*.coder.example.com`: Domain name for wildcard apps, commonly used for
|
||||
[dashboard port forwarding](../../../networking/port-forwarding.md). This
|
||||
is optional and can be removed.
|
||||
- `localhost:3000`: Address Coder is running on. Modify this if you changed
|
||||
`CODER_HTTP_ADDRESS` in the Coder configuration.
|
||||
- _DO NOT CHANGE the `ask http://example.com` line! Doing so will result in
|
||||
your certs potentially not being generated._
|
||||
|
||||
4. [Configure Coder](../../index.md) and change the following values:
|
||||
|
||||
- `CODER_ACCESS_URL`: root domain (e.g. `https://coder.example.com`)
|
||||
- `CODER_WILDCARD_ACCESS_URL`: wildcard domain (e.g. `*.example.com`).
|
||||
|
||||
5. Start the Caddy server:
|
||||
|
||||
If you're [keeping Caddy running](https://caddyserver.com/docs/running) via a
|
||||
system service:
|
||||
|
||||
```shell
|
||||
sudo systemctl restart caddy
|
||||
```
|
||||
|
||||
Or run a standalone server:
|
||||
|
||||
```shell
|
||||
caddy run
|
||||
```
|
||||
|
||||
6. Optionally, use [ufw](https://wiki.ubuntu.com/UncomplicatedFirewall) or
|
||||
another firewall to disable external traffic outside of Caddy.
|
||||
|
||||
```shell
|
||||
# Check status of UncomplicatedFirewall
|
||||
sudo ufw status
|
||||
|
||||
# Allow SSH
|
||||
sudo ufw allow 22
|
||||
|
||||
# Allow HTTP, HTTPS (Caddy)
|
||||
sudo ufw allow 80
|
||||
sudo ufw allow 443
|
||||
|
||||
# Deny direct access to Coder server
|
||||
sudo ufw deny 3000
|
||||
|
||||
# Enable UncomplicatedFirewall
|
||||
sudo ufw enable
|
||||
```
|
||||
|
||||
7. Navigate to your Coder URL! A TLS certificate should be auto-generated on
|
||||
your first visit.
|
||||
|
||||
## Generating wildcard certificates
|
||||
|
||||
By default, this configuration uses Caddy's
|
||||
[on-demand TLS](https://caddyserver.com/docs/caddyfile/options#on-demand-tls) to
|
||||
generate a certificate for each subdomain (e.g. `app1.coder.example.com`,
|
||||
`app2.coder.example.com`). When users visit new subdomains, such as accessing
|
||||
[ports on a workspace](../../../networking/port-forwarding.md), the request will
|
||||
take an additional 5-30 seconds since a new certificate is being generated.
|
||||
|
||||
For production deployments, we recommend configuring Caddy to generate a
|
||||
wildcard certificate, which requires an explicit DNS challenge and additional
|
||||
Caddy modules.
|
||||
|
||||
1. Install a custom Caddy build that includes the
|
||||
[caddy-dns](https://github.com/caddy-dns) module for your DNS provider (e.g.
|
||||
CloudFlare, Route53).
|
||||
|
||||
- Docker:
|
||||
[Build an custom Caddy image](https://github.com/docker-library/docs/tree/master/caddy#adding-custom-caddy-modules)
|
||||
with the module for your DNS provider. Be sure to reference the new image
|
||||
in the `docker-compose.yaml`.
|
||||
|
||||
- Standalone:
|
||||
[Download a custom Caddy build](https://caddyserver.com/download) with the
|
||||
module for your DNS provider. If you're using Debian/Ubuntu, you
|
||||
[can configure the Caddy package](https://caddyserver.com/docs/build#package-support-files-for-custom-builds-for-debianubunturaspbian)
|
||||
to use the new build.
|
||||
|
||||
2. Edit your `Caddyfile` and add the necessary credentials/API tokens to solve
|
||||
the DNS challenge for wildcard certificates.
|
||||
|
||||
For example, for AWS Route53:
|
||||
|
||||
```diff
|
||||
tls {
|
||||
- on_demand
|
||||
- issuer acme {
|
||||
- email email@example.com
|
||||
- }
|
||||
|
||||
+ dns route53 {
|
||||
+ max_retries 10
|
||||
+ aws_profile "real-profile"
|
||||
+ access_key_id "AKI..."
|
||||
+ secret_access_key "wJa..."
|
||||
+ token "TOKEN..."
|
||||
+ region "us-east-1"
|
||||
+ }
|
||||
}
|
||||
```
|
||||
|
||||
> Configuration reference from
|
||||
> [caddy-dns/route53](https://github.com/caddy-dns/route53).
|
||||
|
||||
And for CloudFlare:
|
||||
|
||||
Generate a
|
||||
[token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token)
|
||||
with the following permissions:
|
||||
|
||||
- Zone:Zone:Edit
|
||||
|
||||
```diff
|
||||
tls {
|
||||
- on_demand
|
||||
- issuer acme {
|
||||
- email email@example.com
|
||||
- }
|
||||
|
||||
+ dns cloudflare CLOUDFLARE_API_TOKEN
|
||||
}
|
||||
```
|
||||
|
||||
> Configuration reference from
|
||||
> [caddy-dns/cloudflare](https://github.com/caddy-dns/cloudflare).
|
||||
@@ -0,0 +1,179 @@
|
||||
# How to use NGINX as a reverse-proxy with LetsEncrypt
|
||||
|
||||
## Requirements
|
||||
|
||||
1. Start a Coder deployment and be sure to set the following
|
||||
[configuration values](../../index.md):
|
||||
|
||||
```env
|
||||
CODER_HTTP_ADDRESS=127.0.0.1:3000
|
||||
CODER_ACCESS_URL=https://coder.example.com
|
||||
CODER_WILDCARD_ACCESS_URL=*.coder.example.com
|
||||
```
|
||||
|
||||
Throughout the guide, be sure to replace `coder.example.com` with the domain
|
||||
you intend to use with Coder.
|
||||
|
||||
2. Configure your DNS provider to point your coder.example.com and
|
||||
\*.coder.example.com to your server's public IP address.
|
||||
|
||||
> For example, to use `coder.example.com` as your subdomain, configure
|
||||
> `coder.example.com` and `*.coder.example.com` to point to your server's
|
||||
> public ip. This can be done by adding A records in your DNS provider's
|
||||
> dashboard.
|
||||
|
||||
3. Install NGINX (assuming you're on Debian/Ubuntu):
|
||||
|
||||
```shell
|
||||
sudo apt install nginx
|
||||
```
|
||||
|
||||
4. Stop NGINX service:
|
||||
|
||||
```shell
|
||||
sudo systemctl stop nginx
|
||||
```
|
||||
|
||||
## Adding Coder deployment subdomain
|
||||
|
||||
> This example assumes Coder is running locally on `127.0.0.1:3000` and that
|
||||
> you're using `coder.example.com` as your subdomain.
|
||||
|
||||
1. Create NGINX configuration for this app:
|
||||
|
||||
```shell
|
||||
sudo touch /etc/nginx/sites-available/coder.example.com
|
||||
```
|
||||
|
||||
2. Activate this file:
|
||||
|
||||
```shell
|
||||
sudo ln -s /etc/nginx/sites-available/coder.example.com /etc/nginx/sites-enabled/coder.example.com
|
||||
```
|
||||
|
||||
## Install and configure LetsEncrypt Certbot
|
||||
|
||||
1. Install LetsEncrypt Certbot: Refer to the
|
||||
[CertBot documentation](https://certbot.eff.org/instructions?ws=apache&os=ubuntufocal&tab=wildcard).
|
||||
Be sure to pick the wildcard tab and select your DNS provider for
|
||||
instructions to install the necessary DNS plugin.
|
||||
|
||||
## Create DNS provider credentials
|
||||
|
||||
> This example assumes you're using CloudFlare as your DNS provider. For other
|
||||
> providers, refer to the
|
||||
> [CertBot documentation](https://eff-certbot.readthedocs.io/en/stable/using.html#dns-plugins).
|
||||
|
||||
1. Create an API token for the DNS provider you're using: e.g.
|
||||
[CloudFlare](https://developers.cloudflare.com/fundamentals/api/get-started/create-token)
|
||||
with the following permissions:
|
||||
|
||||
- Zone - DNS - Edit
|
||||
|
||||
2. Create a file in `.secrets/certbot/cloudflare.ini` with the following
|
||||
content:
|
||||
|
||||
```ini
|
||||
dns_cloudflare_api_token = YOUR_API_TOKEN
|
||||
```
|
||||
|
||||
```shell
|
||||
mkdir -p ~/.secrets/certbot
|
||||
touch ~/.secrets/certbot/cloudflare.ini
|
||||
nano ~/.secrets/certbot/cloudflare.ini
|
||||
```
|
||||
|
||||
3. Set the correct permissions:
|
||||
|
||||
```shell
|
||||
sudo chmod 600 ~/.secrets/certbot/cloudflare.ini
|
||||
```
|
||||
|
||||
## Create the certificate
|
||||
|
||||
1. Create the wildcard certificate:
|
||||
|
||||
```shell
|
||||
sudo certbot certonly --dns-cloudflare --dns-cloudflare-credentials ~/.secrets/certbot/cloudflare.ini -d coder.example.com -d *.coder.example.com
|
||||
```
|
||||
|
||||
## Configure nginx
|
||||
|
||||
1. Edit the file with:
|
||||
|
||||
```shell
|
||||
sudo nano /etc/nginx/sites-available/coder.example.com
|
||||
```
|
||||
|
||||
2. Add the following content:
|
||||
|
||||
```nginx
|
||||
server {
|
||||
server_name coder.example.com *.coder.example.com;
|
||||
|
||||
# HTTP configuration
|
||||
listen 80;
|
||||
listen [::]:80;
|
||||
|
||||
# HTTP to HTTPS
|
||||
if ($scheme != "https") {
|
||||
return 301 https://$host$request_uri;
|
||||
}
|
||||
|
||||
# HTTPS configuration
|
||||
listen [::]:443 ssl ipv6only=on;
|
||||
listen 443 ssl;
|
||||
ssl_certificate /etc/letsencrypt/live/coder.example.com/fullchain.pem;
|
||||
ssl_certificate_key /etc/letsencrypt/live/coder.example.com/privkey.pem;
|
||||
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:3000; # Change this to your coder deployment port default is 3000
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection upgrade;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $http_x_forwarded_proto;
|
||||
add_header Strict-Transport-Security "max-age=15552000; includeSubDomains" always;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> Don't forget to change: `coder.example.com` by your (sub)domain
|
||||
|
||||
3. Test the configuration:
|
||||
|
||||
```shell
|
||||
sudo nginx -t
|
||||
```
|
||||
|
||||
## Refresh certificates automatically
|
||||
|
||||
1. Create a new file in `/etc/cron.weekly`:
|
||||
|
||||
```shell
|
||||
sudo touch /etc/cron.weekly/certbot
|
||||
```
|
||||
|
||||
2. Make it executable:
|
||||
|
||||
```shell
|
||||
sudo chmod +x /etc/cron.weekly/certbot
|
||||
```
|
||||
|
||||
3. And add this code:
|
||||
|
||||
```shell
|
||||
#!/bin/sh
|
||||
sudo certbot renew -q
|
||||
```
|
||||
|
||||
## Restart NGINX
|
||||
|
||||
```shell
|
||||
sudo systemctl restart nginx
|
||||
```
|
||||
|
||||
And that's it, you should now be able to access Coder at your sub(domain) e.g.
|
||||
`https://coder.example.com`.
|
||||
Reference in New Issue
Block a user