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
@@ -27,7 +27,7 @@
|
||||
"aws",
|
||||
"persistent-vm"
|
||||
],
|
||||
"markdown": "\n# Remote Development on AWS EC2 VMs (Linux)\n\nProvision AWS EC2 VMs as [Coder workspaces](https://coder.com/docs/workspaces) with this example template.\n\n\u003c!-- TODO: Add screenshot --\u003e\n\n## Prerequisites\n\n### Authentication\n\nBy default, this template authenticates to AWS using the provider's default [authentication methods](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication-and-configuration).\n\nThe simplest way (without making changes to the template) is via environment variables (e.g. `AWS_ACCESS_KEY_ID`) or a [credentials file](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-format). If you are running Coder on a VM, this file must be in `/home/coder/aws/credentials`.\n\nTo use another [authentication method](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication), edit the template.\n\n## Required permissions / policy\n\nThe following sample policy allows Coder to create EC2 instances and modify\ninstances provisioned by Coder:\n\n```json\n{\n\t\"Version\": \"2012-10-17\",\n\t\"Statement\": [\n\t\t{\n\t\t\t\"Sid\": \"VisualEditor0\",\n\t\t\t\"Effect\": \"Allow\",\n\t\t\t\"Action\": [\n\t\t\t\t\"ec2:GetDefaultCreditSpecification\",\n\t\t\t\t\"ec2:DescribeIamInstanceProfileAssociations\",\n\t\t\t\t\"ec2:DescribeTags\",\n\t\t\t\t\"ec2:DescribeInstances\",\n\t\t\t\t\"ec2:DescribeInstanceTypes\",\n\t\t\t\t\"ec2:CreateTags\",\n\t\t\t\t\"ec2:RunInstances\",\n\t\t\t\t\"ec2:DescribeInstanceCreditSpecifications\",\n\t\t\t\t\"ec2:DescribeImages\",\n\t\t\t\t\"ec2:ModifyDefaultCreditSpecification\",\n\t\t\t\t\"ec2:DescribeVolumes\"\n\t\t\t],\n\t\t\t\"Resource\": \"*\"\n\t\t},\n\t\t{\n\t\t\t\"Sid\": \"CoderResources\",\n\t\t\t\"Effect\": \"Allow\",\n\t\t\t\"Action\": [\n\t\t\t\t\"ec2:DescribeInstanceAttribute\",\n\t\t\t\t\"ec2:UnmonitorInstances\",\n\t\t\t\t\"ec2:TerminateInstances\",\n\t\t\t\t\"ec2:StartInstances\",\n\t\t\t\t\"ec2:StopInstances\",\n\t\t\t\t\"ec2:DeleteTags\",\n\t\t\t\t\"ec2:MonitorInstances\",\n\t\t\t\t\"ec2:CreateTags\",\n\t\t\t\t\"ec2:RunInstances\",\n\t\t\t\t\"ec2:ModifyInstanceAttribute\",\n\t\t\t\t\"ec2:ModifyInstanceCreditSpecification\"\n\t\t\t],\n\t\t\t\"Resource\": \"arn:aws:ec2:*:*:instance/*\",\n\t\t\t\"Condition\": {\n\t\t\t\t\"StringEquals\": {\n\t\t\t\t\t\"aws:ResourceTag/Coder_Provisioned\": \"true\"\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t]\n}\n```\n\n## Architecture\n\nThis template provisions the following resources:\n\n- AWS Instance\n\nCoder uses `aws_ec2_instance_state` to start and stop the VM. This example template is fully persistent, meaning the full filesystem is preserved when the workspace restarts. See this [community example](https://github.com/bpmct/coder-templates/tree/main/aws-linux-ephemeral) of an ephemeral AWS instance.\n\n\u003e **Note**\n\u003e This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.\n\n## code-server\n\n`code-server` is installed via the `startup_script` argument in the `coder_agent`\nresource block. The `coder_app` resource is defined to access `code-server` through\nthe dashboard UI over `localhost:13337`.\n"
|
||||
"markdown": "\n# Remote Development on AWS EC2 VMs (Linux)\n\nProvision AWS EC2 VMs as [Coder workspaces](https://coder.com/docs/workspaces) with this example template.\n\n## Prerequisites\n\n### Authentication\n\nBy default, this template authenticates to AWS using the provider's default [authentication methods](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication-and-configuration).\n\nThe simplest way (without making changes to the template) is via environment variables (e.g. `AWS_ACCESS_KEY_ID`) or a [credentials file](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-format). If you are running Coder on a VM, this file must be in `/home/coder/aws/credentials`.\n\nTo use another [authentication method](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication), edit the template.\n\n## Required permissions / policy\n\nThe following sample policy allows Coder to create EC2 instances and modify\ninstances provisioned by Coder:\n\n```json\n{\n\t\"Version\": \"2012-10-17\",\n\t\"Statement\": [\n\t\t{\n\t\t\t\"Sid\": \"VisualEditor0\",\n\t\t\t\"Effect\": \"Allow\",\n\t\t\t\"Action\": [\n\t\t\t\t\"ec2:GetDefaultCreditSpecification\",\n\t\t\t\t\"ec2:DescribeIamInstanceProfileAssociations\",\n\t\t\t\t\"ec2:DescribeTags\",\n\t\t\t\t\"ec2:DescribeInstances\",\n\t\t\t\t\"ec2:DescribeInstanceTypes\",\n\t\t\t\t\"ec2:CreateTags\",\n\t\t\t\t\"ec2:RunInstances\",\n\t\t\t\t\"ec2:DescribeInstanceCreditSpecifications\",\n\t\t\t\t\"ec2:DescribeImages\",\n\t\t\t\t\"ec2:ModifyDefaultCreditSpecification\",\n\t\t\t\t\"ec2:DescribeVolumes\"\n\t\t\t],\n\t\t\t\"Resource\": \"*\"\n\t\t},\n\t\t{\n\t\t\t\"Sid\": \"CoderResources\",\n\t\t\t\"Effect\": \"Allow\",\n\t\t\t\"Action\": [\n\t\t\t\t\"ec2:DescribeInstanceAttribute\",\n\t\t\t\t\"ec2:UnmonitorInstances\",\n\t\t\t\t\"ec2:TerminateInstances\",\n\t\t\t\t\"ec2:StartInstances\",\n\t\t\t\t\"ec2:StopInstances\",\n\t\t\t\t\"ec2:DeleteTags\",\n\t\t\t\t\"ec2:MonitorInstances\",\n\t\t\t\t\"ec2:CreateTags\",\n\t\t\t\t\"ec2:RunInstances\",\n\t\t\t\t\"ec2:ModifyInstanceAttribute\",\n\t\t\t\t\"ec2:ModifyInstanceCreditSpecification\"\n\t\t\t],\n\t\t\t\"Resource\": \"arn:aws:ec2:*:*:instance/*\",\n\t\t\t\"Condition\": {\n\t\t\t\t\"StringEquals\": {\n\t\t\t\t\t\"aws:ResourceTag/Coder_Provisioned\": \"true\"\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t]\n}\n```\n\n## Architecture\n\nThis template provisions the following resources:\n\n- AWS Instance\n\nCoder uses `aws_ec2_instance_state` to start and stop the VM. This example template is fully persistent, meaning the full filesystem is preserved when the workspace restarts. See this [community example](https://github.com/bpmct/coder-templates/tree/main/aws-linux-ephemeral) of an ephemeral AWS instance.\n\n\u003e **Note**\n\u003e This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.\n\n## code-server\n\n`code-server` is installed via the `startup_script` argument in the `coder_agent`\nresource block. The `coder_app` resource is defined to access `code-server` through\nthe dashboard UI over `localhost:13337`.\n"
|
||||
},
|
||||
{
|
||||
"id": "aws-windows",
|
||||
@@ -155,7 +155,7 @@
|
||||
"nomad",
|
||||
"container"
|
||||
],
|
||||
"markdown": "\n# Remote Development on Nomad\n\nProvision Nomad Jobs as [Coder workspaces](https://coder.com/docs/workspaces) with this example template. This example shows how to use Nomad service tasks to be used as a development environment using docker and host csi volumes.\n\n\u003c!-- TODO: Add screenshot --\u003e\n\n\u003e **Note**\n\u003e This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.\n\n## Prerequisites\n\n- [Nomad](https://www.nomadproject.io/downloads)\n- [Docker](https://docs.docker.com/get-docker/)\n\n## Setup\n\n### 1. Start the CSI Host Volume Plugin\n\nThe CSI Host Volume plugin is used to mount host volumes into Nomad tasks. This is useful for development environments where you want to mount persistent volumes into your container workspace.\n\n1. Login to the Nomad server using SSH.\n\n2. Append the following stanza to your Nomad server configuration file and restart the nomad service.\n\n ```hcl\n plugin \"docker\" {\n config {\n allow_privileged = true\n }\n }\n ```\n\n ```shell\n sudo systemctl restart nomad\n ```\n\n3. Create a file `hostpath.nomad` with following content:\n\n ```hcl\n job \"hostpath-csi-plugin\" {\n datacenters = [\"dc1\"]\n type = \"system\"\n\n group \"csi\" {\n task \"plugin\" {\n driver = \"docker\"\n\n config {\n image = \"registry.k8s.io/sig-storage/hostpathplugin:v1.10.0\"\n\n args = [\n \"--drivername=csi-hostpath\",\n \"--v=5\",\n \"--endpoint=${CSI_ENDPOINT}\",\n \"--nodeid=node-${NOMAD_ALLOC_INDEX}\",\n ]\n\n privileged = true\n }\n\n csi_plugin {\n id = \"hostpath\"\n type = \"monolith\"\n mount_dir = \"/csi\"\n }\n\n resources {\n cpu = 256\n memory = 128\n }\n }\n }\n }\n ```\n\n4. Run the job:\n\n ```shell\n nomad job run hostpath.nomad\n ```\n\n### 2. Setup the Nomad Template\n\n1. Create the template by running the following command:\n\n ```shell\n coder template init nomad-docker\n cd nomad-docker\n coder template push\n ```\n\n2. Set up Nomad server address and optional authentication:\n\n3. Create a new workspace and start developing.\n"
|
||||
"markdown": "\n# Remote Development on Nomad\n\nProvision Nomad Jobs as [Coder workspaces](https://coder.com/docs/workspaces) with this example template. This example shows how to use Nomad service tasks to be used as a development environment using docker and host csi volumes.\n\n\u003c!-- TODO: Add screenshot --\u003e\n\n\u003e **Note**\n\u003e This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.\n\n## Prerequisites\n\n- [Nomad](https://www.nomadproject.io/downloads)\n- [Docker](https://docs.docker.com/get-docker/)\n\n## Setup\n\n### 1. Start the CSI Host Volume Plugin\n\nThe CSI Host Volume plugin is used to mount host volumes into Nomad tasks. This is useful for development environments where you want to mount persistent volumes into your container workspace.\n\n1. Login to the Nomad server using SSH.\n\n2. Append the following stanza to your Nomad server configuration file and restart the nomad service.\n\n ```tf\n plugin \"docker\" {\n config {\n allow_privileged = true\n }\n }\n ```\n\n ```shell\n sudo systemctl restart nomad\n ```\n\n3. Create a file `hostpath.nomad` with following content:\n\n ```tf\n job \"hostpath-csi-plugin\" {\n datacenters = [\"dc1\"]\n type = \"system\"\n\n group \"csi\" {\n task \"plugin\" {\n driver = \"docker\"\n\n config {\n image = \"registry.k8s.io/sig-storage/hostpathplugin:v1.10.0\"\n\n args = [\n \"--drivername=csi-hostpath\",\n \"--v=5\",\n \"--endpoint=${CSI_ENDPOINT}\",\n \"--nodeid=node-${NOMAD_ALLOC_INDEX}\",\n ]\n\n privileged = true\n }\n\n csi_plugin {\n id = \"hostpath\"\n type = \"monolith\"\n mount_dir = \"/csi\"\n }\n\n resources {\n cpu = 256\n memory = 128\n }\n }\n }\n }\n ```\n\n4. Run the job:\n\n ```shell\n nomad job run hostpath.nomad\n ```\n\n### 2. Setup the Nomad Template\n\n1. Create the template by running the following command:\n\n ```shell\n coder template init nomad-docker\n cd nomad-docker\n coder template push\n ```\n\n2. Set up Nomad server address and optional authentication:\n\n3. Create a new workspace and start developing.\n"
|
||||
},
|
||||
{
|
||||
"id": "scratch",
|
||||
|
||||
@@ -11,8 +11,6 @@ tags: [vm, linux, aws, persistent-vm]
|
||||
|
||||
Provision AWS EC2 VMs as [Coder workspaces](https://coder.com/docs/workspaces) with this example template.
|
||||
|
||||
<!-- TODO: Add screenshot -->
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Authentication
|
||||
|
||||
@@ -31,7 +31,7 @@ The CSI Host Volume plugin is used to mount host volumes into Nomad tasks. This
|
||||
|
||||
2. Append the following stanza to your Nomad server configuration file and restart the nomad service.
|
||||
|
||||
```hcl
|
||||
```tf
|
||||
plugin "docker" {
|
||||
config {
|
||||
allow_privileged = true
|
||||
@@ -45,7 +45,7 @@ The CSI Host Volume plugin is used to mount host volumes into Nomad tasks. This
|
||||
|
||||
3. Create a file `hostpath.nomad` with following content:
|
||||
|
||||
```hcl
|
||||
```tf
|
||||
job "hostpath-csi-plugin" {
|
||||
datacenters = ["dc1"]
|
||||
type = "system"
|
||||
|
||||
@@ -1,156 +0,0 @@
|
||||
# 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](https://coder.com/docs/admin/configure):
|
||||
|
||||
```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://dash.cloudflare.com/profile/api-tokens) 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`.
|
||||
@@ -1,28 +0,0 @@
|
||||
# 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>
|
||||
|
||||
@@ -1,15 +0,0 @@
|
||||
{
|
||||
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
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,149 +0,0 @@
|
||||
# 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/examples/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](https://coder.com/docs/networking/port-forwarding#dashboard). 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](https://coder.com/docs/install)
|
||||
|
||||
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](https://coder.com/docs/networking/port-forwarding#dashboard). 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](https://coder.com/docs/admin/configure) 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](../../../docs/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://dash.cloudflare.com/profile/api-tokens) 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).
|
||||
@@ -1,57 +0,0 @@
|
||||
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:
|
||||
@@ -1,163 +0,0 @@
|
||||
# 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](https://coder.com/docs/admin/configure):
|
||||
|
||||
```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://dash.cloudflare.com/profile/api-tokens) 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