An OIDC-protected index page for your homeserver.
1# Ladon
2
3
4
5A dead-simple index page for your homeserver, protected via OpenID Connect.
6
7## Deployment
8
9### Configuration
10
11#### KDL config for links
12
13Ladon relies on a single KDL file for displaying your links. Here's an example:
14
15```kdl
16group "Media" {
17 link "Plex" url="https://plex.mydomain.com"
18 link "Calibre CWA" url="https://calibre.mydomain.com"
19 link "Neko" url="https://<Tailscale IP>:8000"
20}
21
22group "Collaboration" {
23 link "Jira" url="https://jira.myworkdomain.com"
24 link "Confluence" url="https://docs.myworkdomain.com"
25}
26```
27
28The container image expects this file to be at `/data/links.kdl`, so you'll
29need to perform a volume binding at deploy time to ensure that file is
30available.
31
32#### Environment Variables
33
34After your config file, you'll need to set some environment variables for
35OpenID Connect. Bog-standard OAuth2 is not currently supported, since Ladon was
36mainly built with Pocket ID in mind.
37
38**All value are required.**
39
40| Variable Name | Description |
41| ------------- | ----------- |
42| `SESSION_SECRET` | 16 character string used to encrypt and sign session cookies. Make sure this is a randomly-generated value. |
43| `OIDC_CLIENT_ID` | OAuth2 client ID from your OIDC provider. |
44| `OIDC_CLIENT_SECRET` | OAuth2 client secret from your OIDC provider. |
45| `OIDC_ISSUER` | Issuer of your OIDC provider. In the case of Pocket ID, this will be simply your root domain with protocol. For other OpenID providers, this should be the start of your discovery URL, i.e. your domain minus the `/.well-known/openid-configuriation` at the end. |
46| `LADON_DOMAIN` | Domain where you are hosting Ladon. This is required for informing your OpenID provider of the correct callback URL. |
47
48### Starting Ladon
49
50With the config out of the way, you can deploy Ladon with your container
51runtime of choice.
52
53#### Docker Compose
54
55```yaml
56# docker-compose.yml
57
58services:
59 ladon:
60 image: ghcr.io/puregarlic/ladon
61 environment:
62 SESSION_SECRET: changemechangeme
63 OIDC_CLIENT_ID: changeme
64 OIDC_CLIENT_SECRET: qwfpjljujehnneharst
65 OIDC_ISSUER: https://oid.mydomain.com
66 LADON_DOMAIN: https://mydomain.com
67
68 # If you'd rather use a dotenv file, comment the above and uncomment below:
69 # env_file: ".env"
70
71 ports:
72 - "4000:4000"
73 volumes:
74 # In your data directory, make sure you've made `links.kdl`
75 - ./data:/data
76```
77
78#### Quadlet
79
80The below example assumes you want Ladon to start at boot, and that your
81environment variables are stored in a `.env` file located at `/my/environment/.env`.
82
83```ini
84[Unit]
85Description="Links index"
86
87[Container]
88AutoUpdate=registry
89Image=ghcr.io/puregarlic/ladon
90PublishPort=4000:4000tcp
91
92# Update these values for your deployment
93Volume=/my/data/path:/data
94EnvironmentFile=/my/environment/.env
95
96[Install]
97WantedBy=default.target
98```
99
100## Potentially-Asked Questions
101
102> Can I theme my page?
103
104Not at this time, but potentially in the future. The current theme is
105[Rose Pine](https://rosepinetheme.com/).
106
107> Can I add extra data to my links, e.g. descriptions?
108
109Not at this time again, but maybe in the future. If you really want, you can
110nest groups, but there's no significant difference in the formatting as a
111result of such.
112
113> Can I show certain links to certain users?
114
115Nope, but again, perhaps at a later time.
116
117> Why Ladon?
118
119According to [Wikipedia](https://en.wikipedia.org/wiki/Ladon_(mythology)),
120_Ladon was the serpent-like dragon that twined and twisted around the tree in
121the Garden of the Hesperides and guarded the golden apples._ The apps on
122your homeserver are kind of like golden apples (for hackers), so maybe this
123program can be the serpent-like dragon to guard them for you.
124
125At least on the surface, anyway. It's worth noting that Ladon is not a
126replacement for safely and securely configuring your applications. Ladon was
127only designed to make the lives of your friends and family easier without
128broadcasting an itemized list of potential vulnerabilities.