Merge pull request #427 from haiwen/update_12.0_cluster

Update 12.0 cluster

Author: freeplant

manual/docker/cluster/env

@@ -34,5 +34,4 @@ INIT_S3_AWS_REGION=us-east-1
 INIT_S3_HOST=s3.us-east-1.amazonaws.com
 INIT_S3_USE_HTTPS=true
 
-
 JWT_PRIVATE_KEY=<your jwt private key>

manual/setup/cluster_deploy_with_docker.md

@@ -4,12 +4,16 @@ Seafile Docker cluster deployment requires "sticky session" settings in the load
 
 ## Environment
 
+!!! note "Prerequisites"
+
+    - We assume you have already deployed ***memcache***, ***MariaDB***, ***ElasticSearch*** in separate machines and use ***S3*** like object storage. 
+
+    - Usually, each node of Seafile Cluster should have at least **2 cores** and **2G memory**. If the above services are deployed together with a node in the Seafile cluster, we recommend that you prepare **4 cores** and **4G memory** for the node (especially if ElasticSearch is also deployed on the node)
+
 System: Ubuntu 24.04
 
 Seafile Server: 2 frontend nodes, 1 backend node
 
-We assume you have already deployed memcache, MariaDB, ElasticSearch in separate machines and use S3 like object storage.
-
 ## Deploy Seafile service
 
 ### Deploy the first Seafile frontend node
@@ -22,13 +26,13 @@ We assume you have already deployed memcache, MariaDB, ElasticSearch in separate
 
 2. Pulling Seafile image
 
+    !!! tip
+        Since v12.0, Seafile PE versions are hosted on DockerHub and does not require username and password to download.
+
     ```bash
     docker pull seafileltd/seafile-pro-mc:12.0-latest
     ```
 
-    !!! note
-        Since v12.0, Seafile PE versions are hosted on DockerHub and does not require username and password to download.
-
 3. Download the `seafile-server.yml` and `.env`
 
     ```sh
@@ -45,8 +49,7 @@ We assume you have already deployed memcache, MariaDB, ElasticSearch in separate
 5. Start the Seafile docker
 
     ```sh
-    $ cd /opt/seafile
-    $ docker compose up -d
+    docker compose up -d
     ```
 
     !!! success "Cluster init mode"
@@ -155,12 +158,22 @@ We assume you have already deployed memcache, MariaDB, ElasticSearch in separate
 
 ### Deploy the others Seafile frontend nodes
 
-You can directly copy all the directories generated by the first frontend node, including the Docker-compose files (e.g., `seafile-server.yml`, `.env`) and modified configuration files, and then start the seafile docker container:
+1. Create the mount directory
 
-```sh
-docker compose down
-docker compose up -d
-```
+    ```
+    $ mkdir -p /opt/seafile/shared
+
+    ```
+
+2. Pull Seafile image
+
+3. Copy `seafile-server.yml`, `.env `and configuration files from the first frontend node
+
+4. Start the service
+
+    ```sh
+    docker compose up -d
+    ```
 
 ### Deploy seafile backend node
 
@@ -171,7 +184,7 @@ docker compose up -d
 
     ```
 
-2. Pulling Seafile image
+2. Pull Seafile image
 
 3. Copy `seafile-server.yml`, `.env` and configuration files from frontend node
 
@@ -217,7 +230,67 @@ docker compose up -d
 
 ## Deploy load balance (Optional)
 
-### Install HAproxy and Keepalived services
+Generally speaking, in order to better access the Seafile service, we recommend that you use a load balancing service to access the Seafile cluster and bind your domain name (such as `seafile.cluster.com`) to the load balancing service. Usually, you can use:
+
+- Cloud service provider's load balancing service
+- Deploy your own load balancing service, our document will give two of common load balance services:
+
+    - Nginx
+    - HAproxy
+
+### Nginx
+
+1. Install Nginx in the host if you would like to deploy load balance service
+
+```sh
+sudo apt update
+sudo apt install nginx
+```
+
+2. Create the configurations file for Seafile cluster
+
+```sh
+sudo nano /etc/nginx/sites-available/seafile-cluster
+```
+
+and, add the following contents into this file:
+
+```nginx
+upstream seafile_cluster {
+    server <IP: your frontend node 1>:80;
+    server <IP: your frontend node 2>:80;
+    ...
+}
+
+server {
+    listen 80;
+    server_name <your domain>;
+
+    location / {
+        proxy_pass http://seafile_cluster;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        http_502 http_503 http_504;
+    }
+}
+```
+
+3. Link the configurations file to `sites-enabled` directory:
+
+```sh
+sudo ln -s /etc/nginx/sites-available/seafile-cluster /etc/nginx/sites-enabled/
+```
+
+4. Test and enable configuration
+
+```sh
+sudo nginx -t
+sudo nginx -s reload
+```
+
+### HAproxy and Keepalived services
 
 Execute the following commands on the two Seafile frontend servers:
 
@@ -341,6 +414,10 @@ $ systemctl enable --now keepalived
 
 So far, Seafile cluster has been deployed.
 
+## HTTPS
+
+You can engaged HTTPS in your load balance service, as you can use certificates manager (e.g., [Certbot](https://certbot.eff.org)) to acquire and enable HTTPS to your Seafile cluster. You have to modify the relative URLs from the prefix `http://` to `https://` in `seahub_settings.py` and `.env`, after enabling HTTPS.
+
 ## (Optional) Deploy SeaDoc server
 
 You can follow [here](../extension/setup_seadoc.md) to deploy SeaDoc server. And then modify `SEADOC_SERVER_URL` in your `.env` file

manual/upgrade/upgrade_a_cluster_docker.md

@@ -16,24 +16,136 @@ Seafile adds new features in major and minor versions. It is likely that some da
 In general, to upgrade a cluster, you need:
 
 1. Download the new image, stop the old docker container, modify the Seafile image version in docker-compose.yml to the new version. Start with docker compose up.
-2. Run the upgrade script in container (for example, /opt/seafile/seafile-server-latest/upgrade/upgrade_10_0_11_0.sh) in one frontend node
+2. Run the upgrade script in container (for example, `/opt/seafile/seafile-server-latest/upgrade/upgrade_x_x_x_x.sh`) in one frontend node
 3. Update configuration files at each node according to the documentation for each version
 4. Delete old search index in the backend node if needed
 
-## Maintanence upgrade
+## Upgrade a cluster from Seafile 11 to 12
 
-Maintanence upgrade only needs to download the new image, stop the old docker container, modify the Seafile image version in docker-compose.yml to the new version. Start with docker compose up.
+1. Stop the seafile service in all nodes
 
-## Upgrade from 10.0 to 11.0
+    ```sh
+    docker compose down
+    ```
 
-Migrate your configuration for LDAP and OAuth according to [here](upgrade_notes_for_11.0.x.md)
+2. Download the docker-compose files for *Seafile 12*
 
-## Upgrade from 9.0 to 10.0
+    ```sh
+    wget -O .env https://manual.seafile.com/12.0/docker/cluster/env
+    wget https://manual.seafile.com/12.0/docker/cluster/seafile-server.yml
+    ```
 
-If you are using with ElasticSearch, SAML SSO and storage backend features, follow the upgrading manual on how to update the configuration for [these features](upgrade_notes_for_10.0.x.md).
+3. Modify `.env`:
 
-If you want to use the new notification server and rate control (pro edition only), please refer to the [upgrading manual](upgrade_notes_for_10.0.x.md).
+    - Generate a JWT key
 
-## Upgrade from 8.0 to 9.0
+        ```sh
+        pwgen -s 40 1
 
-If you are using with ElasticSearch, follow the upgrading manual on how to [update the configuration](upgrade_notes_for_9.0.x.md).
+        # e.g., EkosWcXonPCrpPE9CFsnyQLLPqoPhSJZaqA3JMFw
+        ```
+
+    - Fill up the following field according to your configurations using in *Seafile 11*:
+
+        ```sh
+        SEAFILE_SERVER_HOSTNAME=<your loadbalance's host>
+        SEAFILE_SERVER_PROTOCOL=https # or http
+        SEAFILE_MYSQL_DB_HOST=<your mysql host>
+        SEAFILE_MYSQL_DB_USER=seafile # if you don't use `seafile` as your Seafile server's account, please correct it
+        SEAFILE_MYSQL_DB_PASSWORD=<your mysql password for user `seafile`>
+        JWT_PRIVATE_KEY=<your JWT key generated in Sec. 3.1>
+        ```
+
+        !!! tip "Remove the variables using in Cluster initialization"
+            Since Seafile has been initialized in Seafile 11, the variables related to Seafile cluster initialization can be removed from `.env`:
+
+            - INIT_SEAFILE_MYSQL_ROOT_PASSWORD
+            - CLUSTER_INIT_MODE
+            - CLUSTER_INIT_MEMCACHED_HOST
+            - CLUSTER_INIT_ES_HOST
+            - CLUSTER_INIT_ES_PORT
+            - INIT_S3_STORAGE_BACKEND_CONFIG
+            - INIT_S3_COMMIT_BUCKET
+            - INIT_S3_FS_BUCKET
+            - INIT_S3_BLOCK_BUCKET
+            - INIT_S3_KEY_ID
+            - INIT_S3_USE_V4_SIGNATURE
+            - INIT_S3_SECRET_KEY
+            - INIT_S3_AWS_REGION
+            - INIT_S3_HOST
+            - INIT_S3_USE_HTTPS
+
+4. Start the Seafile in a node
+
+    !!! note
+        According to this upgrade document, a **frontend** service will be started here. If you plan to use this node as a backend node, you need to modify this item in `.env` and set it to `backend`:
+
+        ```sh
+        CLUSTER_MODE=backend
+        ```
+
+    ```sh
+    docker compose up -d
+    ```
+
+5. Upgrade Seafile
+
+    ```sh
+    docker exec -it seafile bash
+    # enter the container `seafile`
+
+    # stop servers
+    cd /opt/seafile/seafile-server-latest
+    ./seafile.sh stop
+    ./seahub.sh stop
+    
+    # upgrade seafile
+    cd upgrade
+    ./upgrade_11.0_12.0.sh
+    ```
+
+    !!! success
+        After upgrading the Seafile, you can see the following messages in your console:
+
+        ```
+        Updating seafile/seahub database ...
+
+        [INFO] You are using MySQL
+        [INFO] updating seafile database...
+        [INFO] updating seahub database...
+        [INFO] updating seafevents database...
+        Done
+
+        migrating avatars ...
+
+        Done
+
+        updating /opt/seafile/seafile-server-latest symbolic link to /opt/seafile/seafile-pro-server-12.0.6 ...
+
+
+
+        -----------------------------------------------------------------
+        Upgraded your seafile server successfully.
+        -----------------------------------------------------------------
+        ```
+
+        Then you can exit the container by `exit`
+
+6. Restart current node
+
+    ```sh
+        docker compose down
+        docker compose up -d
+    ```
+
+    !!! tip 
+        - You can use `docker logs -f seafile` to check whether the current node service is running normally
+
+7. Operations for other nodes
+
+    - Download and modify `.env` similar to the first node (for backend node, you should set `CLUSTER_MODE=backend`)
+
+    - Start the Seafile server:
+        ```sh
+        docker compose up -d
+        ```