From 7a7c3f3864b0d7d1be3a0b622f6a70e86a6981d8 Mon Sep 17 00:00:00 2001
From: Huang Junxiang <wacmkxiaoyi@gmail.com>
Date: Fri, 30 May 2025 17:34:27 +0800
Subject: [PATCH] add usage of custom ca certificate with caddy (#530)

---
 manual/setup/caddy.md | 68 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)

diff --git a/manual/setup/caddy.md b/manual/setup/caddy.md
index 04d25d7e..e025ec30 100644
--- a/manual/setup/caddy.md
+++ b/manual/setup/caddy.md
@@ -5,9 +5,77 @@
 
 Caddy is a modern open source web server that mainly binds external traffic and internal services in [seafile docker](./overview.md). In addition to the advantages of traditional proxy components (e.g., *nginx*), Caddy also makes it easier for users to complete the acquisition and update of HTTPS certificates by providing simpler configurations. 
 
+## Engage HTTPS by caddy
+
+We provide two options for enabling HTTPS via *Caddy*, which mainly rely on The caddy docker proxy container from [Lucaslorentz](https://github.com/lucaslorentz/caddy-docker-proxy) supports dynamic configuration with labels:
+
+- With a automatically generated certificate
+- Using a custom (existing) certificate
+
+### With a automatically generated certificate
+
 To engage HTTPS, users only needs to correctly configure the following fields in `.env`:
 
 ```shell
 SEAFILE_SERVER_PROTOCOL=https
 SEAFILE_SERVER_HOSTNAME=example.com
 ```
+
+### Using a custom (existing) certificate
+
+With the `caddy.yml`, a default volume-mount is created: `/opt/seafile-caddy` (as you can change it by modifying `SEAFILE_CADDY_VOLUME` in `.env`). By convention you should provide your certificate & key files in the container host filesystem under `/opt/seafile-caddy/certs/` to make it available to caddy:
+
+```sh
+/opt/seafile-caddy/certs/
+├── cert.pem  # xxx.crt in some case
+├── key.pem # xxx.key in some case
+```
+
+!!! tip "Command to generate custom certificates"
+    With this command, you can generate your own custom certificates:
+
+    ```sh
+    cd /opt/seafile-caddy/certs
+    openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ./key.pem -out ./cert.pem
+    ```
+
+    **Please be aware that custom certicates can not be used for ip-adresses**
+
+Then modify `seafile-server.yml` to enable your custom certificate, by the way, we strongly recommend you to make a backup of `seafile-server.yml` before doing this:
+
+```sh
+cp seafile-server.yml seafile-server.yml.bak
+nano seafile-server.yml
+```
+
+and
+
+```yml
+services:
+  ...
+  seafile:
+    ...
+    volumes:
+      ...
+      # If you use a self-generated certificate, please add it to the Seafile server trusted directory (i.e. remove the comment symbol below)
+      # - "/opt/seafile-caddy/certs/cert.pem:/usr/local/share/ca-certificates/cert.crt"
+    labels:
+      caddy: ${SEAFILE_SERVER_HOSTNAME:?Variable is not set or empty} # leave this variables only
+      caddy.tls: "/data/caddy/certs/cert.pem /data/caddy/certs/key.pem"
+      ...
+```
+
+!!! warning "DNS resolution must work inside the container"
+
+    If you're using a ***non-public url*** like `my-custom-setup.local`, you have to make sure, that the docker container can resolve this DNS query. If you don't run your own DNS servers, you have to add extras_hosts to your `.yml` file.
+
+## Modify `seahub_settings.py` and restart the server
+
+If you enabled HTTPS during initial deployment, you can skip this section (the HTTPS will take effect with the first time startup).
+
+1. Modify `seahub_settings.py` and change all `http://seafile.example.com` to `https://seafile.example.com`.
+2. Restart the server:
+
+```sh
+docker compose down && docker compose up -d
+```