added appearance as a subsection of setup

stirby · stirby · commit 47334848ad89 · 2024-10-01T23:42:34.000Z
diff --git a/docs/admin/README.md b/docs/admin/README.md
@@ -2,7 +2,7 @@
 
 These guides contain information on managing the Coder control plane and [authoring templates](./templates/README.md).
 
-First time viewers looking to set up control plane access can start with the [configuration guide](./setup.md). If you're a team lead looking to design environments for your developers, check out our [templates guides](./templates/README.md). If you are a developer using Coder, we recommend the [user guides](../user-guides/README.md).
+First time viewers looking to set up control plane access can start with the [configuration guide](./setup/README.md). If you're a team lead looking to design environments for your developers, check out our [templates guides](./templates/README.md). If you are a developer using Coder, we recommend the [user guides](../user-guides/README.md).
 
 For automation and scripting workflows, see our [CLI](../reference/cli/README.md) and [API](../reference/api/README.md) docs.
 
diff --git a/docs/admin/monitoring/health-check.md b/docs/admin/monitoring/health-check.md
@@ -13,7 +13,7 @@ The deployment health page is broken up into the following sections:
 ## Access URL
 
 The Access URL section shows checks related to Coder's
-[access URL](../setup.md#access-url).
+[access URL](../setup/README.md#access-url).
 
 Coder will periodically send a GET request to `${CODER_ACCESS_URL}/healthz` and
 validate that the response is `200 OK`. The expected response body is also the
@@ -27,7 +27,8 @@ _Access URL not set_
 
 **Problem:** no access URL has been configured.
 
-**Solution:** configure an [access URL](../setup.md#access-url) for Coder.
+**Solution:** configure an [access URL](../setup/README.md#access-url) for
+Coder.
 
 ### EACS02
 
diff --git a/docs/admin/networking/README.md b/docs/admin/networking/README.md
@@ -59,7 +59,7 @@ In order for clients to be able to establish direct connections:
 ## coder server
 
 Workspaces connect to the coder server via the server's external address, set
-via [`ACCESS_URL`](../../admin/setup.md#access-url). There must not be a NAT
+via [`ACCESS_URL`](../../admin/setup/README.md#access-url). There must not be a NAT
 between workspaces and coder server.
 
 Users connect to the coder server's dashboard and API through its `ACCESS_URL`
diff --git a/docs/admin/networking/port-forwarding.md b/docs/admin/networking/port-forwarding.md
@@ -49,10 +49,10 @@ For more examples, see `coder port-forward --help`.
 ## Dashboard
 
 > To enable port forwarding via the dashboard, Coder must be configured with a
-> [wildcard access URL](../../admin/setup.md#wildcard-access-url). If an access
-> URL is not specified, Coder will create
-> [a publicly accessible URL](../../admin/setup.md#tunnel) to reverse proxy the
-> deployment, and port forwarding will work.
+> [wildcard access URL](../../admin/setup/README.md#wildcard-access-url). If an
+> access URL is not specified, Coder will create
+> [a publicly accessible URL](../../admin/setup/README.md#tunnel) to reverse
+> proxy the deployment, and port forwarding will work.
 >
 > There is a
 > [DNS limitation](https://datatracker.ietf.org/doc/html/rfc1035#section-2.3.1)
diff --git a/docs/admin/setup/README.md b/docs/admin/setup/README.md
diff --git a/docs/admin/setup/appearance.md b/docs/admin/setup/appearance.md
@@ -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 and logo url](../../images/admin/setup/appearance/application-name-logo-url.png)
+
+## 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 banner](../../images/admin/setup/appearance/announcement_banner_settings.png)
+
+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.
+
+![Multiple announcements](../../images/admin/setup/appearance/multiple-banners.PNG)
+
+Example: Adhere to government network classification requirements and notify
+users of which network their Coder deployment is on.
+
+![service banner secret](../../images/admin/setup/appearance/service-banner-secret.png)
+
+## 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.
+
+![support links](../../images/admin/setup/appearance/support-links.png)
+
+### 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
+```
diff --git a/docs/admin/templates/extending-templates/icons.md b/docs/admin/templates/extending-templates/icons.md
@@ -44,7 +44,7 @@ come bundled with your Coder deployment.
     CODER_EXTERNAL_AUTH_1_ICON=/icon/google.svg
     ```
 
-- [**Support Links**](../admin/appearance.md#support-links):
+- [**Support Links**](../admin/setup/appearance.md#support-links):
 
   - Use icons for support links to make them recognizable. You can set the
     `icon` field for each link in `CODER_SUPPORT_LINKS` array.
diff --git a/docs/admin/templates/extending-templates/web-ides.md b/docs/admin/templates/extending-templates/web-ides.md
@@ -196,8 +196,8 @@ module "jupyter" {
 ```
 
 If you cannot enable a
-[wildcard subdomain](../../../admin/setup.md#wildcard-access-url), you can
-configure the template to run Jupyter on a path. There is however
+[wildcard subdomain](../../../admin/setup/README.md#wildcard-access-url), you
+can configure the template to run Jupyter on a path. There is however
 [security risk](../../../reference/cli/server#--dangerous-allow-path-app-sharing)
 running an app on a path and the template code is more complicated with coder
 value substitution to recreate the path structure.
diff --git a/docs/admin/templates/troubleshooting.md b/docs/admin/templates/troubleshooting.md
@@ -21,7 +21,7 @@ practices:
 
 - Ensure the resource has `curl` installed (alternatively, `wget` or `busybox`)
 - Ensure the resource can `curl` your Coder
-  [access URL](../../admin/setup.md#access-url)
+  [access URL](../../admin/setup/README.md#access-url)
 - Manually connect to the resource and check the agent logs (e.g.,
   `kubectl exec`, `docker exec` or AWS console)
   - The Coder agent logs are typically stored in `/tmp/coder-agent.log`
@@ -31,7 +31,7 @@ practices:
     `/tmp/coder-shutdown-script.log`
 - This can also happen if the websockets are not being forwarded correctly when
   running Coder behind a reverse proxy.
-  [Read our reverse-proxy docs](../../admin/setup.md#tls--reverse-proxy)
+  [Read our reverse-proxy docs](../../admin/setup/README.md#tls--reverse-proxy)
 
 ## Startup script issues
 
diff --git a/docs/admin/users/oidc-auth.md b/docs/admin/users/oidc-auth.md
@@ -119,7 +119,7 @@ CODER_OIDC_ICON_URL=https://gitea.io/images/gitea.png
 ```
 
 To change the icon and text above the OpenID Connect button, see application
-name and logo url in [appearance](./appearance.md) settings.
+name and logo url in [appearance](../setup/appearance.md) settings.
 
 ## Disable Built-in Authentication
 
diff --git a/docs/admin/users/quotas.md b/docs/admin/users/quotas.md
@@ -104,4 +104,4 @@ Form will never get held up by quota enforcement.
 ## Up next
 
 - [Group Sync](./group-sync.md)
-- [Control plane configuration](../setup.md)
+- [Control plane configuration](../setup/README.md)
diff --git a/docs/images/admin/service-banner-config.png b/docs/images/admin/service-banner-config.png
diff --git a/docs/images/admin/setup/appearance/announcement_banner_settings.png b/docs/images/admin/setup/appearance/announcement_banner_settings.png
diff --git a/docs/images/admin/setup/appearance/application-name-logo-url.png b/docs/images/admin/setup/appearance/application-name-logo-url.png
diff --git a/docs/images/admin/setup/appearance/multiple-banners.PNG b/docs/images/admin/setup/appearance/multiple-banners.PNG
diff --git a/docs/images/admin/setup/appearance/service-banner-maintenance.png b/docs/images/admin/setup/appearance/service-banner-maintenance.png
diff --git a/docs/images/admin/setup/appearance/service-banner-secret.png b/docs/images/admin/setup/appearance/service-banner-secret.png
diff --git a/docs/images/admin/setup/appearance/support-links.png b/docs/images/admin/setup/appearance/support-links.png
diff --git a/docs/install/README.md b/docs/install/README.md
@@ -65,4 +65,4 @@ coder login https://coder.example.com
 ## Next up
 
 - [Create your first template](../start/first-template.md)
-- [Expose your control plane to other users](../admin/setup.md)
+- [Expose your control plane to other users](../admin/setup/README.md)
diff --git a/docs/install/cli.md b/docs/install/cli.md
@@ -57,4 +57,4 @@ coder login https://coder.example.com
 ## Next up
 
 - [Create your first template](../tutorials/template-from-scratch.md)
-- [Control plane configuration](../admin/setup.md)
+- [Control plane configuration](../admin/setup/README.md)
diff --git a/docs/install/cloud/compute-engine.md b/docs/install/cloud/compute-engine.md
@@ -31,7 +31,7 @@ Your browser does not support the video tag.
 </video>
 
 Be sure to add a keypair so that you can connect over SSH to further
-[configure Coder](../../admin/setup.md).
+[configure Coder](../../admin/setup/README.md).
 
 After launching the instance, wait 30 seconds and navigate to the public IPv4
 address. You should be redirected to a public tunnel URL.
@@ -48,8 +48,8 @@ pre-installed.
 
 Coder is primarily configured by server-side flags and environment variables.
 Given you created or added key-pairs when launching the instance, you can
-[configure your Coder deployment](../../admin/setup.md) by logging in via SSH or
-using the console:
+[configure your Coder deployment](../../admin/setup/README.md) by logging in via
+SSH or using the console:
 
 ```shell
 ssh ubuntu@<gcp-public-IPv4>
@@ -74,5 +74,5 @@ to set up authentication.
 
 - [Use your IDE with Coder](../../user-guides/workspace-access/README.md)
 - [Writing custom templates for Coder](../../admin/templates/README.md)
-- [Configure the Coder server](../../admin/setup.md)
-- [Use your own domain + TLS](../../admin/setup.md#tls--reverse-proxy)
+- [Configure the Coder server](../../admin/setup/README.md)
+- [Use your own domain + TLS](../../admin/setup/README.md#tls--reverse-proxy)
diff --git a/docs/install/cloud/ec2.md b/docs/install/cloud/ec2.md
@@ -29,7 +29,7 @@ deployments and you should adjust your infrastructure when preparing for
 production use. See: [Scaling Coder](../../admin/infrastructure/README.md)
 
 Be sure to add a keypair so that you can connect over SSH to further
-[configure Coder](../../admin/setup.md).
+[configure Coder](../../admin/setup/README.md).
 
 After launching the instance, wait 30 seconds and navigate to the public IPv4
 address. You should be redirected to a public tunnel URL.
@@ -49,8 +49,8 @@ pre-installed.
 
 Coder is primarily configured by server-side flags and environment variables.
 Given you created or added key-pairs when launching the instance, you can
-[configure your Coder deployment](../../admin/setup.md) by logging in via SSH or
-using the console:
+[configure your Coder deployment](../../admin/setup/README.md) by logging in via
+SSH or using the console:
 
 <!-- TOOD(@kylecarbs): fix this weird formatting (https://imgur.com/a/LAUY3cT) -->
 
@@ -86,5 +86,5 @@ creating VM-based workspaces.
 
 - [IDEs with Coder](../../user-guides/workspace-access/README.md)
 - [Writing custom templates for Coder](../../admin/templates/README.md)
-- [Configure the Coder server](../../admin/setup.md)
-- [Use your own domain + TLS](../../admin/setup.md#tls--reverse-proxy)
+- [Configure the Coder server](../../admin/setup/README.md)
+- [Use your own domain + TLS](../../admin/setup/README.md#tls--reverse-proxy)
diff --git a/docs/install/database.md b/docs/install/database.md
@@ -20,9 +20,9 @@ With `psql -U coder`:
 CREATE DATABASE coder;
 ```
 
-Coder configuration is defined via [environment variables](../admin/setup.md).
-The database client requires the connection string provided via the
-`CODER_PG_CONNECTION_URL` variable.
+Coder configuration is defined via
+[environment variables](../admin/setup/README.md). The database client requires
+the connection string provided via the `CODER_PG_CONNECTION_URL` variable.
 
 ```shell
 export CODER_PG_CONNECTION_URL="postgres://coder:secret42@localhost/coder?sslmode=disable"
diff --git a/docs/install/docker.md b/docs/install/docker.md
@@ -77,7 +77,7 @@ which includes an PostgreSQL container and volume.
    workspace
 
 Coder configuration is defined via environment variables. Learn more about
-Coder's [configuration options](../admin/setup.md).
+Coder's [configuration options](../admin/setup/README.md).
 
 ## Troubleshooting
 
@@ -104,10 +104,10 @@ group, the above may not work as-is.
 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/setup.md#tunnel). For production deployments, we
-recommend setting an [access URL](../admin/setup.md#access-url)
+[Coder's tunnel](../admin/setup/README.md#tunnel). For production deployments,
+we recommend setting an [access URL](../admin/setup/README.md#access-url)
 
 ## Next steps
 
 - [Create your first template](../tutorials/template-from-scratch.md)
-- [Control plane configuration](../admin/setup.md#configure-control-plane-access)
+- [Control plane configuration](../admin/setup/README.md#configure-control-plane-access)
diff --git a/docs/install/kubernetes.md b/docs/install/kubernetes.md
@@ -293,4 +293,4 @@ steps.
 ## Next steps
 
 - [Create your first template](../tutorials/template-from-scratch.md)
-- [Control plane configuration](../admin/setup.md)
+- [Control plane configuration](../admin/setup/README.md)
diff --git a/docs/install/offline.md b/docs/install/offline.md
@@ -265,4 +265,4 @@ local machine has outbound HTTPS (port 443) connectivity to:
 ## Next steps
 
 - [Create your first template](../tutorials/template-from-scratch.md)
-- [Control plane configuration](../admin/setup.md)
+- [Control plane configuration](../admin/setup/README.md)
diff --git a/docs/install/openshift.md b/docs/install/openshift.md
@@ -326,4 +326,4 @@ This template should be ready to use straight away.
 ## Next steps
 
 - [Create your first template](../tutorials/template-from-scratch.md)
-- [Control plane configuration](../admin/setup.md)
+- [Control plane configuration](../admin/setup/README.md)
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -153,8 +153,16 @@
 				{
 					"title": "Setup",
 					"description": "Configure user access to your control plane.",
-					"path": "./admin/setup.md",
-					"icon_path": "./images/icons/toggle_on.svg"
+					"path": "./admin/setup/README.md",
+					"icon_path": "./images/icons/toggle_on.svg",
+					"children": [
+						{
+							"title": "Appearance",
+							"description": "Learn how to configure the appearance of Coder",
+							"path": "./admin/appearance.md",
+							"state": ["enterprise", "premium"]
+						}
+					]
 				},
 				{
 					"title": "Infrastructure",
diff --git a/docs/tutorials/faqs.md b/docs/tutorials/faqs.md
@@ -123,9 +123,9 @@ resource "coder_app" "code-server" {
 An important concept to understand is that Coder creates workspaces which have
 an agent that must be able to reach the `coder server`.
 
-If the [`CODER_ACCESS_URL`](../admin/setup.md#access-url) is not accessible from
-a workspace, the workspace may build, but the agent cannot reach Coder, and thus
-the missing icons. e.g., Terminal, IDEs, Apps.
+If the [`CODER_ACCESS_URL`](../admin/setup/README.md#access-url) is not
+accessible from a workspace, the workspace may build, but the agent cannot reach
+Coder, and thus the missing icons. e.g., Terminal, IDEs, Apps.
 
 > By default, `coder server` automatically creates an Internet-accessible
 > reverse proxy so that workspaces you create can reach the server.
diff --git a/docs/user-guides/workspace-access/jetbrains.md b/docs/user-guides/workspace-access/jetbrains.md
@@ -40,8 +40,8 @@ manually setting up an SSH connection.
 
    ![Gateway Connect to Coder](../../images/gateway/plugin-connect-to-coder.png)
 
-1. Enter your Coder deployment's [Access Url](../../admin/setup.md#access-url)
-   and click **Connect**.
+1. Enter your Coder deployment'ssetup/README.md
+   [Access Url](../../admin/setup/README.md#access-url) and click **Connect**.
 
    Gateway opens your Coder deployment's `cli-auth` page with a session token.
    Click the copy button, paste the session token in the Gateway **Session
diff --git a/docs/user-guides/workspace-access/port-forwarding.md b/docs/user-guides/workspace-access/port-forwarding.md
@@ -53,10 +53,10 @@ For more examples, see `coder port-forward --help`.
 ## Dashboard
 
 > To enable port forwarding via the dashboard, Coder must be configured with a
-> [wildcard access URL](../../admin/setup.md#wildcard-access-url). If an access
-> URL is not specified, Coder will create
-> [a publicly accessible URL](../../admin/setup.md#tunnel) to reverse proxy the
-> deployment, and port forwarding will work.
+> [wildcard access URL](../../admin/setup/README.md#wildcard-access-url). If an
+> access URL is not specified, Coder will create
+> [a publicly accessible URL](../../admin/setup/README.md#tunnel) to reverse
+> proxy the deployment, and port forwarding will work.
 >
 > There is a
 > [DNS limitation](https://datatracker.ietf.org/doc/html/rfc1035#section-2.3.1)
