Skip to content

Commit 5f1df56

Browse files
johnstcnjohnstcn
authored
chore: add warning about database availability (coder#1096)
1 parent 344c4a6 commit 5f1df56

File tree

1 file changed

+117
-110
lines changed

1 file changed

+117
-110
lines changed

‎setup/installation.md

Lines changed: 117 additions & 110 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,11 @@ Install the following dependencies if you haven't already:
1717
[PostgreSQL](https://www.postgresql.org/docs/12/admin.html) instance to store
1818
data, including workspace information and session tokens.
1919

20+
> ⚠️ Coder requires a database in order to function. If Coder's database becomes
21+
> unavailable, Coder will become unavailable. Ensure that your Coder database is
22+
> monitored for common issues such as available connections, disk usage, and so
23+
> on.
24+
2025
## For public sector deployments
2126

2227
Users with public sector deployments may need to obtain Coder's installation
@@ -31,7 +36,8 @@ resources from
3136
3237
## Install Coder
3338

34-
1. Create the Coder [namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/):
39+
1. Create the Coder
40+
[namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/):
3541

3642
```console
3743
kubectl create namespace coder
@@ -90,142 +96,143 @@ resources from
9096
## Set the super admin password
9197

9298
**Optional**: change the admin user password by updating `values.yaml` as
93-
follows:
94-
95-
```yaml
96-
superAdmin:
97-
# Options for configuring the secret used to specify the password for the
98-
# built-in super admin account.
99-
passwordSecret:
100-
# coderd.superAdmin.passwordSecret.name -- Name of a secret that should
101-
# be used to determine the password for the super admin account. The
102-
# password should be contained in the field `password`, or the manually
103-
# specified one.
104-
name: ""
105-
# coderd.superAdmin.passwordSecret.key -- The key of the secret that
106-
# contains the super admin password.
107-
key: "password"
108-
```
99+
follows:
100+
101+
```yaml
102+
superAdmin:
103+
# Options for configuring the secret used to specify the password for the
104+
# built-in super admin account.
105+
passwordSecret:
106+
# coderd.superAdmin.passwordSecret.name -- Name of a secret that should
107+
# be used to determine the password for the super admin account. The
108+
# password should be contained in the field `password`, or the manually
109+
# specified one.
110+
name: ""
111+
# coderd.superAdmin.passwordSecret.key -- The key of the secret that
112+
# contains the super admin password.
113+
key: "password"
114+
```
109115
110116
## Connect an external database
111117
112-
**Optional**: To configure an externally hosted database, set the following
113-
in `values.yaml`:
114-
115-
> Ensure that you have superuser privileges to your PostgreSQL database.
116-
117-
```yaml
118-
postgres:
119-
default:
120-
enable: false
121-
host: HOST_ADDRESS
122-
port: PORT_NUMBER
123-
user: YOUR_USER_NAME
124-
database: YOUR_DATABASE
125-
passwordSecret: secret-name
126-
sslMode: require
127-
```
128-
129-
a. To create the `passwordSecret`, run:
130-
131-
```console
132-
kubectl create secret generic <NAME> --from-literal="password=UserDefinedPassword"
133-
```
134-
135-
> Put a space before the command to prevent it from being saved in your shell
136-
> history.
137-
>
138-
> Running this command could potentially expose your database password to
139-
> other users on your system through `/proc`. If this is a concern, you can
140-
> use `--from-file=password=/dev/stdin` instead of `--from-literal=...` to
141-
> enter your password and press `Ctrl+D` when you're done to submit it.
142-
>
143-
> Ensure that there are no trailing white spaces in your password secret.
144-
145-
For more detailed configuration instructions,
146-
[see our PostgreSQL setup guide](../guides/deployments/postgres.md).
147-
Alternatively, see our [guide on connecting to AWS RDS via IAM credentials](/guides/admin/awsrds.md).
118+
**Optional**: To configure an externally hosted database, set the following in
119+
`values.yaml`:
120+
121+
> Ensure that you have superuser privileges to your PostgreSQL database.
122+
123+
```yaml
124+
postgres:
125+
default:
126+
enable: false
127+
host: HOST_ADDRESS
128+
port: PORT_NUMBER
129+
user: YOUR_USER_NAME
130+
database: YOUR_DATABASE
131+
passwordSecret: secret-name
132+
sslMode: require
133+
```
134+
135+
a. To create the `passwordSecret`, run:
136+
137+
```console
138+
kubectl create secret generic <NAME> --from-literal="password=UserDefinedPassword"
139+
```
140+
141+
> Put a space before the command to prevent it from being saved in your shell
142+
> history.
143+
>
144+
> Running this command could potentially expose your database password to other
145+
> users on your system through `/proc`. If this is a concern, you can use
146+
> `--from-file=password=/dev/stdin` instead of `--from-literal=...` to enter
147+
> your password and press `Ctrl+D` when you're done to submit it.
148+
>
149+
> Ensure that there are no trailing white spaces in your password secret.
150+
151+
For more detailed configuration instructions,
152+
[see our PostgreSQL setup guide](../guides/deployments/postgres.md).
153+
Alternatively, see our
154+
[guide on connecting to AWS RDS via IAM credentials](/guides/admin/awsrds.md).
148155

149156
## Enable dev URLs
150157

151158
**Optional**: Enable dev URL usage.
152-
[You must provide a wildcard domain in the Helm chart](../admin/devurls.md).
159+
[You must provide a wildcard domain in the Helm chart](../admin/devurls.md).
153160

154-
```yaml
155-
coderd:
156-
devurlsHost: "*.my-custom-domain.io"
157-
```
161+
```yaml
162+
coderd:
163+
devurlsHost: "*.my-custom-domain.io"
164+
```
158165

159166
## Enable TLS
160167

161168
**Optional:** To set up TLS:
162169

163-
a. You will need to create a TLS secret. To do so, run the following with the
164-
`.pem` files provided by your certificate:
170+
a. You will need to create a TLS secret. To do so, run the following with the
171+
`.pem` files provided by your certificate:
165172

166-
```console
167-
kubectl create secret tls tls-secret --key key.pem --cert cert.pem
168-
```
173+
```console
174+
kubectl create secret tls tls-secret --key key.pem --cert cert.pem
175+
```
169176

170-
> If your certificate provider does not provide `.pem` files, then you may
171-
> need to attach the certificate to the LoadBalancer manually.
177+
> If your certificate provider does not provide `.pem` files, then you may need
178+
> to attach the certificate to the LoadBalancer manually.
172179

173-
b. Attach the secret to the `coderd` service by setting the following values:
180+
b. Attach the secret to the `coderd` service by setting the following values:
174181

175-
```yaml
176-
coderd:
177-
tls:
178-
hostSecretName: <tls-secret>
179-
devurlsHostSecretName: <tls-secret>
180-
```
182+
```yaml
183+
coderd:
184+
tls:
185+
hostSecretName: <tls-secret>
186+
devurlsHostSecretName: <tls-secret>
187+
```
181188

182189
## Set up an ingress controller
183190

184191
**Optional:** If you cannot use a load balancer, you may need an ingress
185-
controller. To configure one with Coder, set the following in `values.yaml`:
186-
187-
> We assume that you already have an ingress controller installed in your
188-
> cluster.
189-
190-
```yaml
191-
coderd:
192-
devurlsHost: "*.devurls.coderhost.com"
193-
serviceSpec:
194-
# The Ingress will route traffic to the internal ClusterIP.
195-
type: ClusterIP
196-
externalTrafficPolicy: ""
197-
tls:
198-
hostSecretName: <tls-secret>
199-
devurlsHostSecretName: <tls-secret>
200-
ingress:
201-
enable: true
202-
# Hostname to use for routing decisions
203-
host: "coder.coderhost.com"
204-
# Custom annotations to apply to the resulting Ingress object
205-
# This is useful for configuring other controllers in the cluster
206-
# such as cert-manager or the ingress controller
207-
annotations: {}
208-
```
192+
controller. To configure one with Coder, set the following in `values.yaml`:
193+
194+
> We assume that you already have an ingress controller installed in your
195+
> cluster.
196+
197+
```yaml
198+
coderd:
199+
devurlsHost: "*.devurls.coderhost.com"
200+
serviceSpec:
201+
# The Ingress will route traffic to the internal ClusterIP.
202+
type: ClusterIP
203+
externalTrafficPolicy: ""
204+
tls:
205+
hostSecretName: <tls-secret>
206+
devurlsHostSecretName: <tls-secret>
207+
ingress:
208+
enable: true
209+
# Hostname to use for routing decisions
210+
host: "coder.coderhost.com"
211+
# Custom annotations to apply to the resulting Ingress object
212+
# This is useful for configuring other controllers in the cluster
213+
# such as cert-manager or the ingress controller
214+
annotations: {}
215+
```
209216

210217
## Configure a proxy
211218

212-
**Optional:** To have Coder initiate outbound connections via a proxy, set
213-
the following (applicable) values:
219+
**Optional:** To have Coder initiate outbound connections via a proxy, set the
220+
following (applicable) values:
214221

215-
```yaml
216-
coderd:
217-
proxy:
218-
http: ""
219-
https: ""
220-
exempt: "cluster.local"
221-
```
222+
```yaml
223+
coderd:
224+
proxy:
225+
http: ""
226+
https: ""
227+
exempt: "cluster.local"
228+
```
222229

223-
Once you've implemented all of the changes in `values.yaml`, upgrade Coder
224-
with the following command:
230+
Once you've implemented all of the changes in `values.yaml`, upgrade Coder with
231+
the following command:
225232

226-
```console
227-
helm upgrade coder coder/coder --namespace coder --version=<VERSION> -f values.yaml
228-
```
233+
```console
234+
helm upgrade coder coder/coder --namespace coder --version=<VERSION> -f values.yaml
235+
```
229236

230237
## Logging
231238

0 commit comments

Comments
 (0)