From 883a649210308142fc7c62827bea4e107f6a9ad7 Mon Sep 17 00:00:00 2001
From: itskovacs <itskovacs@proton.me>
Date: Wed, 23 Jul 2025 18:47:09 +0200
Subject: [PATCH] :memo: Add config documentation

---
 README.md      |   2 +
 docs/config.md | 104 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 106 insertions(+)
 create mode 100644 docs/config.md

diff --git a/README.md b/README.md
index 17e1f1e..4cae9b3 100644
--- a/README.md
+++ b/README.md
@@ -53,6 +53,8 @@ docker pull ghcr.io/itskovacs/trip:1
 docker run -p 8080:8000 -v ./storage:/app/storage ghcr.io/itskovacs/trip:1
 ```
 
+If you want to configure OIDC authentication or other settings, see [config docs](https://github.com/itskovacs/trip/tree/main/docs/config.md).
+
 <br>
 
 ## 📸 Demo <a name = "demo"></a>
diff --git a/docs/config.md b/docs/config.md
new file mode 100644
index 0000000..006bfca
--- /dev/null
+++ b/docs/config.md
@@ -0,0 +1,104 @@
+
+You can modify the configuration by setting values in the `storage/config.yml` file.
+
+> [!NOTE]
+> After a `config.yml` edit, you must restart the container for the changes to take effect.
+
+
+### Change Token duration
+
+To modify the token lifespan, edit `ACCESS_TOKEN_EXPIRE_MINUTES` for the *Access Token* and `REFRESH_TOKEN_EXPIRE_MINUTES` for the *Refresh Token*.
+By default, the *Refresh Token* expires after `1440` minutes (24 hours), and the *Access Token* after `30` minutes.
+
+```yaml
+ACCESS_TOKEN_EXPIRE_MINUTES=30
+REFRESH_TOKEN_EXPIRE_MINUTES=1440
+```
+
+
+### Configure OIDC Auth
+
+> [!TIP]
+> By default, `OIDC_PROTOCOL` is `https` and `OIDC_REALM` is `master`
+
+```yaml
+OIDC_CLIENT_ID="your-client-id"
+OIDC_CLIENT_SECRET="your-client-secret"
+OIDC_HOST="sso.yourdomain.lan"
+OIDC_REDIRECT_URI="your-redirect-uri"
+
+# Optional,
+OIDC_PROTOCOL="https"
+OIDC_REALM="master"
+```
+
+> [!CAUTION]
+> You might face a `SSLError` / `CERTIFICATE_VERIFY_FAILED` if you use `https` protocol. I invite you to check [Troubleshoot SSL Error](#tbshoot-cert) section
+
+
+### Disable registration
+
+The key `REGISTER_ENABLE` can be configured to `false` if you want to disable registration.
+
+**To disable**, add this in your `config.yml`:
+```yaml
+REGISTER_ENABLE=false
+```
+
+### Modify Image default size
+
+By default, images are resized to `500px` for places and `600px` for trips. You can override these default values by setting them in the `config.yml`:
+
+> [!CAUTION]
+> Higher numbers will lead to higher disk usage.
+
+```yaml
+PLACE_IMAGE_SIZE=500
+TRIP_IMAGE_SIZE=600
+```
+
+### Troubleshoot SSL Error / Certificate <a name = "tbshoot-cert"></a>
+
+One way to check if you're concerned by this is simply doing the following and checking the result:
+```dockerfile
+$ docker run --rm -it ghcr.io/itskovacs/trip:1 /bin/bash
+$ python3
+>>> import httpx
+>>> resp = httpx.get("https://your-keycloak-host/")
+```
+
+In case you're facing this issue, it's likely due to the fact that the container does not trust you custom certificate.
+
+To fix this, I recommend you to build your own image with the certificate, based on the latest package.
+
+Pull the latest TRIP image.
+```bash
+docker pull ghcr.io/itskovacs/trip:1
+```
+
+Create a file named `Dockerfile` in your TRIP directory to copy your CA certificate in a custom TRIP image.
+```
+# Use latest TRIP image
+FROM ghcr.io/itskovacs/trip:1
+
+# Copy your CA certificate file in the image. Replace myCA.crt with your certificate name.
+COPY myCA.crt /usr/local/share/ca-certificates/
+RUN update-ca-certificates
+```
+
+Then, simply build the image:
+```bash
+docker build -t trip-custom-cert .
+```
+
+When you want to run TRIP, you just have to use your newly created image `trip-custom-cert`:
+```bash
+docker run -p 8080:8000 -v ./storage:/app/storage trip-custom-cert
+```
+
+> [!IMPORTANT]
+> On TRIP update, simply re-create your custom image:
+> ```
+> docker pull ghcr.io/itskovacs/trip:1
+> docker build -t trip-custom-cert .
+> ```
\ No newline at end of file