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