Skip to content

Commit 0d4c466

Browse files
lissy93lissy93
committed
Update docs
1 parent 8de1cf1 commit 0d4c466

10 files changed

Lines changed: 90 additions & 22 deletions

File tree

‎docs/authentication.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -272,6 +272,8 @@ volumes:
272272
keycloak-data:
273273
```
274274

275+
</details>
276+
275277
You should now be able to access the Keycloak web interface at `http://127.0.0.1:9100`, log in with your admin credentials above, and create a new password when prompted.
276278

277279
### 2. Setup Keycloak Users

‎docs/authentication/authelia-oidc.md‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Authelia Authentication for Dashy
1+
# Authelia
22

33
Dashy supports using [Authelia](https://www.authelia.com/) as its OIDC provider.
44

@@ -47,6 +47,8 @@ services:
4747
retries: 10
4848
```
4949
50+
</details>
51+
5052
The `config/` directory holds Authelia's `configuration.yml`, the user database, the OIDC signing key, and (for local testing) the TLS cert. Generate them in step 2.
5153

5254
---
@@ -369,7 +371,9 @@ Boot starts in [`src/main.js`](https://github.com/lissy93/dashy/blob/4.1.5/src/m
369371

370372
### Visual Overview
371373

372-
### End-to-end authentication flow
374+
<details>
375+
376+
<summary>End-to-end authentication flow</summary>
373377

374378
```mermaid
375379
sequenceDiagram
@@ -410,7 +414,11 @@ sequenceDiagram
410414
end
411415
```
412416

413-
### Server-side request handling
417+
</details>
418+
419+
<details>
420+
421+
<summary>Server-side request handling</summary>
414422

415423
```mermaid
416424
flowchart TD
@@ -439,3 +447,5 @@ flowchart TD
439447
classDef err fill:#fecaca,stroke:#dc2626,color:#7f1d1d
440448
classDef neutral fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
441449
```
450+
451+
</details>

‎docs/authentication/authentik.md‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Authentik Authentication for Dashy
1+
# Authentik
22

33
Dashy supports using [Authentik](https://goauthentik.io/) as its OIDC provider.
44

@@ -104,6 +104,8 @@ services:
104104
redis: {condition: service_healthy}
105105
```
106106
107+
</details>
108+
107109
Bring it up:
108110
109111
```bash
@@ -339,7 +341,9 @@ Boot starts in [`src/main.js`](https://github.com/lissy93/dashy/blob/4.1.5/src/m
339341

340342
### Visual Overview
341343

342-
### End-to-end authentication flow
344+
<details>
345+
346+
<summary>End-to-end authentication flow</summary>
343347

344348
```mermaid
345349
sequenceDiagram
@@ -380,7 +384,11 @@ sequenceDiagram
380384
end
381385
```
382386

383-
### Server-side request handling
387+
</details>
388+
389+
<details>
390+
391+
<summary>Server-side request handling</summary>
384392

385393
```mermaid
386394
flowchart TD
@@ -409,3 +417,5 @@ flowchart TD
409417
classDef err fill:#fecaca,stroke:#dc2626,color:#7f1d1d
410418
classDef neutral fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
411419
```
420+
421+
</details>

‎docs/authentication/built-in.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -350,3 +350,5 @@ sequenceDiagram
350350
Browser->>Dashy: GET /system-info<br />Authorization Bearer header set from cookie
351351
Dashy-->>Browser: 200 + system info
352352
```
353+
354+
</details>

‎docs/authentication/cloudflare-tunnel.md‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Cloudflare Tunnel + Access for Dashy
1+
# Cloudflare Tunnel
22

33
Dashy works well behind [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) with [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/policies/access/) doing auth at the edge. This is one of the most common ways to expose a homelab dashboard to the public internet without opening any inbound ports, without managing TLS, and without standing up your own identity provider.
44

@@ -102,6 +102,8 @@ services:
102102
start_period: 30s
103103
```
104104
105+
</details>
106+
105107
Set the token via env or a `.env` file alongside the compose:
106108

107109
```env
@@ -244,7 +246,9 @@ flowchart LR
244246
classDef err fill:#fecaca,stroke:#dc2626,color:#7f1d1d
245247
```
246248

247-
### End-to-end authentication flow
249+
<details>
250+
251+
<summary>End-to-end authentication flow</summary>
248252

249253
```mermaid
250254
sequenceDiagram
@@ -280,3 +284,5 @@ sequenceDiagram
280284
Dashy-->>Browser: { user: "alice@example.com" }
281285
Browser->>Browser: Match email to users[], set cookie,<br />render dashboard with right admin level
282286
```
287+
288+
</details>

‎docs/authentication/keycloak.md‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Keycloak Authentication for Dashy
1+
# Keycloak
22

33
Dashy supports using a [Keycloak](https://www.keycloak.org/) (V17+) authentication server.
44

@@ -88,6 +88,8 @@ volumes:
8888
keycloak-data:
8989
```
9090
91+
</details>
92+
9193
You should now be able to access the Keycloak web interface at `http://127.0.0.1:9100`, log in with your admin credentials above, and create a new password when prompted.
9294

9395
---
@@ -395,7 +397,9 @@ The server's admin check reads from the `id_token` only. Keycloak's default mapp
395397

396398
### Visual Overview
397399

398-
### End-to-end authentication flow
400+
<details>
401+
402+
<summary>End-to-end authentication flow</summary>
399403

400404
```mermaid
401405
sequenceDiagram
@@ -436,7 +440,11 @@ sequenceDiagram
436440
end
437441
```
438442

439-
### Server-side request handling
443+
</details>
444+
445+
<details>
446+
447+
<summary>Server-side request handling</summary>
440448

441449
```mermaid
442450
flowchart TD
@@ -465,3 +473,5 @@ flowchart TD
465473
classDef err fill:#fecaca,stroke:#dc2626,color:#7f1d1d
466474
classDef neutral fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
467475
```
476+
477+
</details>

‎docs/authentication/pocketid.md‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Pocket ID Authentication for Dashy
1+
# Pocket ID
22

33
Dashy supports using [Pocket ID](https://pocket-id.org/) as its OIDC provider.
44

@@ -52,6 +52,8 @@ services:
5252
start_period: 30s
5353
```
5454
55+
</details>
56+
5557
A few things worth understanding before you start:
5658
5759
- `APP_URL` is the URL the browser uses to reach Pocket ID. It must match exactly, since Pocket ID puts that value in the OIDC issuer, in cookie domains, and in the WebAuthn relying party
@@ -287,7 +289,9 @@ Boot starts in [`src/main.js`](https://github.com/lissy93/dashy/blob/4.1.5/src/m
287289

288290
### Visual Overview
289291

290-
### End-to-end authentication flow
292+
<details>
293+
294+
<summary>End-to-end authentication flow</summary>
291295

292296
```mermaid
293297
sequenceDiagram
@@ -328,7 +332,11 @@ sequenceDiagram
328332
end
329333
```
330334

331-
### Server-side request handling
335+
</details>
336+
337+
<details>
338+
339+
<summary>Server-side request handling</summary>
332340

333341
```mermaid
334342
flowchart TD
@@ -357,3 +365,5 @@ flowchart TD
357365
classDef err fill:#fecaca,stroke:#dc2626,color:#7f1d1d
358366
classDef neutral fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
359367
```
368+
369+
</details>

‎docs/authentication/tailscale.md‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Tailscale (and Headscale) for Dashy
1+
# Tailscale
22

33
[Tailscale](https://tailscale.com/) is a popular way to put Dashy on a private network you can reach from your phone, laptop, or any other device you've added to your tailnet, without exposing it to the public internet. With Tailscale Serve in front, requests reaching Dashy already carry the user's identity in HTTP headers, which plugs straight into Dashy's header auth for auto-login.
44

@@ -104,6 +104,8 @@ services:
104104
start_period: 30s
105105
```
106106
107+
</details>
108+
107109
`.env` next to the compose:
108110

109111
```env
@@ -305,7 +307,9 @@ flowchart LR
305307
classDef err fill:#fecaca,stroke:#dc2626,color:#7f1d1d
306308
```
307309

308-
### End-to-end authentication flow
310+
<details>
311+
312+
<summary>End-to-end authentication flow</summary>
309313

310314
```mermaid
311315
sequenceDiagram
@@ -330,3 +334,5 @@ sequenceDiagram
330334
Dashy-->>Device: { user: "alice@example.com" }
331335
Device->>Device: Match email to users[], set cookie,<br />render dashboard with right admin level
332336
```
337+
338+
</details>

‎docs/authentication/zitadel.md‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Zitadel Authentication for Dashy
1+
# Zitadel
22

33
Dashy supports using [Zitadel](https://zitadel.com/) as its OIDC provider.
44

@@ -86,6 +86,8 @@ services:
8686
condition: service_healthy
8787
```
8888
89+
</details>
90+
8991
The Zitadel external domain (`zitadel.lvh.me` above) must resolve to the host Zitadel listens on. `lvh.me` and its subdomains resolve to `127.0.0.1` everywhere, so no /etc/hosts edits needed locally.
9092

9193
For production:
@@ -365,7 +367,9 @@ Boot starts in [`src/main.js`](https://github.com/lissy93/dashy/blob/4.1.5/src/m
365367

366368
### Visual Overview
367369

368-
### End-to-end authentication flow
370+
<details>
371+
372+
<summary>End-to-end authentication flow</summary>
369373

370374
```mermaid
371375
sequenceDiagram
@@ -407,7 +411,11 @@ sequenceDiagram
407411
end
408412
```
409413

410-
### Server-side request handling
414+
</details>
415+
416+
<details>
417+
418+
<summary>Server-side request handling</summary>
411419

412420
```mermaid
413421
flowchart TD
@@ -436,3 +444,5 @@ flowchart TD
436444
classDef err fill:#fecaca,stroke:#dc2626,color:#7f1d1d
437445
classDef neutral fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
438446
```
447+
448+
</details>

‎docs/contributing.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,16 +25,18 @@ Don't feel any pressure to donate anything, as Dashy and my other projects will
2525

2626
Sponsoring will give you several perks - for $1 / £0.75 per month, you'll get a sponsor badge on your profile, be credited on the Dashy's readme, with a link to your website/ profile/ socials, get priority support, have your feature ideas implemented, plus lots more. For more info, see [@Lissy93's Sponsor Page](https://github.com/sponsors/Lissy93).
2727

28-
### You can also send a one-off small contribution using crypto
29-
30-
[![Donate with BTC](https://en.cryptobadges.io/badge/big/3853bSxupMjvxEYfwGDGAaLZhTKxB2vEVC)](https://en.cryptobadges.io/donate/3853bSxupMjvxEYfwGDGAaLZhTKxB2vEVC)[![Donate with Ethereum](https://en.cryptobadges.io/badge/big/0x0fc98cBf8bea932B4470C46C0FbE1ed1f6765017)](https://en.cryptobadges.io/donate/0x0fc98cBf8bea932B4470C46C0FbE1ed1f6765017)
28+
<details>
29+
<summary>You can also send a one-off small contribution using crypto</summary>
30+
[![Donate with BTC](https://en.cryptobadges.io/badge/big/3853bSxupMjvxEYfwGDGAaLZhTKxB2vEVC)](https://en.cryptobadges.io/donate/3853bSxupMjvxEYfwGDGAaLZhTKxB2vEVC)[![Donate with Ethereum](https://en.cryptobadges.io/badge/big/0x0fc98cBf8bea932B4470C46C0FbE1ed1f6765017)](https://en.cryptobadges.io/donate/0x0fc98cBf8bea932B4470C46C0FbE1ed1f6765017)
3131

3232
- **BTC**: `3853bSxupMjvxEYfwGDGAaLZhTKxB2vEVC`
3333
- **ETH**: `0x0fc98cBf8bea932B4470C46C0FbE1ed1f6765017` / `aliciasykes.eth`
3434
- **XMR**: `471KZdxb6N63aABR4WYwMRjTVkc1p1x7wGsUTEF7AMYzL8L94A5pCuYWkosgJQ5Ze8Y2PscVCGZFJa3hDPg6MaDq47GUm8r`
3535
- **LTC**: `MAuck6Ea1qaNihwKfXutkR1R6BorMth86H`
3636
- **ZEC**: `t1bw1SefijsXRDQVxC9w64XsRK8hBhtQohQ`
3737

38+
</details>
39+
3840
## Enable Anonymous Bug Reports
3941

4042
Bug reports helps me to discover bugs I was unaware of, and then fix them, in order to make Dashy more reliable long term. This is a simple, yet really helpful step you can take to help improve Dashy. [Sentry](https://github.com/getsentry/sentry) is an open source error tracking and performance monitoring tool, which enables the identification any errors which occur in the production app (only if you enable it).

0 commit comments

Comments
 (0)