Author	Nejat Hakan
eMail	nejat.hakan@outlook.de
PayPal Me	https://paypal.me/nejathakan

Cloud Sync & Storage Seafile

Introduction What is Seafile and Why Self-Host It

Welcome to the world of self-hosted cloud storage with Seafile! In an era where data privacy and control are paramount, relying solely on third-party cloud providers like Google Drive, Dropbox, or OneDrive might not align with everyone's needs or principles. Self-hosting empowers you to reclaim ownership of your digital life, and Seafile stands out as a robust, high-performance, and reliable open-source solution for file synchronization and sharing.

What is Seafile?

Seafile is an open-source, enterprise-grade file sync and share platform designed with a focus on reliability, performance, and data privacy. Unlike simple file storage systems, Seafile incorporates several sophisticated features:

Block-Level Storage: At its core, Seafile uses a data model inspired by Git. Files are broken down into smaller blocks (chunks). When you modify a file, only the changed blocks are transferred and stored as new versions. This makes synchronization incredibly efficient, especially for large files or small changes, saving bandwidth and storage space. It also enables robust versioning and snapshot capabilities.
Libraries: Seafile organizes data into "Libraries." Think of a library as a top-level folder or a project workspace. Each library has its own history and can be independently synced or shared. Libraries can also be encrypted for enhanced security.
Cross-Platform Clients: Seafile provides native desktop clients for Windows, macOS, and Linux, as well as mobile apps for iOS and Android. It also offers a full-featured web interface (Seahub). This ensures seamless access to your files from virtually any device.
Performance: Written primarily in C (server core) and Python (web front-end Seahub), Seafile is known for its speed and efficiency, capable of handling large numbers of files and concurrent users.
Sharing and Collaboration: Seafile offers flexible sharing options, including sharing with other Seafile users, creating public upload/download links (optionally password-protected or with expiration dates), and group collaboration features.
File Locking: Prevents conflicts when multiple users might edit the same file simultaneously (especially useful for non-mergeable file types like Office documents).
Markdown & WYSIWYG Editor: Includes built-in support for editing Markdown files directly within the web interface, facilitating documentation and note-taking.
Extensibility: Can be integrated with other services like LDAP/Active Directory for authentication, and office suites like ONLYOFFICE or Collabora Online for online document editing.

Why Self-Host Seafile?

Choosing to self-host Seafile instead of using commercial cloud services offers significant advantages, particularly appealing to university students, researchers, developers, and privacy-conscious individuals:

Data Ownership and Control: This is the primary driver. When you self-host, your data resides on your server (whether it's a physical machine at home, a rented VPS, or a university server). You control who has access, how it's backed up, and where it's geographically located. You are not subject to the terms of service, privacy policies, or potential data scanning practices of third-party providers.
Privacy: Your files are not analyzed for advertising purposes or accessed by third-party employees unless you explicitly grant permission or are legally compelled under specific jurisdictions (which you control). Client-side library encryption adds another layer of protection, making data unreadable even to the server administrator without the password.
Cost-Effectiveness: While commercial cloud storage often starts cheap or free, costs can escalate quickly with larger storage needs or multiple users. Self-hosting involves upfront or ongoing server costs (hardware, electricity, or VPS rental), but it can be significantly cheaper in the long run, especially for terabytes of data. Storage costs on rented servers are often much lower per GB than premium cloud storage tiers.
Customization and Integration: Self-hosting gives you the freedom to configure Seafile precisely to your needs. You can integrate it with existing authentication systems (like university LDAP), set custom quotas, tweak performance parameters, and integrate online document editors.
Learning Opportunity: Setting up and managing a Seafile server is an excellent practical learning experience in server administration, networking, security, database management, and potentially containerization (Docker). This is invaluable for students in computer science or related fields.
No Arbitrary Limits (Beyond Your Resources): You are not bound by arbitrary file size limits (beyond filesystem/OS limits), bandwidth caps (beyond your server's connection), or feature restrictions imposed by service tiers. Your limits are defined by your server's hardware and network capacity.
Enhanced Security Potential: While self-hosting requires you to manage security, it also allows you to implement stricter security measures than might be available or enforced by default on public clouds (e.g., specific firewall rules, intrusion detection systems, mandatory 2FA).

Self-hosting isn't without its responsibilities – you are responsible for installation, configuration, maintenance, backups, and security. However, for those willing to invest the time, the benefits of control, privacy, and customization offered by self-hosting Seafile are substantial. This guide will walk you through the process, from basic setup to advanced configurations.

Basic

This section covers the fundamental knowledge and steps required to get a basic Seafile instance up and running using the most straightforward methods. It's designed for beginners or those wanting a quick setup.

1. Core Seafile Concepts Explained

Before diving into installation, it's crucial to understand the fundamental building blocks and terminology used within the Seafile ecosystem. Grasping these concepts will make configuration, usage, and troubleshooting much easier.

Libraries (Repositories)

Definition: A Library is the primary unit of data organization in Seafile. Conceptually, it's like a top-level folder or a root directory for a specific project, department, or personal collection of files.
Technical Underpinnings: Under the hood, each library functions similarly to a Git repository but is optimized for large binary files and synchronization rather than code. It maintains a history of all changes made to the files within it.
Versioning: Every change (file addition, modification, deletion) creates a new "commit" or snapshot of the library's state. This allows you to revert files or the entire library to any previous point in time. This history is stored efficiently using the block-based storage mechanism.
Synchronization: You choose which libraries you want to synchronize with your desktop client. You don't have to sync everything.
Sharing: Libraries are the primary objects you share with other users or groups. You can grant read-only or read-write permissions.
Encryption: Libraries can be created with client-side encryption. This means you set a password when creating the library. The files are encrypted on your computer before being sent to the server, using this password. The server administrator cannot access the content of encrypted libraries without the password. Crucially, if you forget the password for an encrypted library, the data is irrecoverably lost.

Synchronization Mechanisms

Seafile employs sophisticated synchronization logic to ensure data consistency across devices while optimizing for performance and bandwidth.

Delta Sync (Block-Level): As mentioned, Seafile breaks files into blocks. When a file is modified, the Seafile client calculates which blocks have changed. Only these changed blocks are transferred to the server and then downloaded by other connected clients. This is highly efficient for large files where only small parts are modified (e.g., virtual machine images, large documents, databases).
Two-Way Sync: Changes made on any connected client (desktop, mobile, web) or directly on the server are propagated to all other clients syncing that library.
Conflict Resolution: If the same file is modified simultaneously on two different clients before either can sync, Seafile detects the conflict. It usually saves both versions, renaming one as a "conflicting copy," allowing the user to manually merge or choose the correct version.
Selective Sync (Desktop Client): While you sync entire libraries, advanced desktop client features (covered later) allow you to download only specific sub-folders within a synced library to save local disk space, while still browsing the full structure.

Seafile provides flexible ways to share your files and folders, both internally and externally.

Sharing Libraries:
- To Users: You can share a library directly with another registered Seafile user on the same server, granting either read-only or read-write access.
- To Groups: You can create groups of users (e.g., "Project Team," "Study Group") and share libraries with the entire group, simplifying permission management.
Sharing Sub-folders: You are not limited to sharing entire libraries. You can also share specific sub-folders within a library with users or groups. This allows for more granular control over access.
Sharing Links (Public Links):
- Download Links: You can generate a unique, public URL for a file or folder. Anyone with this link can download the content, even if they don't have a Seafile account. These links can be password-protected and set to expire after a certain time or number of downloads.
- Upload Links: You can generate a unique, public URL for a folder. Anyone with this link can upload files into that folder, even without a Seafile account. This is useful for collecting files from external collaborators. Upload links can also have password protection and expiration dates.

User Roles and Administration

Regular User: Can create libraries, sync files, share their own libraries/folders, and access items shared with them.
Administrator: Has full control over the Seafile instance. Can manage users (create, delete, set quotas), manage libraries (view metadata, transfer ownership, delete), configure system settings, view logs, and perform maintenance. By default, the first user created during setup becomes an administrator. Additional administrators can be designated.

Understanding these core concepts – Libraries as versioned repositories, efficient block-level sync, and flexible sharing options – provides a solid foundation for effectively using and managing your self-hosted Seafile instance.

Workshop Understanding Core Concepts

Objective: To explore the Seafile Web UI (Seahub) and practically interact with Libraries, Versioning, and Sharing, reinforcing the theoretical concepts.

Prerequisites: A running Seafile instance (we'll set one up in the next section, but you could use the official Seafile demo server demo.seafile.com for this specific workshop if needed, though creating your own is better for the full experience). Access to the Seafile web interface.

Steps:

Log In: Access your Seafile server's web address and log in with your user credentials.
Create a Library:
- Click the "+ New Library" button.
- Give it a name, e.g., "My Project Files".
- Do not enable encryption for this first library (we'll explore that later). Click "Submit".
- You now see your empty library listed under "My Libraries".
Upload Files:
- Click on the name of your new library ("My Project Files") to enter it.
- Click the "Upload" button and select a few small files (e.g., text files, images) from your computer. Or simply drag-and-drop files onto the web interface.
Explore Version History:
- Upload a small text file (e.g., notes.txt) containing "Version 1".
- Wait for the upload to complete.
- Now, hover over the notes.txt file in the web UI. You should see icons appear. Click the "History" icon (often looks like a clock or circular arrow).
- You'll see the initial version.
- Go back to the library view. Upload the same file (notes.txt) again, but this time ensure its content is different (e.g., "Version 2"). Seafile will ask if you want to overwrite; confirm.
- Go back to the file history for notes.txt. You should now see two versions listed with different timestamps.
- Click on the older version. You should see options to "View" or "Restore" it. Click "View" to confirm the content was "Version 1".
- This demonstrates the automatic versioning. Close the history view.
Create a Folder and Share:
- Inside your "My Project Files" library, click the "+ New" button and select "New Folder". Name it "Shared Documents".
- Hover over the "Shared Documents" folder and click the "Share" icon.
- Select the "Share Link" tab.
- Click "Generate Download Link". Observe the unique URL created.
- Click the "Settings" icon next to the link. Explore the options: add a password, set an expiration date. Set a simple password (e.g., "test123"). Save the settings.
- Copy the generated link. Open it in a private/incognito browser window. You should be prompted for the password before being able to see and download the (currently empty) folder contents.
- Go back to the sharing options for the folder and click "Generate Upload Link". Copy this link.
- Open the upload link in another private/incognito window. You should be able to drag-and-drop or select files to upload into that specific folder without needing to log in. Upload a test file.
- Go back to your main Seafile browser window, navigate into "Shared Documents," and verify the uploaded file appears.
Clean Up (Optional): Hover over the generated download and upload links in the Share dialog and click the trashcan icon to delete them.

Outcome: You have now practically interacted with Seafile libraries, observed file versioning in action, and created both download and upload sharing links, experiencing the core functionalities discussed.

2. Basic Installation via Docker

Docker provides the easiest and most recommended way to install Seafile, especially for beginners or those who prefer containerization. It packages Seafile and its dependencies (like the database and Memcached) into isolated containers, simplifying setup and management. We will use docker-compose, a tool for defining and running multi-container Docker applications.

Prerequisites

A Linux Server: A server (physical or virtual) running a recent Linux distribution (Ubuntu, Debian, CentOS recommended). You'll need root or sudo access.
Docker Engine: Docker must be installed on your server.
Docker Compose: Docker Compose (often installed as a Docker plugin docker compose or a standalone docker-compose) must be installed.
Basic Command-Line Knowledge: Familiarity with navigating directories (cd), creating files (touch, nano), and running commands.
Domain Name (Optional but Recommended): A domain name pointing to your server's IP address is needed for easy access and HTTPS setup later.

Installation Steps

Install Docker and Docker Compose:
- Follow the official Docker documentation for your specific Linux distribution to install the Docker Engine: https://docs.docker.com/engine/install/
- Install the Docker Compose plugin (usually included with Docker Desktop or installed separately for Linux Server): https://docs.docker.com/compose/install/
- Verify Installation:
```
docker --version
docker compose version # or docker-compose --version
```
- Add User to Docker Group (Optional but recommended): To run Docker commands without sudo, add your user to the docker group (requires logout/login or newgrp docker to take effect):
```
sudo usermod -aG docker $USER
```
Choose a Directory: Select a location on your server to store Seafile's configuration and data. This should be on a filesystem with sufficient space.
```
# Example: Create a directory in /opt
sudo mkdir -p /opt/seafile-docker
cd /opt/seafile-docker
```

Create the docker-compose.yml File:

Create a new file named docker-compose.yml using a text editor (like nano or vim):
```
sudo nano docker-compose.yml
```

Paste the following content into the file. Read the comments carefully and adjust the values!

# This is a docker-compose file for Seafile Professional/Community Edition
# Make sure to adjust passwords, volumes, and ports according to your needs.
# Official documentation: https://manual.seafile.com/docker/deploy_seafile_with_docker/

version: '3.8' # Or a compatible version supported by your docker compose

services:
  # Database Service (MariaDB is commonly used)
  db:
    image: mariadb:10.11 # Use a specific, stable version
    container_name: seafile-mysql
    environment:
      # IMPORTANT: Change 'YOUR_MYSQL_ROOT_PASSWORD' to a strong password
      MYSQL_ROOT_PASSWORD: 'YOUR_MYSQL_ROOT_PASSWORD'
      # IMPORTANT: Change 'YOUR_SEAFILE_DB_PASSWORD' to a strong password
      MYSQL_LOG_CONSOLE: 'true' # Optional: Log MySQL errors to container logs
      # Database names and user are typically handled by the Seafile container entrypoint
    volumes:
      # Mounts the database data to a persistent volume on the host
      # Adjust '/opt/seafile-docker/mysql-data' to your chosen host path
      - ./mysql-data:/var/lib/mysql
    networks:
      - seafile-net
    restart: unless-stopped # Automatically restart the container if it stops

  # Memcached Service (for caching)
  memcached:
    image: memcached:1.6 # Use a specific, stable version
    container_name: seafile-memcached
    entrypoint: memcached -m 256 # Allocate 256MB RAM to memcached (adjust if needed)
    networks:
      - seafile-net
    restart: unless-stopped

  # Seafile Server Service
  seafile:
    # Use 'seafileltd/seafile-mc' for Community Edition
    # Use 'seafileltd/seafile-pro-mc' for Pro Edition (requires license)
    image: seafileltd/seafile-mc:latest # Or specify a version like '9.0.10'
    container_name: seafile
    ports:
      # Map host port 80 to container port 80 (for initial setup/HTTP)
      # You might change the host port (e.g., '8088:80') if port 80 is taken
      # We will later rely on a reverse proxy, making this mapping less critical
      - "80:80"
      # By default, Seafile file server runs on 8082 internally. No need to expose usually.
      # - "8082:8082" # Only expose if needed for direct access (not recommended)
    volumes:
      # Mounts the Seafile server data and configuration to persistent volumes on the host
      # Adjust '/opt/seafile-docker/seafile-data' to your chosen host path
      - ./seafile-data:/shared
    environment:
      # --- Database Settings ---
      DB_HOST: 'db' # The service name of the database container
      DB_ROOT_PASSWD: 'YOUR_MYSQL_ROOT_PASSWORD' # Use the SAME root password as set in the 'db' service

      # --- Seafile Configuration ---
      # IMPORTANT: Change 'YOUR_DOMAIN_OR_IP' to your server's public IP or domain name
      #            This MUST be the URL users will use to access Seafile.
      #            Include http:// or https:// (use http initially)
      SEAFILE_SERVER_HOSTNAME: 'http://YOUR_DOMAIN_OR_IP'

      # IMPORTANT: Change 'admin@example.com' and 'YOUR_ADMIN_PASSWORD'
      SEAFILE_ADMIN_EMAIL: 'admin@example.com' # Email for the first admin user
      SEAFILE_ADMIN_PASSWORD: 'YOUR_ADMIN_PASSWORD' # Password for the first admin user

      # --- Timezone ---
      # Optional: Set your server's timezone, e.g., 'Europe/Berlin', 'America/New_York'
      # Find yours using `timedatectl list-timezones` on linux
      TZ: 'Etc/UTC'

    depends_on:
      - db # Ensure the database container starts before Seafile
      - memcached # Ensure Memcached starts before Seafile
    networks:
      - seafile-net
    restart: unless-stopped

# Define the network for containers to communicate
networks:
  seafile-net:
    driver: bridge # Default Docker network driver

Critical: Replace the placeholder values:
- YOUR_MYSQL_ROOT_PASSWORD: Choose a strong, unique password for the database root user.
- YOUR_SEAFILE_DB_PASSWORD: (While the entrypoint often handles DB creation, some older setups might require this. The provided docker-compose.yml relies on DB_ROOT_PASSWD for the Seafile container to set up its own DB user/password. Ensure consistency.)
- /opt/seafile-docker/mysql-data: Change if you chose a different path for your Docker setup.
- /opt/seafile-docker/seafile-data: Change if you chose a different path for your Docker setup.
- http://YOUR_DOMAIN_OR_IP: Extremely important! This must be the final URL that users will put in their browser to access Seafile. If you don't have a domain yet, use your server's public IP address (e.g., http://123.45.67.89). Using localhost or 127.0.0.1 here will cause problems later.
- admin@example.com: Set the email address for the initial Seafile administrator account.
- YOUR_ADMIN_PASSWORD: Set a strong password for the initial Seafile administrator account.
- TZ: Set your correct timezone (optional but good practice).
Save and close the file (e.g., in nano, press Ctrl+X, then Y, then Enter).

Start the Seafile Containers:
- Navigate to the directory containing your docker-compose.yml file (/opt/seafile-docker in our example).
- Run the following command to download the images and start the containers in the background (-d flag):
```
sudo docker compose up -d
```
- This command will:
  - Read the docker-compose.yml file.
  - Download the specified container images (MariaDB, Memcached, Seafile) if they aren't already present locally.
  - Create the seafile-net network.
  - Create and start the containers (db, memcached, seafile) in the correct order based on depends_on.
  - Map the specified volumes and ports.
  - The Seafile container's entrypoint script will automatically configure Seafile, set up the necessary database tables, and start the Seafile server (seafile-server) and the web UI (Seahub).

Check Container Status:

Wait a minute or two for the containers to initialize, especially on the first run as the database needs setting up.

Check if the containers are running:

sudo docker compose ps

You should see output similar to this, with State as Up or running:

   Name                    Command                 State          Ports
--------------------------------------------------------------------------------
seafile                /sbin/my_init -- /scripts ...   Up      0.0.0.0:80->80/tcp
seafile-memcached      docker-entrypoint.sh memc ...   Up      11211/tcp
seafile-mysql          docker-entrypoint.sh mysq ...   Up      3306/tcp

Check the logs for any errors, particularly for the seafile container:

sudo docker compose logs seafile
# Use 'Ctrl+C' to exit the log view
# Look for messages indicating successful startup

Initial Access:
- Open your web browser and navigate to the SEAFILE_SERVER_HOSTNAME you configured in the docker-compose.yml file (e.g., http://your_domain_or_ip).
- You should see the Seafile login page.
- Log in using the SEAFILE_ADMIN_EMAIL and SEAFILE_ADMIN_PASSWORD you set.

You now have a basic, functioning Seafile server running via Docker!

Workshop Basic Docker Installation

Objective: To perform the basic Seafile installation using Docker and docker-compose as described above and successfully log in to the web interface.

Prerequisites:

A Linux server meeting the prerequisites (Docker, Docker Compose installed).
SSH access to the server with sudo privileges.
A text editor available on the server (e.g., nano).

Steps:

Connect to Server: SSH into your Linux server.

Create Directory: Execute the command to create the installation directory:

sudo mkdir -p /opt/seafile-docker
cd /opt/seafile-docker
echo "Current directory: $(pwd)" # Verify you are in the correct directory

Create docker-compose.yml:
- Run sudo nano docker-compose.yml.
- Copy the docker-compose.yml content provided in the section above.
- Carefully review and replace the placeholder values:
  - YOUR_MYSQL_ROOT_PASSWORD (choose one, e.g., StrongDbRootPass123!)
  - Host volume paths (confirm they match ./mysql-data and ./seafile-data relative to /opt/seafile-docker)
  - SEAFILE_SERVER_HOSTNAME (use http://<your_server_IP> for now if you don't have a domain)
  - SEAFILE_ADMIN_EMAIL (use a real or functional email)
  - SEAFILE_ADMIN_PASSWORD (choose a strong admin password, e.g., StrongSeafileAdminPass456!)
  - TZ (optional, e.g., Europe/London)
- Save the file (Ctrl+X, Y, Enter in nano).
Start Containers: Run the docker compose up command:
```
sudo docker compose up -d
```
Observe the output as Docker downloads images and creates containers.
Verify Status: Wait ~60-90 seconds. Check the status:
```
sudo docker compose ps
```
Ensure all three containers (seafile, seafile-memcached, seafile-mysql) show Up or running. If not, check logs: sudo docker compose logs seafile and sudo docker compose logs db.
Access Web UI:
- Find your server's public IP address if you don't know it (e.g., ip addr show | grep 'inet ' or from your cloud provider console).
- Open a web browser on your local machine.
- Navigate to http://<your_server_IP> (using the IP you configured for SEAFILE_SERVER_HOSTNAME).
- You should see the Seafile login page.
Login: Enter the SEAFILE_ADMIN_EMAIL and SEAFILE_ADMIN_PASSWORD you configured in docker-compose.yml. Click "Log In".

Outcome: You should be successfully logged into the Seafile web interface (Seahub) as the administrator. You have deployed Seafile using Docker. You can see the initial empty dashboard.

3. Initial Server Configuration via Web UI

After the initial installation and first login, there are a few essential configuration steps you should take within the Seafile web interface (Seahub) to personalize your instance and ensure basic functionality.

Accessing System Administration

As the administrator user you logged in with (defined by SEAFILE_ADMIN_EMAIL and SEAFILE_ADMIN_PASSWORD), you have access to the System Administration panel.

Locate the Avatar: In the top-right corner of the Seahub interface, click on your user avatar (it might be a default icon initially).
Select "System Admin": From the dropdown menu, choose "System Admin".

This takes you to the central dashboard for managing your Seafile server. The left sidebar contains various administrative sections.

Key Initial Settings

Navigate through the System Admin sidebar to adjust these settings:

Info: (Usually the default view)
- Provides a quick overview of your Seafile installation: version numbers (Seafile Server, Seahub), number of users, groups, libraries, and storage usage. Verify this information looks correct.
Settings -> General:
- Site Title: Change "Seafile" to something more descriptive, like "My Personal Cloud" or "University Research Drive". This title appears in the browser tab and on the login page.
- Site Base: This typically reflects the SERVICE_URL and FILE_SERVER_ROOT (which we'll cover in Intermediate configuration). For now, ensure it matches the URL you are using to access Seafile. If you used an IP address during Docker setup but plan to use a domain name later, you will need to update this (and related config files) later.
- Enable user registration: By default, this might be enabled. Strongly consider disabling this if you want to control exactly who can create accounts on your server. If disabled, only administrators can create new user accounts. For a personal server or a small group, disabling registration is usually safer.
- Login Attempt Restrictions: Configure settings to lock out users or IP addresses after too many failed login attempts. This helps prevent brute-force attacks. Enable this and set reasonable limits (e.g., 5 attempts before locking for 10 minutes).
- Terms and Conditions: Optionally require users to accept terms before using the service.
Settings -> Email:
- Crucial for Functionality: Configure SMTP settings so Seafile can send emails for password resets, notifications, sharing invitations, etc. Without this, users who forget their passwords cannot recover them easily.
- You'll need details from your email provider (e.g., Gmail, Outlook, SendGrid, Mailgun, or your university's mail relay):
  - Email Host: SMTP server address (e.g., smtp.gmail.com).
  - Email Port: SMTP port (e.g., 587 for TLS, 465 for SSL, 25 for unencrypted).
  - Email User: Your email address or SMTP username.
  - Email Password: Your email password or an app-specific password (recommended for services like Gmail).
  - Email From: The address emails should appear to come from (e.g., noreply@yourdomain.com).
  - Use TLS/SSL: Select the appropriate encryption method required by your provider.
- Send Test Email: After filling in the details, use the "Send Test Email" button to verify the configuration. Check the recipient inbox (and spam folder) for the test message. Troubleshooting email sending is common; double-check all settings and provider requirements.
Users:
- Here you can manage user accounts. You currently only see your admin account.
- Create New Users (if registration is disabled): Click "+ Add User". You'll typically need to provide an email address (which becomes the login username) and an initial password. The user can (and should) change this password after their first login.
- Manage Existing Users: Click on a username to view details, change their password, set storage quotas (if desired), grant/revoke admin privileges, or delete the user.
Settings -> Logo:
- Personalize your instance by uploading a custom logo that will replace the default Seafile logo in the top-left corner of the web interface.

Making these initial adjustments provides a more secure, functional, and personalized Seafile experience.

Workshop Initial Web Configuration

Objective: To configure basic settings within the Seafile System Admin panel, including site title, disabling registration, and attempting email setup.

Prerequisites:

A running Seafile instance accessible via a web browser.
Logged in as the administrator user.
(Optional but needed for email part) SMTP server details from an email provider. You can use a service like Mailtrap.io for testing if you don't want to use a real email account initially.

Steps:

Access System Admin: Log into Seafile. Click your avatar (top-right) -> "System Admin".
Change Site Title:
- Navigate to "Settings" -> "General".
- Locate the "Site Title" field. Change it from "Seafile" to something like "[Your Name]'s Cloud" or "Uni Project Hub".
- Click "Submit" at the bottom of the page.
- Notice the title change in your browser tab and potentially at the top of the page (refresh if needed).
Disable User Registration:
- Still in "Settings" -> "General".
- Find the checkbox for "Enable user registration".
- Uncheck this box.
- Click "Submit".
- (Verification): Log out of Seafile. On the login page, confirm there is no "Sign up" or "Register" link anymore. Log back in as admin.
Configure Login Attempts:
- Still in "Settings" -> "General".
- Find "Login Attempt Restrictions".
- Check the box "Enable login attempt limit".
- Set "Max login attempts" to 5.
- Set "Lockout time" to 15 (minutes).
- Click "Submit".
Attempt Email Configuration:
- Navigate to "Settings" -> "Email".
- Fill in the SMTP details you have. If you don't have any, you can skip this step for now or sign up for a free tier at Mailtrap.io to get test SMTP credentials.
  - Enter Host, Port, User, Password, From address.
  - Select TLS or SSL as appropriate.
- Click "Submit".
- Crucially: Click the "Send Test Email" button. Enter a recipient email address (your own is fine). Click "Send".
- Check the recipient's inbox (and spam folder). Did the email arrive?
  - If Yes: Congratulations! Email is working.
  - If No: Double-check all settings. Consult your email provider's documentation for the correct SMTP details. Check Seafile logs (sudo docker compose logs seafile) for error messages related to email sending. This step often requires troubleshooting.
Add a Test User (Optional):
- Navigate to "Users".
- Click "+ Add User".
- Enter testuser@example.com as the email and assign a simple password (e.g., testpass123). Leave "Role" as default and "Quota" empty (unlimited).
- Click "Submit".
- You should see testuser@example.com listed. Log out as admin and try logging in as this new user to confirm account creation works. Log back in as admin.

Outcome: You have successfully customized basic server settings like the site title, enhanced security by disabling registration and enabling login limits, and attempted to configure email notifications. You have also familiarized yourself with the System Admin interface.

4. Basic Usage Web UI and Desktop Client

With the server running and basic configuration done, let's explore how to actually use Seafile for its core purpose: storing, syncing, and sharing files. We'll cover both the web interface (Seahub) and the desktop synchronization client.

Using the Web Interface (Seahub)

The web interface is accessible from any browser and provides comprehensive functionality without needing to install client software.

Dashboard: After logging in, you'll see your dashboard, typically showing "My Libraries," "Shared with me," "Shared with groups," and "Favorites."
Creating Libraries: Click "+ New Library", provide a name, and optionally choose to encrypt it (remember the warning about lost passwords!).
Navigating Libraries: Click on a library name to browse its contents (files and folders).
Uploading Files/Folders: Inside a library, use the "Upload" button (select files or folders) or simply drag-and-drop items from your computer onto the browser window.
Creating Folders/Files: Use the "+ New" button inside a library to create new folders or basic text/Markdown files directly within Seafile.
File Operations: Hover over a file or folder to see options:
- Download: Download the item to your computer.
- Share: Access sharing options (share to users/groups, generate links).
- History: View the version history of a file.
- Rename: Change the name of the file/folder.
- Move/Copy: Move or copy items to different locations within your libraries.
- Delete: Move the item to the library's trash bin.
Trash Bin: Each library has its own trash bin. Click the "Trash" icon (usually near the top of the library view) to see deleted items. You can restore them or permanently delete them from here. There might also be a system-wide trash cleanup schedule configured by the admin.
Markdown Editing: If you create or upload a .md file, clicking on it often opens a built-in editor allowing you to modify it using Markdown syntax, often with a live preview.
Activities: The "Activities" section (sometimes accessible from the main dashboard or admin panel) shows a log of recent events like file uploads, edits, shares, etc.

Installing and Setting Up the Desktop Client

The desktop client provides automatic, background synchronization between your local computer and the Seafile server, similar to Dropbox or Google Drive desktop clients.

Download: Go to the official Seafile website's download page (https://www.seafile.com/en/download/) and download the appropriate client for your operating system (Windows, macOS, Linux).
Install: Run the installer and follow the standard installation procedure for your OS.
Initial Setup:
- Launch the Seafile client.
- It will prompt you to add an account. Click "Add an Account".
- Server Address: Enter the exact same URL you use to access Seafile in your browser (the SEAFILE_SERVER_HOSTNAME you configured, e.g., http://your_domain_or_ip).
- Email: Enter your Seafile username (email address).
- Password: Enter your Seafile password.
- Computer Name: Choose a name to identify this computer (e.g., "My Laptop," "Workstation"). This helps you manage linked devices later in the web UI under Settings -> Linked Devices.
- Click "Login".
Choosing Libraries to Sync:
- After successful login, the client will connect to the server and display a list of your available libraries.
- By default, no libraries are synced. You need to choose which ones you want to synchronize to your local machine.
- Click the "Sync this library" button next to a library you want to sync.
- It will ask you to choose a local directory where the library's contents should be stored. You can accept the default (usually within a Seafile folder in your user's home directory) or choose a custom location.
- The client will start downloading the library's contents. A green checkmark icon indicates syncing is complete and up-to-date. Other icons indicate syncing in progress or errors.
Client Interface:
- The client usually runs in the system tray or menu bar. Clicking the icon opens the main window.
- It shows your synced libraries, recent file activities, errors, and transfer progress.
- You can right-click a synced library to access options like "Open local folder," "View on cloud," "Sync now," or "Unsync."

Basic Syncing Workflow

Create/Modify Locally: Create a new file or modify an existing file inside the local folder associated with a synced Seafile library.
Automatic Upload: The Seafile client will detect the change, break the file into blocks (if necessary), and upload the changes/new blocks to the server automatically in the background.
Server Update: The server updates the library's state and history.
Automatic Download (Other Clients): Any other desktop clients logged into the same account and syncing the same library will automatically download the changes.
View on Web: You can also verify the changes through the web interface (Seahub).

This seamless, automatic synchronization is the core power of the desktop client.

Workshop Using Seafile

Objective: To practice basic file operations using both the web UI and the desktop client, demonstrating the synchronization process.

Prerequisites:

A running Seafile instance accessible via a web browser.
Administrator or regular user account credentials.
Seafile Desktop Client installed on your local machine (Windows, macOS, or Linux).

Steps:

Part 1: Web UI Operations

Log In (Web): Access your Seafile server via the web browser and log in.
Create Library: Click "+ New Library", name it "Sync Test", do not encrypt it, and click "Submit".
Create Folder & File (Web):
- Click on the "Sync Test" library to enter it.
- Click "+ New" -> "New Folder". Name it "Web Uploads".
- Enter the "Web Uploads" folder.
- Click "+ New" -> "New File". Name it web_notes.md.
- Enter some text like "# Notes from Web Interface\n\nThis file was created online."
- Click the "Save" icon (usually a checkmark or disk icon).
Upload File (Web):
- Navigate back to the root of the "Sync Test" library.
- Click "Upload" -> "File". Select any small image file from your computer.

Part 2: Desktop Client Setup & Sync

Launch Client: Start the Seafile Desktop Client on your computer if it's not already running.
Add Account (if needed): If this is the first time, add your account: enter Server URL, Email, Password, and Computer Name. Click "Login".
Sync the Library:
- In the Seafile client's main window, find the "Sync Test" library in the list.
- Click the "Download and Sync" button (or similar wording) next to it.
- Confirm the local folder location where you want to sync it (the default is usually fine). Click "OK" or "Sync".
- Wait for the client to download the library contents. The status icon next to the library should turn into a green checkmark.
Verify Local Files:
- Right-click the "Sync Test" library in the client and select "Open local folder" (or manually navigate to the folder you chose).
- Verify that you see the "Web Uploads" folder and the image file you uploaded via the web UI.
- Look inside the "Web Uploads" folder and verify web_notes.md is there. Open it with a text editor and check its content.

Part 3: Local Changes and Synchronization

Modify File Locally:
- Open the web_notes.md file (located in your local "Sync Test/Web Uploads" folder) using a local text editor.
- Add a new line: "This line was added locally via the desktop client."
- Save the file.
Create File Locally:
- In the root of your local "Sync Test" folder (not inside "Web Uploads"), create a new text file named local_file.txt. Add some text like "Hello from local machine". Save it.
Observe Client: Watch the Seafile desktop client icon in your system tray/menu bar. It should indicate activity (syncing). You can open the client window to see the progress or recent activities. Wait for the green checkmark again.
Verify on Web:
- Go back to your Seafile web browser window.
- Refresh the view of the "Sync Test" library.
- You should now see local_file.txt in the root of the library.
- Navigate into the "Web Uploads" folder. Click on web_notes.md. You should see the updated content including the line added locally. If there's a built-in editor, it should show the changes. You can also check its history to see the modification.

Outcome: You have successfully used both the web UI and desktop client to manage files. You created content online, synced it down, made changes locally, created new content locally, and observed these changes automatically sync back to the server and become visible in the web UI, demonstrating the core two-way sync functionality.

Intermediate

This section delves deeper into Seafile administration, covering more robust installation methods, detailed configuration, essential security practices like HTTPS, and advanced user management.

5. Advanced Installation Methods

While Docker offers convenience, installing Seafile manually (or "natively") on the host system provides finer control over components, potentially better performance in some scenarios (by avoiding containerization overhead), and might be necessary in environments where Docker isn't preferred or allowed. This typically involves installing dependencies, downloading the Seafile server package, and configuring it alongside a separate web server (like Nginx or Apache) and database (like MySQL/MariaDB or PostgreSQL).

Choosing a Database Backend

Seafile requires a database to store metadata, user information, file structures, and sharing permissions (the file content itself is stored as blocks on the filesystem). You have choices:

SQLite:
- Pros: Simplest to set up, as it's a file-based database included with Python. No separate database server needed initially. Good for single-user or very small deployments (< 5 users).
- Cons: Does not scale well. Performance degrades significantly under load or with many files/users. Not recommended for production or multi-user environments. Prone to database locking issues under concurrent access.
MySQL/MariaDB:
- Pros: Very popular, mature, well-documented relational database. Offers good performance and scalability for most Seafile use cases. Widely supported. MariaDB is a community-developed fork of MySQL and is often recommended.
- Cons: Requires running a separate database server process. Slightly more complex configuration than SQLite.
PostgreSQL:
- Pros: Powerful, feature-rich, standards-compliant relational database known for robustness and data integrity. Can offer excellent performance, sometimes surpassing MySQL in complex query scenarios.
- Cons: Requires running a separate database server process. Configuration can be slightly more involved than MySQL for beginners. Less commonly used with Seafile than MySQL/MariaDB, so finding specific community help might be marginally harder.

Recommendation: For any deployment beyond personal testing, use MySQL/MariaDB or PostgreSQL. MariaDB is often a good default choice due to its performance and ease of use relative to its capabilities.

Manual Installation Steps (Example using Ubuntu/Debian and MariaDB)

This is a detailed overview. Always refer to the latest official Seafile Server Manual for the specific commands and package versions for your OS: https://manual.seafile.com/deploy/

Prepare the Server:
- Start with a clean, updated Linux server (e.g., Ubuntu 20.04/22.04 or Debian 11/12).
- Ensure essential tools are present: sudo, wget, tar, text editor (nano, vim).
- bash sudo apt update && sudo apt upgrade -y sudo apt install -y wget tar python3 python3-pip python3-dev libmariadb-dev-compat libmariadb-dev build-essential # Base tools + MySQL/MariaDB dev libraries

Install and Configure MariaDB:

Install the MariaDB server:
```
sudo apt install -y mariadb-server
```
Run the secure installation script:
```
sudo mysql_secure_installation
```
- Set a strong root password.
- Remove anonymous users? Yes.
- Disallow root login remotely? Yes.
- Remove test database? Yes.
- Reload privilege tables? Yes.

Log in to MariaDB as root:

sudo mysql -u root -p
# Enter the root password you just set

Create the databases and user for Seafile (replace YOUR_SEAFILE_DB_PASSWORD with a strong, unique password):

-- Create databases with UTF8mb4 encoding for full character support
CREATE DATABASE `ccnet-db` CHARACTER SET = 'utf8mb4' COLLATE = 'utf8mb4_unicode_ci';
CREATE DATABASE `seafile-db` CHARACTER SET = 'utf8mb4' COLLATE = 'utf8mb4_unicode_ci';
CREATE DATABASE `seahub-db` CHARACTER SET = 'utf8mb4' COLLATE = 'utf8mb4_unicode_ci';

-- Create a dedicated user for Seafile
CREATE USER 'seafile'@'localhost' IDENTIFIED BY 'YOUR_SEAFILE_DB_PASSWORD';

-- Grant privileges to the Seafile user on these databases
GRANT ALL PRIVILEGES ON `ccnet-db`.* TO 'seafile'@'localhost';
GRANT ALL PRIVILEGES ON `seafile-db`.* TO 'seafile'@'localhost';
GRANT ALL PRIVILEGES ON `seahub-db`.* TO 'seafile'@'localhost';

-- Apply the changes
FLUSH PRIVILEGES;

-- Exit MariaDB
EXIT;

Test the Seafile user login (optional):

mysql -u seafile -p -h localhost
# Enter YOUR_SEAFILE_DB_PASSWORD
# Type 'EXIT;' to quit if successful

Install Seafile Python Dependencies:
- Seafile relies on several Python packages. Install them using pip. It's highly recommended to use a virtual environment, but the official script often installs globally or expects system packages. Check the manual. A common approach is:
- ```bash # Install prerequisites for Python packages (some might be covered by build-essential) sudo apt install -y python3-setuptools python3-ldap python3-urllib3 python3-requests python3-pil # Check manual for exhaustive list

Install specific libraries via pip (consult manual for exact list and versions!)

sudo pip3 install --timeout=3600 Pillow pylibmc captcha jinja2 sqlalchemy psd-tools django-pylibmc django-simple-captcha python-memcached requests # Example list, VERIFY WITH MANUAL `` *Note: Installing Python packages globally withsudo pip3can sometimes conflict with system packages. Using virtual environments (venv`) is generally better practice for Python projects but adds complexity to the Seafile setup script handling.*
Download and Extract Seafile Server:
- Go to the official Seafile download page and find the link for the latest Generic Linux Server version (Community or Pro).
- Choose a directory to install Seafile (e.g., /opt/seafile).
- ```bash # Example for creating the directory sudo mkdir -p /opt/seafile cd /opt/seafile

Download the server tarball (replace URL with the correct one)

sudo wget https://download.seafile.com/f/xxxxxx/seafile-server_9.0.10_x86-64.tar.gz # Replace with actual link!

Extract the tarball

sudo tar -xzf seafile-server_*.tar.gz

Optional: Clean up the tarball

sudo rm seafile-server_*.tar.gz

Create a dedicated data directory (outside the installation dir usually)

sudo mkdir /opt/seafile-data ```
Run the Seafile Setup Script:
- Navigate into the extracted Seafile server directory (e.g., /opt/seafile/seafile-server-9.0.10).
- Run the setup script specifically for MySQL/MariaDB:
```
cd seafile-server-* # Navigate into the extracted folder
sudo ./setup-seafile-mysql.sh
```
- The script will guide you through configuration:
  - Server Name: Choose a name for your server (e.g., "MySeafile").
  - Server IP or Domain: Crucial! Enter the exact IP address or domain name users will use (e.g., seafile.mydomain.com or 123.45.67.89). This sets initial values for SERVICE_URL and FILE_SERVER_ROOT.
  - Seafile Data Directory: Specify the path you created earlier (e.g., /opt/seafile-data). Ensure this directory exists and has correct permissions. The setup script might offer to create it.
  - Database Details:
    - Database Server Host: localhost (or the IP if your DB is remote).
    - Database Server Port: 3306 (default for MySQL/MariaDB).
    - Database User: seafile (the user you created).
    - Database Password: YOUR_SEAFILE_DB_PASSWORD (the password you set).
    - Database Names: ccnet-db, seafile-db, seahub-db (confirm these match what you created).
  - Initialization: Choose 1 to initialize the databases (create tables). Do not choose this if you are upgrading or restoring!
- The script will create configuration files (like ccnet.conf, seafile.conf, seahub_settings.py) in the /opt/seafile/conf directory (or similar, check script output) and populate the database tables.
Set File Permissions:
- The Seafile process needs ownership or write access to the data directory and parts of the installation/log directories. Often, creating a dedicated seafile user/group and assigning ownership is best practice.
- bash # Example: Create user/group and assign ownership sudo adduser --system --group --no-create-home seafile sudo chown -R seafile:seafile /opt/seafile # Installation directory (adjust if needed) sudo chown -R seafile:seafile /opt/seafile-data # Data directory # May also need ownership of log directory, e.g., /opt/seafile/logs sudo chown -R seafile:seafile /opt/seafile/logs Note: Running Seafile services as this non-root seafile user enhances security.
Start Seafile and Seahub:
- Seafile consists of two main services: seafile-server (handles file syncing) and seahub (the web interface).
- Start them using the provided scripts (adjust path if needed):
```
# Start Seafile server (run as the seafile user if created)
sudo -u seafile /opt/seafile/seafile-server-latest/seafile.sh start

# Start Seahub web interface (run as the seafile user if created)
sudo -u seafile /opt/seafile/seafile-server-latest/seahub.sh start
```
- On the first start of Seahub, it will prompt you to create the initial administrator account (email and password). Enter these carefully.
- Seahub, by default, starts a development web server on port 8000. This is not suitable for production. We will address this with a reverse proxy (Nginx/Apache) later.
Initial Access (Development Mode):
- Ensure your server's firewall allows traffic on port 8000 (e.g., sudo ufw allow 8000/tcp).
- Access Seafile via http://YOUR_SERVER_IP_OR_DOMAIN:8000.
- Log in with the admin credentials you just created.

This manual installation gives you a running Seafile server but without HTTPS and using the less efficient Seahub development server. The next steps involve setting up a production-grade web server (reverse proxy) and configuring Seafile in more detail.

Workshop Manual Installation (Conceptual)

Objective: To understand the sequence of steps and commands involved in a manual Seafile installation using MariaDB on Ubuntu/Debian, without necessarily performing every step on a live server (unless you have a dedicated test machine).

Prerequisites:

Access to a Linux command line (could be your local machine with virtualization, a cloud VM, or just reading through carefully).
Conceptual understanding of Linux package management (apt), database creation (mysql client), and file system navigation.

Steps (Mental Walkthrough & Key Command Review):

Preparation:
- Imagine starting with a fresh Ubuntu Server. What's the first command you'd run? (sudo apt update && sudo apt upgrade -y)
- What key packages would you install before even downloading Seafile? (Python, pip, MariaDB client/dev libraries, build tools: python3 python3-pip python3-dev libmariadb-dev-compat libmariadb-dev build-essential wget tar)
Database Setup:
- How do you install the MariaDB server? (sudo apt install mariadb-server)
- What script hardens the initial MariaDB security? (sudo mysql_secure_installation)
- Recall the SQL commands (or their purpose) needed to prepare for Seafile:
  - CREATE DATABASE ... CHARACTER SET 'utf8mb4'; (Why utf8mb4?) -> Supports a wider range of characters, including emojis.
  - CREATE USER 'seafile'@'localhost' IDENTIFIED BY '...'; (Why 'localhost'?) -> Restricts this user to connecting only from the server itself, improving security.
  - GRANT ALL PRIVILEGES ON ... TO 'seafile'@'localhost'; (What does this do?) -> Gives the Seafile application full control over its specific databases.
  - FLUSH PRIVILEGES; (Why is this needed?) -> Reloads the grant tables so the changes take effect immediately.
Seafile Download & Extraction:
- Where would you typically install Seafile software? (/opt/seafile is common). Command? (sudo mkdir /opt/seafile; cd /opt/seafile)
- How do you get the Seafile server package? (wget <URL>)
- How do you unpack it? (tar -xzf <filename>)
- Where should Seafile data (user files, etc.) be stored? (Typically outside the program directory, e.g., /opt/seafile-data). Command? (sudo mkdir /opt/seafile-data)
Seafile Configuration Script:
- Which script initiates the configuration process for MySQL? (sudo ./setup-seafile-mysql.sh inside the extracted server directory).
- What critical piece of information does this script ask for that affects URLs? (Server IP or Domain Name).
- What other key details does it need? (Data directory path, DB host, DB port, DB user, DB password, DB names).
Permissions:
- Why is it recommended to run Seafile services as a non-root user (e.g., seafile)? (Principle of least privilege: if the service is compromised, the attacker doesn't immediately have root access).
- Which commands are used to create such a user and assign ownership? (sudo adduser --system ... seafile, sudo chown -R seafile:seafile /opt/seafile /opt/seafile-data /opt/seafile/logs)
Starting Services:
- What are the two main services? (seafile-server, seahub).
- What are the commands to start them? (sudo -u seafile .../seafile.sh start, sudo -u seafile .../seahub.sh start).
- On which port does seahub.sh start typically run initially, and why is this not ideal for production? (Port 8000, it's a less performant development server).

Outcome: By walking through these steps and reviewing the key commands and their purpose, you should have a much clearer understanding of the manual installation process, the components involved (OS, Database, Seafile Core, Seahub Web), and the rationale behind various configuration choices, even if you didn't execute them live. This prepares you for understanding the configuration files in the next section.

6. Server Configuration Deep Dive

Whether you installed Seafile via Docker or manually, understanding its configuration files is key to customizing behavior, optimizing performance, and enabling advanced features. The primary files are:

ccnet.conf: Configures the Ccnet daemon, responsible for user management and connections between components.
seafile.conf: Configures the Seafile data server (seaf-server), handling file storage, syncing, and transfers.
seahub_settings.py: Configures the Seahub web interface (Django application), controlling appearance, web features, and integrations.

Location:

Docker: These files are typically located within the mounted /shared/conf volume on the host (e.g., /opt/seafile-docker/seafile-data/seafile/conf if you followed the basic Docker setup).
Manual Install: Usually found in a conf directory near your installation path (e.g., /opt/seafile/conf).

Important: After modifying any of these configuration files, you must restart the corresponding Seafile services for the changes to take effect.

Docker: sudo docker compose restart seafile

Manual Install:

sudo -u seafile /opt/seafile/seafile-server-latest/seafile.sh restart
sudo -u seafile /opt/seafile/seafile-server-latest/seahub.sh restart # Or use the fastcgi stop/start if using Nginx/Apache

`ccnet.conf`

Located in the conf directory (or /shared/conf in Docker). Primarily deals with networking and user management backend settings.

[General]
# The central configuration directory. Usually detected automatically.
# CONF_DIR = /opt/seafile/conf

[Network]
# Port for the Ccnet service. Default is 10001. Usually only needs
# internal access between Seafile components, unless using LDAP sync.
# PORT = 10001

[Client]
# Port used by seaf-daemon (desktop client background service) to talk to Ccnet.
# Default is 13419. Usually only needed locally on the client machine.
# PORT = 13419

[Database]
# Defines the database connection for Ccnet's user/group info.
# Examples shown are for MySQL. Adjust TYPE for sqlite3 or postgresql.
# Ensure these match your actual database setup.
TYPE = mysql
HOST = db # Docker service name or 127.0.0.1 for manual local install
PORT = 3306
USER = seafile
PASSWD = YOUR_SEAFILE_DB_PASSWORD # The password you set
DB = ccnet-db
CONNECTION_CHARSET = utf8mb4 # Important for character support

Key Sections: [Database] is critical, ensuring Ccnet can connect to its database. The details must match your setup (Docker service name db or 127.0.0.1/localhost for manual installs, correct user/password/database name). CONNECTION_CHARSET = utf8mb4 is highly recommended.

`seafile.conf`

Located in the conf directory (or /shared/conf in Docker). Configures the core data server.

[general]
# The location where Seafile server stores its internal data structures
# (commits, blocks, etc.). This points INSIDE the container for Docker.
# For manual installs, it's the path you chose during setup.
# data_dir = /shared/seafile-data # Docker Example
# data_dir = /opt/seafile-data # Manual Install Example

[database]
# Defines the database connection for Seafile's library/file metadata.
# Similar structure to ccnet.conf database section. MUST match your setup.
type = mysql
host = db # Docker service name or 127.0.0.1 for manual local install
port = 3306
user = seafile
password = YOUR_SEAFILE_DB_PASSWORD
db_name = seafile-db
connection_charset = utf8mb4

[fileserver]
# Port for the Seafile file server (seaf-server). Default 8082.
# This is where clients connect to upload/download file content.
# Needs to be accessible from the outside, usually via a reverse proxy.
port = 8082

# Maximum upload file size in Megabytes (MB). Default is unlimited/very large.
# Set a value like '2048' for 2GB limit.
# max_upload_size =

# Maximum download directory size in MB. Default unlimited.
# max_download_dir_size =

[seahub]
# Tells seaf-server where to find the Seahub media files (CSS, JS, images).
# Usually points to the 'media' subdirectory within the seahub installation.
# Needs adjustment for manual installs, often set automatically by setup script.
# media_dir = /opt/seafile/seafile-server-latest/seahub/media

Key Sections:
- [database]: Critical, must match your Seafile database setup.
- [fileserver]: port = 8082 is the default port clients use for data transfer. You might configure max_upload_size if needed.

`seahub_settings.py`

Located in the conf directory (or /shared/conf in Docker). This is a Python file, so syntax matters (indentation, quotes). It controls the web interface and features. Many options are available, consult the official manual for a full list.

# -*- coding: utf-8 -*-

# Unique secret key for this Seahub instance. Auto-generated during setup.
# DO NOT SHARE THIS KEY. If compromised, generate a new one.
SECRET_KEY = "YOUR_AUTO_GENERATED_SECRET_KEY"

# --- Database Configuration ---
# Tells Seahub (Django) how to connect to its database.
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql', # Or 'postgresql' or 'sqlite3'
        'HOST': 'db', # Docker service name or '127.0.0.1' for manual
        'PORT': '3306',
        'USER': 'seafile',
        'PASSWORD': 'YOUR_SEAFILE_DB_PASSWORD',
        'NAME': 'seahub-db',
        'OPTIONS': {
            'charset': 'utf8mb4',
        },
    }
}

# --- URL Configuration ---
# VERY IMPORTANT: These MUST match the URL users use to access Seafile.
# Should align with SEAFILE_SERVER_HOSTNAME in Docker or the value given
# during manual setup, especially after setting up a reverse proxy.
# Incorrect values cause issues with links, downloads, avatars etc.
SERVICE_URL = "http://YOUR_DOMAIN_OR_IP" # Use https:// after setting up reverse proxy

# This MUST point to the URL where the file server (seaf-server on port 8082)
# is accessible. Usually SERVICE_URL + '/seafhttp'. The reverse proxy
# needs to be configured to handle this path correctly.
FILE_SERVER_ROOT = SERVICE_URL + '/seafhttp'

# --- Caching ---
# Enables caching for better web performance. Highly recommended.
# Memcached is preferred over database caching.
CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
        'LOCATION': 'memcached:11211', # Docker: 'service_name:port'
        # 'LOCATION': '127.0.0.1:11211', # Manual Install: 'ip:port'
    },
    # Optional: Separate cache for avatars
    'avatar': {
         'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
         'LOCATION': 'memcached:11211', # Or '127.0.0.1:11211'
         'OPTIONS': {
             'MAX_ENTRIES': 1000
         }
     },
}


# --- Email Settings ---
# Can be configured here OR via the System Admin > Settings > Email UI.
# Settings here take precedence if uncommented.
# EMAIL_USE_TLS = True
# EMAIL_HOST = 'smtp.example.com'
# EMAIL_HOST_USER = 'username@example.com'
# EMAIL_HOST_PASSWORD = 'password'
# EMAIL_PORT = 587
# DEFAULT_FROM_EMAIL = EMAIL_HOST_USER
# SERVER_EMAIL = EMAIL_HOST_USER

# --- User/Security Settings ---
# Disable registration via config file (alternative to Web UI)
# ENABLE_SIGNUP = False

# Enable Terms and Conditions requirement on signup/first login
# ENABLE_TERMS_AND_CONDITIONS = True

# Force password change for users after admin reset
# FORCE_PASSWORD_CHANGE = True

# Minimum password length requirement
# PASSWORD_MIN_LENGTH = 8 # Default is 6

# Enable Two-Factor Authentication (requires setup, see advanced section)
# ENABLE_TWO_FACTOR_AUTH = True

# --- Other Features ---
# Enable online file preview/editing (requires additional setup, e.g. ONLYOFFICE/Collabora)
# See specific documentation for these features.
# SERVICE_URL and FILE_SERVER_ROOT must be correct for these to work.
# ENABLE_ONLYOFFICE = True
# VERIFY_ONLYOFFICE_CERTIFICATE = True
# ONLYOFFICE_API_ENDPOINT = "http://onlyoffice-document-server/"
# ONLYOFFICE_JWT_SECRET = "your-onlyoffice-jwt-secret"

# Enable file search (requires configuring Elasticsearch or dtsearch backend)
# Enable background indexing tasks for search.
# SEARCH_ENABLE = True
# SEARCH_INDEX_UPDATE_INTERVAL = 10 # In minutes


# --- Logging ---
# Configure logging levels and outputs
# See Django logging documentation for details.
# LOGGING = { ... }


# Add any other custom settings below.
# Check the Seafile Server Manual for many more options!
# e.g., customizing logos, enabling/disabling features, quotas, etc.

Key Sections/Variables:
- SECRET_KEY: Must be kept private.
- DATABASES: Must match your Seahub database setup.
- SERVICE_URL & FILE_SERVER_ROOT: Absolutely critical for correct operation, especially after adding HTTPS or a reverse proxy. These dictate how Seafile generates internal and external links. This is the most common source of problems if misconfigured.
- CACHES: Enabling Memcached significantly improves web UI responsiveness. Ensure LOCATION points to your Memcached service (memcached:11211 in Docker, 127.0.0.1:11211 for local manual install).
- Email settings, user/security settings, and feature enablement (like ONLYOFFICE, Search) are common customizations.

Carefully review and adjust these files according to your specific setup and requirements. Always back up configuration files before making significant changes.

Workshop Exploring and Modifying Configuration Files

Objective: To locate, examine, and make a minor modification to a Seafile configuration file, then restart the services and observe the effect. We will modify the Site Title via seahub_settings.py instead of the Web UI.

Prerequisites:

A running Seafile instance (Docker preferred for easy access to mapped conf volume).
Access to the server's command line with sudo privileges.
A text editor (nano).

Steps:

Locate Configuration Files:
- If using Docker (based on the example docker-compose.yml): The configuration files are mapped to the host inside the /opt/seafile-docker/seafile-data/seafile/conf directory.
```
cd /opt/seafile-docker/seafile-data/seafile/conf
ls -l
# You should see ccnet.conf, seafile.conf, seahub_settings.py, etc.
```
- If using Manual Install: Navigate to the conf directory you identified during setup (e.g., /opt/seafile/conf).
```
cd /opt/seafile/conf
ls -l
```
Examine seafile.conf:
- Open the file for viewing:
```
sudo nano seafile.conf # Or just 'cat seafile.conf'
```
- Identify the [database] section and note the db_name (seafile-db).
- Identify the [fileserver] section and note the port (8082).
- Exit nano (Ctrl+X) without saving if you opened it for editing.
Backup seahub_settings.py: Before editing, create a backup:
```
sudo cp seahub_settings.py seahub_settings.py.bak
```
Modify seahub_settings.py:
- Open the file for editing:
```
sudo nano seahub_settings.py
```
- Scroll down through the file. You likely won't see a SITE_TITLE setting by default, as it's often managed via the UI database setting unless explicitly added here.
- Add the following lines at the end of the file (ensure correct Python syntax - no leading spaces unless intended for indentation within a block, which isn't the case here):
```
# Custom Site Title set via config file
SITE_TITLE = 'Seafile Config Lab'

# Optional: Also override the logo link URL if needed
# SITE_NAME = 'ConfigLab' # Short name used in some places
```
- Important: Make sure you add this on new lines at the end, not disrupting existing Python code blocks.
- Save the file and exit (Ctrl+X, Y, Enter).

Restart Seafile Services:

Docker:

cd /opt/seafile-docker # Go back to the directory with docker-compose.yml
sudo docker compose restart seafile # This restarts the container, which restarts seafile & seahub

Manual Install:

# Assuming Seafile installed in /opt/seafile and running as user 'seafile'
sudo -u seafile /opt/seafile/seafile-server-latest/seahub.sh restart
# Note: Restarting only Seahub is enough for seahub_settings.py changes
# Wait a few seconds for it to restart

Verify the Change:
- Clear your browser cache or use a private/incognito window to avoid cached titles.
- Access your Seafile web interface.
- Observe the title shown in the browser tab and potentially on the login page. It should now be "Seafile Config Lab".
- Log in. Navigate to System Admin -> Settings -> General. The "Site Title" field might now be greyed out or reflect the value from the config file, indicating it's overridden by seahub_settings.py.
Revert Changes (Optional):
- If you want to go back to managing the title via the UI:
  - Edit seahub_settings.py again (sudo nano seahub_settings.py).
  - Delete or comment out (by adding # at the beginning) the SITE_TITLE = 'Seafile Config Lab' line you added.
  - Save the file.
  - Restart the services again (sudo docker compose restart seafile or sudo -u seafile .../seahub.sh restart).
  - Verify the site title reverts to its previous state (you might need to set it again in the System Admin UI).

Outcome: You have successfully located Seafile's configuration files, backed one up, made a change to seahub_settings.py to override a setting usually controlled by the UI, restarted the relevant service(s), and verified the change took effect. This demonstrates the process of customizing Seafile via its configuration files.

7. Reverse Proxy Setup with Nginx and HTTPS

Running Seahub directly via seahub.sh start (on port 8000) uses a basic Python development server that is inefficient and insecure for production use. Furthermore, accessing your Seafile instance over plain HTTP (port 80) sends your login credentials and data unencrypted.

A reverse proxy (like Nginx or Apache) sits in front of your Seafile services and provides several benefits:

HTTPS/SSL/TLS Encryption: The reverse proxy handles SSL termination, encrypting traffic between users and your server. This is essential for security. We'll use Let's Encrypt for free certificates.
Standard Ports: Allows users to access Seafile via standard web ports (80 for HTTP, 443 for HTTPS) instead of non-standard ports like 8000.
Performance: Production web servers like Nginx are highly optimized for handling concurrent connections and serving static files (like Seafile's CSS, JS, images), improving performance.
Load Balancing (Advanced): Can distribute traffic across multiple Seafile server instances if needed.
Security: Can provide an additional layer of security, filtering requests or implementing rate limiting.
Unified Access: Handles requests for both the Seahub web interface (port 8000 internally) and the Seafile file server (port 8082 internally) through a single domain name.

We will focus on Nginx, a popular, high-performance web server.

Prerequisites

A Running Seafile Instance: Either Docker-based or manual install.
A Domain Name: You need a registered domain name (e.g., seafile.yourdomain.com) pointing to your server's public IP address via DNS A or AAAA records. Using an IP address for HTTPS is difficult and not recommended.

Nginx Installed:

sudo apt update
sudo apt install -y nginx

Certbot Installed: For obtaining Let's Encrypt SSL certificates.
```
sudo apt install -y certbot python3-certbot-nginx
```
Firewall Configured: Ensure ports 80 (for HTTP challenge) and 443 (for HTTPS) are open on your server's firewall.
```
sudo ufw allow 'Nginx Full' # Allows both port 80 and 443
sudo ufw status # Verify rules
```

Configuration Steps

Stop Direct Seafile Web Access (If Applicable):
- Docker: If you exposed port 80 in your docker-compose.yml (ports: - "80:80"), you should remove or comment out this mapping, as Nginx will now handle port 80 on the host. You don't want both Nginx and the Seafile container trying to bind to the same host port.
```
# In docker-compose.yml under 'seafile' service:
# ports:
#  - "80:80" # Comment this out or remove it
```
  After editing, run sudo docker compose up -d to apply the change (it will recreate the Seafile container without the port mapping).
- Manual Install: You are likely already running Seahub on port 8000, which is fine as Nginx will proxy to it internally. Ensure no other service is using port 80 or 443 on the host.
Configure seahub_settings.py for HTTPS:
- Edit your seahub_settings.py file (/opt/seafile-docker/seafile-data/seafile/conf/seahub_settings.py or /opt/seafile/conf/seahub_settings.py).
- Update SERVICE_URL and FILE_SERVER_ROOT to use https. Replace seafile.yourdomain.com with your actual domain.
```
# Use HTTPS now!
SERVICE_URL = "https://seafile.yourdomain.com"
FILE_SERVER_ROOT = SERVICE_URL + '/seafhttp'

# Optional but recommended when behind a proxy:
# Tell Django/Seahub it's behind a secure proxy
SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https')
USE_X_FORWARDED_HOST = True
```
- Save the file. Restart Seahub if needed (Docker restart handles this).

Create Nginx Configuration File:

Create a new Nginx configuration file for your Seafile site. Replace seafile.yourdomain.com with your domain.
```
sudo nano /etc/nginx/sites-available/seafile.yourdomain.com.conf
```

Paste the following configuration, adjusting paths and domain names:

# Nginx configuration for Seafile with HTTPS (Let's Encrypt)

server {
    # Listen on port 80 for HTTP requests
    listen 80;
    listen [::]:80;
    # IMPORTANT: Replace with your actual domain name
    server_name seafile.yourdomain.com;

    # Redirect all HTTP traffic to HTTPS
    location / {
        return 301 https://$host$request_uri;
    }

    # Location for Let's Encrypt ACME challenge verification
    location /.well-known/acme-challenge/ {
        root /var/www/html; # Or another webroot Nginx has access to
    }
}

server {
    # Listen on port 443 for HTTPS requests
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    # IMPORTANT: Replace with your actual domain name
    server_name seafile.yourdomain.com;

    # SSL Certificate paths (Certbot will manage these later)
    # Initially, you might use self-signed certs for testing,
    # but we'll let Certbot handle the real ones.
    ssl_certificate /etc/letsencrypt/live/seafile.yourdomain.com/fullchain.pem; # Managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/seafile.yourdomain.com/privkey.pem; # Managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # Recommended SSL parameters from Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # Recommended DH parameters from Certbot

    # Add security headers (optional but recommended)
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    add_header X-Content-Type-Options nosniff always;
    add_header X-Frame-Options SAMEORIGIN always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    # Proxy pass requests to the Seahub (Web UI) service
    # Seahub typically runs on port 8000 internally
    location / {
        proxy_pass         http://127.0.0.1:8000; # For manual install
        # proxy_pass         http://seafile:8000; # For Docker using service name 'seafile' (if networking allows)
                                            # Sometimes using the host's Docker IP (e.g. 172.x.0.1) is needed if networking setup is complex
        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-Host $server_name;
        proxy_set_header   X-Forwarded-Proto https; # Let Seahub know connection is HTTPS
        proxy_read_timeout  1200s; # Increase timeout for large file uploads/downloads if needed

        # Required for WebSocket connections used by Seahub
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        client_max_body_size 0; # Allow large file uploads, set to 0 for unlimited or specific value like '2048m' for 2GB
        access_log      /var/log/nginx/seahub.access.log;
        error_log       /var/log/nginx/seahub.error.log;
    }

    # Proxy pass requests for file uploads/downloads to the Seafile File Server
    # Seafile file server runs on port 8082 internally
    location /seafhttp {
        rewrite ^/seafhttp(.*)$ $1 break; # Remove /seafhttp prefix before proxying
        proxy_pass http://127.0.0.1:8082; # For manual install
        # proxy_pass http://seafile:8082; # For Docker (check networking)
        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-Host $server_name;
        proxy_set_header   X-Forwarded-Proto https;
        client_max_body_size 0; # Allow large file uploads
        proxy_read_timeout  1200s; # Increase timeout
        proxy_connect_timeout 3600s; # Increase timeout
        proxy_send_timeout 3600s; # Increase timeout
        send_timeout 3600s; # Increase timeout

        access_log      /var/log/nginx/seafile.access.log;
        error_log       /var/log/nginx/seafile.error.log;
    }

    # Serve Seafile media files (CSS, JS, images) directly via Nginx for better performance
    # Adjust the 'alias' path based on your installation type and location
    location /media {
        # Manual Install Example (adjust path to your seahub/media):
        alias /opt/seafile/seafile-server-latest/seahub/media;

        # Docker Install Example:
        # This requires mapping the media volume from the container to the host
        # OR proxying media requests back to Seahub (less efficient).
        # A common Docker approach is to let Seahub serve media via the '/' location proxy pass,
        # or create a shared volume specifically for media if optimization is critical.
        # If proxying via '/', remove this separate /media location block.
        # If using a volume mount:
        # alias /path/on/host/mapped/to/container/media;
    }
}

Explanation & Adjustments:
- server_name: Replace seafile.yourdomain.com everywhere with your actual domain.
- proxy_pass (for /):
  - Manual Install: Use http://127.0.0.1:8000.
  - Docker: Try http://seafile:8000 (using the service name from docker-compose.yml). If that doesn't work due to Docker networking complexities, you might need to use the Docker host's IP within the Docker network (often 172.17.0.1 or similar, check with ip addr show docker0) or the main seafile container's IP (less reliable). Using 127.0.0.1:8000 won't work from the Nginx container (if Nginx is also Dockerized) or the host unless Seahub's port 8000 is mapped to the host, which isn't standard practice when using a reverse proxy. Using the Docker service name seafile is usually the cleanest approach if Nginx is running on the host.
- proxy_pass (for /seafhttp): Similar logic applies. Use http://127.0.0.1:8082 for manual or http://seafile:8082 for Docker.
- location /media:
  - Manual Install: Adjust the alias path to point exactly where the seahub/media directory is located in your Seafile server installation (e.g., /opt/seafile/seafile-server-9.0.10/seahub/media). Serving media directly via Nginx is much faster.
  - Docker: This is trickier. The simplest way is often to remove the entire /media location block. Nginx will then proxy requests for /media/... to Seahub via the main / location block. This works but is less performant. For optimal performance, you'd need to map the container's internal media volume to the host and set the alias here, or run Nginx itself in a container on the same Docker network. For simplicity now, just remove the /media block if using Docker.
- client_max_body_size 0;: Nginx defaults to a very small limit (1MB). Set to 0 for unlimited or a specific value like 2g or 2048m to match Seafile's potential limits.
- Timeouts: Increased timeouts are often necessary for reliable large file operations.
Save and close the file.

Enable the Nginx Site:

sudo ln -s /etc/nginx/sites-available/seafile.yourdomain.com.conf /etc/nginx/sites-enabled/
# Test Nginx configuration for syntax errors
sudo nginx -t
# If syntax is OK, reload Nginx to apply changes
sudo systemctl reload nginx

Obtain Let's Encrypt Certificate:
- Use Certbot with the Nginx plugin. Replace the email and domain name.
- bash sudo certbot --nginx -d seafile.yourdomain.com --email your-email@example.com --agree-tos --no-eff-email -n --redirect
- Explanation of Certbot flags:
  - --nginx: Use the Nginx plugin to automatically modify the Nginx config for SSL.
  - -d seafile.yourdomain.com: Specify the domain to get a certificate for.
  - --email your-email@example.com: Registration and recovery email.
  - --agree-tos: Agree to the Let's Encrypt Terms of Service.
  - --no-eff-email: Don't subscribe to EFF newsletter (optional).
  - -n: Run non-interactively.
  - --redirect: Automatically add the HTTP to HTTPS redirect in Nginx (our config already does this, but this flag reinforces it and is common practice).
- Certbot should automatically detect your server block, obtain the certificate, and update the Nginx configuration file (/etc/nginx/sites-available/seafile.yourdomain.com.conf) to include the correct ssl_certificate, ssl_certificate_key, and include directives. It will also reload Nginx.
Final Verification:
- Check Nginx status: sudo systemctl status nginx
- Test Nginx config again: sudo nginx -t
- Access your Seafile instance using https://seafile.yourdomain.com in your browser.
  - It should automatically redirect from HTTP if you try that.
  - You should see a valid padlock icon (no SSL warnings).
  - Log in and test basic functionality (uploading a small file, browsing folders) to ensure the proxy passes are working correctly. Check desktop client sync as well.

You now have Seafile running securely behind Nginx with HTTPS encryption! Remember that Let's Encrypt certificates expire every 90 days, but Certbot automatically sets up a systemd timer or cron job to handle renewal (sudo systemctl list-timers | grep certbot, sudo certbot renew --dry-run).

Workshop Setting Up Nginx and Let's Encrypt

Objective: To configure Nginx as a reverse proxy for an existing Seafile installation and secure it using a Let's Encrypt SSL certificate.

Prerequisites:

A running Seafile instance (Docker or Manual).
A registered domain name pointed to your server's public IP.
Nginx and Certbot installed (sudo apt install nginx certbot python3-certbot-nginx).
Ports 80 and 443 open in the firewall (sudo ufw allow 'Nginx Full').
Command-line access to the server with sudo.

Steps:

Update Seafile Configuration:
- Edit seahub_settings.py (/opt/seafile-docker/seafile-data/seafile/conf/seahub_settings.py or /opt/seafile/conf/seahub_settings.py).
- Change SERVICE_URL to https://your-seafile-domain.com.
- Ensure FILE_SERVER_ROOT is SERVICE_URL + '/seafhttp'.
- Add SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https') and USE_X_FORWARDED_HOST = True.
- Save the file.
- Restart Seafile services:
  - Docker: cd /opt/seafile-docker && sudo docker compose restart seafile
  - Manual: sudo -u seafile /opt/seafile/seafile-server-latest/seahub.sh restart (wait a bit)
Prepare Nginx Config:
- Create the Nginx config file: sudo nano /etc/nginx/sites-available/your-seafile-domain.com.conf
- Paste the example Nginx configuration provided in the section above.
- Crucially Adjust:
  - Replace seafile.yourdomain.com with your domain everywhere.
  - Set the correct proxy_pass URLs for / and /seafhttp based on your install type (e.g., http://127.0.0.1:8000 and http://127.0.0.1:8082 for manual, or http://seafile:8000 and http://seafile:8082 for Docker).
  - If using Docker, REMOVE the entire location /media { ... } block.
  - If using Manual Install, ensure the alias path in the location /media block points correctly to your seahub/media directory.
  - Set client_max_body_size 0; in both / and /seafhttp locations.
- Save the file (Ctrl+X, Y, Enter).
Enable Nginx Site & Test:
- Create the symbolic link: sudo ln -s /etc/nginx/sites-available/your-seafile-domain.com.conf /etc/nginx/sites-enabled/
- Test the configuration: sudo nginx -t. Fix any reported syntax errors in your .conf file.
- Reload Nginx: sudo systemctl reload nginx.
Obtain SSL Certificate:
- Run Certbot:
```
sudo certbot --nginx -d your-seafile-domain.com --email your-real-email@example.com --agree-tos --no-eff-email -n --redirect
```
  (Replace domain and email).
- Certbot should confirm success and that it has updated your Nginx config and reloaded Nginx.
Verify HTTPS Access:
- Open your web browser and navigate to https://your-seafile-domain.com.
- Check for a valid padlock icon in the address bar.
- Try accessing http://your-seafile-domain.com – it should automatically redirect to HTTPS.
- Log in to Seafile.
- Try uploading a small file.
- Try downloading the file.
- If using the desktop client, ensure it can still connect and sync using the new https:// URL (you might need to remove and re-add the account in the client).

Outcome: You have successfully placed your Seafile instance behind an Nginx reverse proxy, enabled HTTPS using Let's Encrypt, and verified basic functionality over the secure connection. Your Seafile setup is now significantly more secure and professional.

8. User Management and Permissions

Effectively managing users, groups, and permissions is crucial for organizing collaboration and controlling access to data within Seafile.

User Management (System Admin Panel)

Administrators manage users via the "System Admin" panel in the Seahub web interface.

Adding Users:
- If registration is disabled (recommended for controlled environments), go to System Admin -> Users -> + Add User.
- Provide Email (login username), optionally Name, Password, and Role (usually Default). Click Submit. You need to communicate the initial password to the user.
- Alternatively, use "Add Users in Batch" to upload a CSV file for creating multiple accounts.
Listing and Searching Users: The main Users page lists all users. You can search by email or name. Filter by status (Active/Inactive).
User Actions: Clicking on a username allows you to:
- View Info: See user details, quota usage, linked devices.
- Edit Profile: Change Name, Contact Email, Institution, etc.
- Change Password: Set a new password for the user.
- Set Quota: Define a storage limit for the user (e.g., 5 for 5GB, 0 or empty for unlimited). Requires editing seahub_settings.py to enable quotas (ENABLE_QUOTA_CHECK = True) and restarting services first.
- Manage Role: Change the user's role (e.g., grant/revoke Admin privileges).
- Manage Libraries: View libraries owned by the user, transfer ownership to another user (useful if someone leaves), or delete libraries.
- Manage Groups: See groups the user is a member of.
- View Links: See public sharing links created by the user.
- Linked Devices: See and unlink desktop/mobile clients connected to the account.
- Activate/Deactivate: Deactivated users cannot log in but their data remains. Useful for temporarily disabling access.
- Delete User: Permanently removes the user account and transfers their libraries to the admin (or prompts for deletion). Be cautious!

Group Management

Groups simplify sharing libraries and folders with multiple users simultaneously.

Creating Groups: Any user can create a group via the main Seahub interface (not just admins). Click the "Groups" tab -> "+ New Group". Give it a name.
Managing Groups (Admin): Admins can see and manage all groups via System Admin -> Groups.
- Clicking a group name allows viewing members, libraries shared with the group, and group settings.
- Admins can add/remove members from any group, rename groups, transfer group ownership, or delete groups.
Group Membership: Group owners (or admins) can add/remove members. Members can leave groups themselves.
Sharing with Groups: When sharing a library or folder, you can type the group name instead of individual user emails. All group members inherit the specified permission (read-only or read-write).

Library and Folder Permissions

Permissions control what actions users can perform on shared data.

Library Sharing:
- Owner clicks the "Share" icon on a library.
- Choose "Share to user" or "Share to group".
- Enter email address or group name.
- Select Permission:
  - Read-Write: User/group can view, download, modify, upload, delete files/folders within the shared library.
  - Read-Only: User/group can only view and download content. They cannot make changes.
  - (Pro Edition Feature) Online Read-Write/Read-Only: Allows editing via integrated online editors (like ONLYOFFICE) but potentially restricts direct download/sync (check specific version documentation).
Sub-folder Sharing:
- Navigate inside a library, hover over a folder, click "Share".
- Similar options: Share to user/group with Read-Write or Read-Only permissions.
- Permissions on sub-folders override parent library permissions only if they are more restrictive or grant access where none existed. A user with read-only access to the library cannot get read-write access to a sub-folder via sub-folder sharing alone. However, someone without access to the library can be granted access to only a specific sub-folder.
Public Sharing Links:
- Generate download or upload links for files or folders.
- Permissions:
  - Download Links: Can be view-only (for supported file types like PDF, images, videos, text) or download-only. Pro edition might offer more granular controls like disabling download but allowing online viewing.
  - Upload Links: Only allow uploading files into the target folder.
- Security: Always consider setting passwords and expiration dates on public links, especially for sensitive data. Admins can view/delete all public links via System Admin -> Links.

Roles

Seafile has a basic role system:

Default (User): Standard user permissions described above.
Admin: Full control over the system via the System Admin panel. Can manage all users, groups, libraries, settings.
(Pro Edition) Guest: A limited role, typically cannot create libraries, only access items shared with them. Useful for external collaborators.

Understanding these layers – user accounts, group aggregation, and granular permissions on libraries/folders/links – allows you to tailor Seafile access precisely to your collaboration needs.

Workshop Managing Users, Groups, and Shares

Objective: To practice creating users, organizing them into groups, and sharing libraries and folders with different permissions.

Prerequisites:

A running Seafile instance with Nginx/HTTPS configured.
Logged in as the administrator.
Ability to log in as other users (you'll create them). Either use different browsers, private windows, or log out/in.

Steps:

Create Test Users:
- Go to System Admin -> Users.
- Click + Add User. Create two users:
  - User 1: user1@yourdomain.com, Password: TestPass123!
  - User 2: user2@yourdomain.com, Password: TestPass456!
- Click "Submit" after each. Verify they appear in the user list.
Create a Group:
- Log out from the admin account.
- Log in as user1@yourdomain.com (Password: TestPass123!).
- Navigate to the "Groups" tab on the left.
- Click + New Group. Name it "Project Alpha". Click "Submit".
- You are now the owner of "Project Alpha". Click on its name.
- Click "Members" -> "+ Add Member". Enter user2@yourdomain.com. Click "Submit".
- You should see user1 (Owner) and user2 (Member).
- Log out from user1.
Create and Share a Library (Read-Write to Group):
- Log back in as admin.
- Go to "My Libraries". Click + New Library. Name it "Admin Shared RW". Submit.
- Hover over "Admin Shared RW" and click "Share".
- Select "Share to group". Start typing "Project Alpha". Select the group.
- Ensure "Permission" is set to "Read-Write". Click "Submit".
Create and Share a Library (Read-Only to User):
- Create another library named "Admin Shared RO".
- Hover over "Admin Shared RO" and click "Share".
- Select "Share to user". Enter user1@yourdomain.com.
- Change "Permission" to "Read-Only". Click "Submit".
Verify Access and Permissions (User 1):
- Log out from admin. Log in as user1@yourdomain.com.
- Go to the "Shared with me" section.
- You should see "Admin Shared RW" (shared via the group) and "Admin Shared RO".
- Click on "Admin Shared RW". Try creating a new folder inside it (e.g., "+ New" -> "New Folder"). This should work because of Read-Write permission.
- Go back. Click on "Admin Shared RO". Try creating a new folder. This should fail or the option should be greyed out due to Read-Only permission. Try uploading a file - it should also fail.
Verify Access and Permissions (User 2):
- Log out from user1. Log in as user2@yourdomain.com (Password: TestPass456!).
- Go to "Shared with me".
- You should only see "Admin Shared RW" (shared via the group). You should not see "Admin Shared RO".
- Click on "Admin Shared RW". Try creating a new folder. This should work. Upload a small file.
Share a Sub-folder:
- Log out from user2. Log back in as admin.
- Go into the "Admin Shared RW" library. Create a folder named "Sensitive Docs".
- Hover over "Sensitive Docs" and click "Share".
- Select "Share to user". Enter user1@yourdomain.com.
- Set Permission to "Read-Only". Click "Submit". (Note: Even though User1 has RW access to the library via the group, we are adding a more specific, restrictive permission for this user on this sub-folder).
Verify Sub-folder Permissions:
- Log out from admin. Log in as user1@yourdomain.com.
- Go to "Shared with me" -> "Admin Shared RW".
- Try creating a file in the root of "Admin Shared RW". This should work.
- Enter the "Sensitive Docs" folder. Try creating a new folder or uploading a file inside "Sensitive Docs". This should fail because the specific Read-Only permission for user1 on this sub-folder takes precedence over the group's Read-Write permission on the parent library.
- Log out from user1. Log in as user2@yourdomain.com.
- Go to "Shared with me" -> "Admin Shared RW" -> "Sensitive Docs".
- Try creating a file inside "Sensitive Docs". This should work because user2 only inherits the Read-Write permission from the group share on the library, and there's no specific overriding permission for user2 on the sub-folder.

Outcome: You have practiced creating users, adding them to groups, sharing libraries with different permissions (Read-Write, Read-Only) to both users and groups, and observed how specific sub-folder permissions can override broader library permissions. This demonstrates effective control over data access in a collaborative environment.

9. Desktop Client Advanced Features

While the basic function of the Seafile desktop client is straightforward synchronization, it offers several advanced features that enhance usability, save disk space, and provide more control. These features are primarily accessed through the client's main interface or by right-clicking on synced libraries or folders in your file explorer.

Selective Sync (Cloud File Browser)

This is one of the most powerful features for managing local disk space while still having access to all your files.

Concept: When you initially sync a library, the client downloads all its contents. Selective Sync allows you to keep the library synced (meaning changes are still tracked and uploaded/downloaded for selected parts) but choose specific sub-folders to download locally. Other folders remain "cloud-only" but are still visible in a special view.
How it Works (Typical Implementation):
1. Sync Library: First, sync the library normally (it might initially download everything).
2. Right-Click: In your computer's file explorer (Windows Explorer, macOS Finder, Linux File Manager), navigate inside the synced library folder.
3. "Seafile" Context Menu: Right-click on a sub-folder within the library. You should see a "Seafile" or similar context menu entry provided by the client integration.
4. "Sync this folder" / "Unsync this folder":
  - If a folder is currently fully downloaded ("synced"), choosing "Unsync this folder" (or similar wording like "Free up space") will remove the local copies of the files inside that folder but keep the folder itself as a placeholder. The files still exist on the server and other synced devices. The folder icon might change to indicate it's cloud-only.
  - If a folder is currently "unsynced" (cloud-only placeholder), choosing "Sync this folder" (or similar wording like "Always keep on this device") will download its contents locally.
Client Interface View: The main Seafile client window often provides a "Cloud File Browser" view. This lets you navigate the entire structure of a synced library (even the cloud-only parts) directly from the client interface. You can right-click folders here to choose whether to sync them locally or keep them cloud-only. You can also directly open cloud-only files (which downloads them temporarily).
Benefits: Drastically saves local disk space, especially with very large libraries, while still allowing you to browse the full structure and download specific items on demand. Essential for laptops or machines with limited storage.

Unsyncing a Library

This is different from Selective Sync. Unsyncing removes the library entirely from your local computer and stops the client from tracking its changes.

How it Works:
1. Open the main Seafile desktop client window.
2. Find the library you want to stop syncing.
3. Right-click on the library name or click a settings icon associated with it.
4. Choose the "Unsync" option.
5. The client will ask for confirmation. Confirming will delete the local folder and all its contents (make sure you don't need any unsaved local changes!) and stop any future synchronization for this library on this computer.
Result: The library disappears from your local Seafile folder and the client's list of actively synced libraries. It still exists on the server and can be synced again later if needed.
Use Cases: Use this when you no longer need ongoing access to a library on a particular machine or want to completely remove its local footprint.

Syncing with Existing Folder

Sometimes, you might already have a folder on your computer that contains the same files as a library on the Seafile server (perhaps you copied them manually before deciding to use Seafile, or you're setting up sync on a new machine where you previously downloaded the data). Instead of downloading everything again, you can attempt to sync the server library with your existing local folder.

How it Works:
1. When you first choose to sync a library in the client, instead of accepting the default location, click the option to "Choose" or "Select" a different folder.
2. Navigate to and select the existing folder on your computer that you believe matches the library content.
3. The client will warn you that it needs to merge the server content with the local folder.
4. Process: The client will scan the local folder and compare its contents (files, timestamps, potentially hashes) with the server's version of the library.
  - Files that match on both sides are recognized, and no transfer occurs.
  - Files only on the server are downloaded.
  - Files only in the local folder are typically uploaded to the server.
  - Files that exist in both places but differ might create conflicts (saved as "conflicting copy") or be resolved based on timestamps (newer usually wins, but this can be complex).
Caution: This can be risky if the local folder and the server library are significantly different. It might lead to unintended uploads, downloads, or conflicts. It's often safer, though slower, to sync to a new empty folder and then manually copy any extra local files into that synced folder afterwards, letting Seafile handle the upload. Use "Sync with existing folder" carefully, ideally when you are confident the contents are very similar.

Controlling Sync Intervals and Bandwidth

Settings: Access the client's settings/preferences dialog.
Sync Interval: Some clients may allow adjusting how frequently they check the server for changes (though real-time sync via notifications is often used). Longer intervals might save minimal resources but delay sync.
Bandwidth Limits: Crucially, you can often set limits on upload and download speeds. This is useful if Seafile syncing saturates your internet connection, impacting other activities like browsing or streaming. Set limits in KB/s or MB/s. Setting 0 usually means unlimited.

Mastering these advanced client features allows for a much more tailored and efficient synchronization experience, adapting Seafile to your specific storage constraints and network conditions.

Workshop Using Advanced Client Features

Objective: To practice using Selective Sync to manage local storage and observe the "Sync with existing folder" behavior.

Prerequisites:

Seafile Desktop Client installed and connected to your account.

A library on the server with several files and at least one sub-folder containing more files. Create one if needed (e.g., "Large Library Test").

Example structure:

Large Library Test/
├── report.docx
├── image1.jpg
├── presentation.pptx
└── Project Data/
    ├── data_file_a.csv
    ├── data_file_b.csv
    └── archive.zip

Part 1: Selective Sync

Sync the Library:
- In the Seafile client, find "Large Library Test" (or your equivalent).
- Click "Download and Sync". Choose the default local path.
- Wait for the initial sync to complete (green checkmark).
Verify Full Download:
- Open the local "Large Library Test" folder in your file explorer.
- Verify that all files (report.docx, image1.jpg, presentation.pptx) and the "Project Data" sub-folder (with its contents) are present locally.
Unsync a Sub-folder (Make Cloud-Only):
- Navigate into the local "Large Library Test" folder.
- Right-click on the "Project Data" sub-folder.
- Find the "Seafile" context menu. Select the option similar to "Free up space" or "Unsync this folder".
- Confirm if prompted.
Observe Changes:
- The icon for the "Project Data" folder should change (e.g., showing a cloud symbol).
- Try to open the "Project Data" folder. Its contents (data_file_a.csv, etc.) should be gone from the local disk. (Some OS integrations might still show them as placeholders).
- Check the available disk space on your drive; it should have increased slightly (depending on the size of the files in "Project Data").
- The files in the root of "Large Library Test" (report.docx, etc.) should still be present locally.
Browse via Client:
- Open the main Seafile client window.
- Find "Large Library Test". There might be a "Cloud File Browser" button or similar.
- Use the Cloud File Browser to navigate into "Large Library Test" and then into "Project Data". You should be able to see the filenames (data_file_a.csv, etc.) even though they aren't stored locally.
Re-Sync the Sub-folder:
- Option 1 (File Explorer): Right-click the cloud-only "Project Data" folder -> Seafile -> "Sync this folder" or "Always keep on this device".
- Option 2 (Client Cloud Browser): Right-click the "Project Data" folder in the client's browser and choose a similar sync option.
- Wait for the files inside "Project Data" to download again. Verify they reappear in your local file explorer.

Part 2: Sync with Existing Folder (Demonstration)

Create a Local Folder: On your Desktop or another location outside your main Seafile sync folder, create a new folder named "Local Copy".
Copy Some Files: Copy one file from your local "Large Library Test" folder (e.g., report.docx) into the "Local Copy" folder.
Create a New File: Inside the "Local Copy" folder, create a new text file named local_only.txt with some content.
Unsync the Original Library: In the Seafile client, right-click "Large Library Test" and choose "Unsync". Confirm. Verify the local "Large Library Test" folder is deleted.
Initiate Sync with Existing:
- In the Seafile client, find "Large Library Test" again. Click "Download and Sync".
- Crucially: When prompted for the location, click "Choose" or "Select Folder".
- Navigate to and select the "Local Copy" folder you created on your Desktop.
- The client will likely warn about merging. Proceed with caution (click "OK" or "Sync").
Observe Merge Behavior:
- Watch the client's transfer progress and file activity.
- Once synced (green checkmark), open the "Local Copy" folder.
- Expected Result:
  - report.docx: Should still be there. The client likely recognized it matched the server version and didn't re-download it.
  - image1.jpg, presentation.pptx, Project Data/: These should have been downloaded from the server because they weren't in "Local Copy" initially.
  - local_only.txt: This file, which only existed locally, should have been uploaded to the server.
Verify on Web: Log in to Seahub, navigate to "Large Library Test", and verify that local_only.txt now appears there alongside the other files.

Outcome: You have successfully used Selective Sync to control which parts of a library are stored locally, saving disk space. You have also simulated the "Sync with existing folder" scenario and observed how Seafile merges local and server content, highlighting both its utility and the need for caution.

Advanced

This section explores sophisticated topics for experienced users aiming to optimize, secure, integrate, and maintain a production-ready Seafile installation.

10. Performance Tuning and Scaling

As your Seafile usage grows (more users, larger files, more frequent syncs), performance can become a bottleneck. Tuning various components can significantly improve responsiveness and throughput.

Caching with Memcached

Purpose: Seahub (the web interface) involves database queries and rendering web pages. Memcached is an in-memory key-value store used to cache frequently accessed data (like user sessions, settings, file lists, avatars), reducing database load and speeding up web UI responses.

Verification: Ensure Memcached is running and configured correctly in seahub_settings.py.

Docker: The provided docker-compose.yml includes a Memcached service and configures Seahub to use it (LOCATION': 'memcached:11211'). Verify the memcached container is running (docker compose ps).

Manual Install: Install Memcached (sudo apt install memcached), ensure it's running (sudo systemctl status memcached), and configure seahub_settings.py to point to it (LOCATION': '127.0.0.1:11211').

# In seahub_settings.py
CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
        'LOCATION': '127.0.0.1:11211', # Or 'memcached:11211' for Docker
    },
    # Optional separate avatar cache
    'avatar': {
         'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
         'LOCATION': '127.0.0.1:11211', # Or 'memcached:11211'
         'OPTIONS': {
             'MAX_ENTRIES': 1000 # Limit entries if needed
         }
     },
}

Tuning Memcached: The primary tuning parameter is memory allocation. The default might be 64MB. Increase it if you have many users or extensive usage.
- Docker: Modify the entrypoint in docker-compose.yml: entrypoint: memcached -m 256 (for 256MB). Then docker compose up -d --force-recreate memcached.
- Manual Install: Edit the Memcached config file (e.g., /etc/memcached.conf) and change the -m value. Restart Memcached (sudo systemctl restart memcached). Monitor memory usage.

Seahub Concurrency (Gunicorn Workers)

Problem: The default seahub.sh start uses a single-process Python development server. For production, Seahub should be run using a proper WSGI HTTP server like Gunicorn (which is included with Seafile). Gunicorn can handle multiple incoming web requests concurrently using multiple worker processes.
Configuration (Manual Install with Nginx/Apache):
1. Stop Development Server: If Seahub is running via seahub.sh start, stop it: sudo -u seafile /opt/seafile/seafile-server-latest/seahub.sh stop.
2. Start with Gunicorn: Use a command like this (adjust paths, user, port):
```
sudo -u seafile /opt/seafile/seafile-server-latest/seahub.sh start-gunicorn # Old way, might still work
# OR more explicit Gunicorn command (preferred, adjust paths/user):
sudo -u seafile /usr/bin/python3 /opt/seafile/seafile-server-latest/seahub/thirdpart/gunicorn \
    --workers=5 \
    --threads=4 \
    --bind=127.0.0.1:8000 \
    --pid=/opt/seafile/pids/seahub_gunicorn.pid \
    --access-logfile=/opt/seafile/logs/gunicorn.access.log \
    --error-logfile=/opt/seafile/logs/gunicorn.error.log \
    --log-level=info \
    seahub.wsgi:application
```
  - --workers: The number of worker processes. A common starting point is (2 * number_of_cpu_cores) + 1. Monitor CPU/RAM usage and adjust. Too many workers can exhaust resources.
  - --threads: (Optional, for Gunicorn's gthread worker type) Number of threads per worker. Useful if workers spend time waiting for I/O. Requires careful tuning. Default workers use single thread.
  - --bind: IP and port Gunicorn should listen on. This should match what your Nginx/Apache proxy_pass directive points to (e.g., 127.0.0.1:8000).
  - Log files: Specify paths for access and error logs. Ensure the seafile user can write to /opt/seafile/logs and /opt/seafile/pids.
3. Systemd Service: Create a systemd service file (/etc/systemd/system/seahub.service) to manage the Gunicorn process reliably (start on boot, restart on failure). See Seafile manual or online examples for creating this service file.
Configuration (Docker): The official Docker image usually runs Seahub with Gunicorn by default. You can often control the number of workers via environment variables in docker-compose.yml:
```
# In docker-compose.yml under seafile service environment:
environment:
  # ... other variables ...
  # Set the number of Gunicorn workers (adjust value based on your server cores/RAM)
  SEAFILE_WEB_WORKERS: 5
```
Then run sudo docker compose up -d --force-recreate seafile. Check the container logs to confirm the number of workers started.

Seafile File Server Workers (seaf-server)

Purpose: The seaf-server process handles file uploads, downloads, and internal sync operations. By default, it might run with a limited number of worker threads.

Configuration: Edit seafile.conf (/opt/seafile/conf/seafile.conf or mapped Docker path). Add or modify the [fileserver] section:

[fileserver]
port = 8082
# Number of worker threads for handling file transfers.
# Default is often low (e.g., 3 or 5). Increase based on expected concurrent transfers and server cores.
# Don't set it excessively high, as it consumes resources. Start by doubling the default and monitor.
worker_threads = 10

Restart: Restart the Seafile server process after changing this:
- Docker: sudo docker compose restart seafile
- Manual: sudo -u seafile /opt/seafile/seafile-server-latest/seafile.sh restart

Database Optimization

Indexing: Ensure the Seafile databases (ccnet-db, seafile-db, seahub-db) have appropriate indexes. The setup script usually creates necessary indexes, but checking periodically or after major upgrades is wise. Tools like mysqltuner or pgtune can provide general database tuning advice.
Connection Pool: Seafile components manage their own database connections. Ensure the database server itself is configured to handle the expected number of connections from Ccnet, Seahub (multiple workers), and seaf-server. Check max_connections in your MySQL/PostgreSQL configuration.
Query Caching (Database Level): While application-level caching (Memcached for Seahub) is preferred, some database-level query caching might help, but can also have overhead. Consult DB-specific tuning guides.
Hardware: Ensure the database server has sufficient RAM (to hold indexes and working sets in memory), fast disk I/O (SSDs are highly recommended), and adequate CPU power. If Seafile and the DB are on the same machine, resource contention can occur. Consider a dedicated DB server for large deployments.

Filesystem Considerations

Storage: Use fast storage (SSDs preferred over HDDs) for the Seafile data directory (/opt/seafile-data or the Docker volume path), especially for the block storage itself.
Filesystem Choice: Standard Linux filesystems like ext4 or XFS are generally fine. Ensure sufficient inodes are available if you expect millions of small files.
Regular Cleanup: Encourage users to empty library trash periodically. Configure automatic cleanup of old trash items in seafile.conf ([history] section, keep_days setting).

Monitoring

System Resources: Monitor CPU, RAM, disk I/O, and network usage on the Seafile server and database server (if separate). Tools like htop, iotop, nethogs, vmstat, or integrated monitoring solutions (Prometheus/Grafana, Zabbix) are essential.
Seafile Logs: Regularly check Seafile logs (seafile.log, controller.log, seahub.log, gunicorn.access.log, gunicorn.error.log, etc.) for errors or performance warnings.
Database Logs: Check MySQL/PostgreSQL logs for slow queries or errors.

Scaling Seafile is an iterative process. Start with sensible defaults, monitor performance under load, identify bottlenecks (CPU, RAM, disk, network, database, specific Seafile component), and tune accordingly. Increase workers, allocate more RAM to caches/databases, or upgrade hardware as needed.

Workshop Tuning Gunicorn Workers (Docker)

Objective: To adjust the number of Seahub Gunicorn workers in a Docker deployment and observe the potential impact (conceptual, as actual impact depends on load).

Prerequisites:

Seafile running via the standard Docker Compose setup.
Access to the server command line with sudo.
docker compose command available.

Steps:

Check Current Configuration (Optional but informative):

Look inside the running Seafile container to see the Gunicorn process. First, find the container name/ID:
```
sudo docker compose ps
# Note the name listed for the 'seafile' service (e.g., 'seafile')
```

Execute ps aux inside the container to list processes. Look for Gunicorn processes.

sudo docker compose exec seafile ps aux | grep gunicorn
# You might see a master process and several worker processes. Count the workers.
# Example Output might show '/usr/bin/python3 /opt/seafile/.../gunicorn ... seahub.wsgi:application' processes

Alternatively, check the container logs shortly after startup, which often mention the number of workers:
```
sudo docker compose logs seafile | grep 'Booting worker'
```

Edit docker-compose.yml:

Navigate to the directory containing your docker-compose.yml file (e.g., /opt/seafile-docker).
Edit the file: sudo nano docker-compose.yml
Locate the environment: section under the seafile: service.

Add or modify the SEAFILE_WEB_WORKERS variable. Let's increase it (or decrease it if it was already high). Choose a sensible number based on your CPU cores (e.g., if you have 4 cores, try 5 or 9).

services:
  # ... db, memcached ...
  seafile:
    # ... image, container_name, ports, volumes ...
    environment:
      # ... DB_HOST, DB_ROOT_PASSWD, SEAFILE_SERVER_HOSTNAME, etc ...
      TZ: 'Etc/UTC'
      # --- Set Gunicorn Workers ---
      SEAFILE_WEB_WORKERS: 9 # Set your desired number here
    depends_on:
      # ...
    networks:
      # ...
    restart: unless-stopped
# ... networks ...

Save the file (Ctrl+X, Y, Enter).

Apply Changes and Recreate Container:
- Use docker compose up -d which will detect the configuration change and recreate only the seafile container:
```
sudo docker compose up -d --force-recreate seafile
# The --force-recreate flag ensures the container restarts with the new environment variable
```
- Wait for the container to start fully.

Verify the Change:

Re-check the container logs for the worker count:

sudo docker compose logs seafile | grep 'Booting worker'
# You should see log lines corresponding to the new number of workers.

Or, re-run the process check inside the container:

sudo docker compose exec seafile ps aux | grep gunicorn
# Count the 'seahub.wsgi:application' worker processes. It should match SEAFILE_WEB_WORKERS.

Observe (Conceptual):
- While you might not see a difference without load testing, understand the implications:
  - More Workers: Can handle more simultaneous web requests to Seahub (browsing files, checking notifications, etc.). May increase CPU and RAM usage. Could improve UI responsiveness under heavy load.
  - Fewer Workers: Consumes less CPU/RAM. Might lead to slower UI responses or timeouts if many users access the web interface concurrently.
- Use browser developer tools (Network tab) to monitor page load times before and after the change, though this requires actual user load to be meaningful.

Outcome: You have successfully adjusted the number of Seahub Gunicorn workers within the Docker environment by modifying the docker-compose.yml file and recreating the container. You understand that this setting controls the concurrency of the web interface and how to verify the change.

11. Backup and Recovery Strategies

Data loss is unacceptable. A robust backup and recovery strategy is non-negotiable for any self-hosted service, especially one holding valuable files like Seafile. A complete Seafile backup involves backing up both the database metadata and the actual file data blocks.

Components to Back Up

Databases:
- ccnet-db: User and group information.
- seafile-db: Library metadata, file structures, sync status.
- seahub-db: Web UI settings, user profiles, sharing links, activity logs.
- Method: Use standard database dump tools (mysqldump for MySQL/MariaDB, pg_dump for PostgreSQL).
Seafile Data Directory:
- This directory contains the actual file content, stored as versioned blocks, library history, and other essential server data.
- Location:
  - Docker: The host directory mapped to /shared inside the container (e.g., /opt/seafile-docker/seafile-data).
  - Manual Install: The directory specified during setup-seafile-mysql.sh (e.g., /opt/seafile-data).
- Method: Filesystem-level backup using tools like rsync, tar, or specialized backup software. Crucially, Seafile services should ideally be stopped during this file backup to ensure data consistency.
Configuration Files:
- The contents of the conf directory (e.g., /opt/seafile/conf or /opt/seafile-docker/seafile-data/seafile/conf). This includes ccnet.conf, seafile.conf, seahub_settings.py, avatars, custom CSS/logos, etc.
- Method: Simple file copy (cp, rsync, tar). These change infrequently, but backing them up is vital for restoring your exact setup.
Nginx/Web Server Configuration (If Applicable):
- Your Nginx site configuration file (e.g., /etc/nginx/sites-available/seafile.yourdomain.com.conf).
- Let's Encrypt certificates (/etc/letsencrypt/). Certbot usually handles renewal, but backing up /etc/letsencrypt provides an extra safety net.
- Method: File copy.
docker-compose.yml (If Applicable):
- The docker-compose.yml file itself defines your container setup.
- Method: File copy.

Backup Procedure (Example: Manual Install with MariaDB)

Important: Schedule this procedure to run regularly (e.g., nightly) using cron.

Stop Seafile Services: This ensures data consistency, especially for the file data.

sudo -u seafile /opt/seafile/seafile-server-latest/seahub.sh stop
sudo -u seafile /opt/seafile/seafile-server-latest/seafile.sh stop
# Wait a few seconds to ensure they fully stop

Backup Databases: (Replace YOUR_SEAFILE_DB_PASSWORD and adjust backup path)

BACKUP_DIR="/mnt/backup/seafile/$(date +%Y-%m-%d_%H-%M-%S)"
sudo mkdir -p "$BACKUP_DIR/database"

sudo mysqldump --user=seafile --password='YOUR_SEAFILE_DB_PASSWORD' --host=localhost --databases ccnet-db > "$BACKUP_DIR/database/ccnet-db.sql"
sudo mysqldump --user=seafile --password='YOUR_SEAFILE_DB_PASSWORD' --host=localhost --databases seafile-db > "$BACKUP_DIR/database/seafile-db.sql"
sudo mysqldump --user=seafile --password='YOUR_SEAFILE_DB_PASSWORD' --host=localhost --databases seahub-db > "$BACKUP_DIR/database/seahub-db.sql"

# Verify dumps were created and have size > 0
ls -l "$BACKUP_DIR/database/"

Backup Seafile Data Directory: (Use rsync for efficiency after the first backup)

# Ensure SEAFILE_DATA_DIR points to your actual data path (e.g., /opt/seafile-data)
SEAFILE_DATA_DIR="/opt/seafile-data"
sudo rsync -az --delete "$SEAFILE_DATA_DIR/" "$BACKUP_DIR/data/"
# '--delete' removes files from backup if they were deleted from source

Alternatively, use tar for a single archive file:

# sudo tar czf "$BACKUP_DIR/data/seafile-data.tar.gz" -C "$(dirname "$SEAFILE_DATA_DIR")" "$(basename "$SEAFILE_DATA_DIR")"

Backup Configuration Files:

# Ensure SEAFILE_INSTALL_DIR points to your installation path (e.g., /opt/seafile)
SEAFILE_INSTALL_DIR="/opt/seafile"
sudo mkdir -p "$BACKUP_DIR/config"
sudo cp -a "$SEAFILE_INSTALL_DIR/conf" "$BACKUP_DIR/config/"
# Optionally back up entire install dir if small, but conf is critical
# sudo cp -a "$SEAFILE_INSTALL_DIR/seafile-server-latest" "$BACKUP_DIR/config/" # Includes scripts too

Restart Seafile Services:

sudo -u seafile /opt/seafile/seafile-server-latest/seafile.sh start
sudo -u seafile /opt/seafile/seafile-server-latest/seahub.sh start-gunicorn # Or your Gunicorn command / systemd start

Backup Other Configs (Optional but Recommended):

# Backup Nginx config
sudo cp -a /etc/nginx/sites-available/seafile.yourdomain.com.conf "$BACKUP_DIR/config/"
# Backup Let's Encrypt (large, do less frequently or rely on certbot renewal)
# sudo cp -aL /etc/letsencrypt "$BACKUP_DIR/config/" # -L follows symlinks

Store Backups Securely:
- Ensure the BACKUP_DIR (/mnt/backup/seafile in the example) is on a separate physical disk or remote storage (e.g., NFS mount, cloud storage via rclone). Backups on the same disk as the original data are useless if the disk fails.
- Implement a rotation policy (e.g., keep daily backups for a week, weekly for a month, monthly for a year) to manage storage space.
- Consider encrypting backups, especially if stored off-site.

Backup Procedure (Docker)

The principle is the same: stop services, back up DBs, back up data volumes, back up config volumes.

Stop Seafile Container:

cd /opt/seafile-docker # Directory with docker-compose.yml
sudo docker compose stop seafile # Stop only Seafile first to let DB finish writes potentially
# Wait a few seconds...
sudo docker compose stop # Stop db and memcached too

Backup Database Volume: Access the volume data on the host.

BACKUP_DIR="/mnt/backup/seafile/$(date +%Y-%m-%d_%H-%M-%S)"
sudo mkdir -p "$BACKUP_DIR/database_volume"
sudo rsync -az --delete /opt/seafile-docker/mysql-data/ "$BACKUP_DIR/database_volume/"
# Alternatively, exec mysqldump inside the running container before stopping (more complex script)

Backup Seafile Data Volume:

sudo mkdir -p "$BACKUP_DIR/data_volume"
sudo rsync -az --delete /opt/seafile-docker/seafile-data/ "$BACKUP_DIR/data_volume/"

Backup docker-compose.yml:

sudo cp /opt/seafile-docker/docker-compose.yml "$BACKUP_DIR/"

Restart Containers:
```
sudo docker compose start
```

Recovery Procedure (Example: Manual Install Disaster Recovery)

Assume the entire server is lost, and you have a new server prepared with the OS, necessary packages (Nginx, MariaDB, Python deps), and your backups available (e.g., mounted at /mnt/restore).

Restore Database:

Install MariaDB, run mysql_secure_installation.
Create the seafile user and the three databases (ccnet-db, seafile-db, seahub-db) just like in the initial setup.

Import the SQL dumps:

RESTORE_DIR="/mnt/restore/seafile/LATEST_BACKUP_DATE/database" # Point to specific backup
sudo mysql -u seafile -p'YOUR_SEAFILE_DB_PASSWORD' ccnet-db < "$RESTORE_DIR/ccnet-db.sql"
sudo mysql -u seafile -p'YOUR_SEAFILE_DB_PASSWORD' seafile-db < "$RESTORE_DIR/seafile-db.sql"
sudo mysql -u seafile -p'YOUR_SEAFILE_DB_PASSWORD' seahub-db < "$RESTORE_DIR/seahub-db.sql"

Restore Seafile Data:

Create the target data directory (e.g., /opt/seafile-data).

Restore the data using rsync:

RESTORE_DIR="/mnt/restore/seafile/LATEST_BACKUP_DATE/data"
sudo rsync -az "$RESTORE_DIR/" /opt/seafile-data/

Restore Seafile Installation/Configuration:
- Download the exact same version of Seafile Server that was running when the backup was made. Extract it (e.g., to /opt/seafile/seafile-server-X.Y.Z). Create the seafile-server-latest symlink.
- Restore the backed-up conf directory:
```
RESTORE_DIR="/mnt/restore/seafile/LATEST_BACKUP_DATE/config"
sudo cp -a "$RESTORE_DIR/conf" /opt/seafile/
```
- Crucially: Edit the restored config files (/opt/seafile/conf/*.conf, seahub_settings.py) and update any server-specific details if the new server has a different IP, hostname, or DB password than the original. Double-check database connection settings and SERVICE_URL/FILE_SERVER_ROOT.
Set Permissions: Create the seafile user/group if needed and set correct ownership for /opt/seafile, /opt/seafile-data, /opt/seafile/logs, /opt/seafile/pids.
```
sudo adduser --system --group --no-create-home seafile # If not exists
sudo chown -R seafile:seafile /opt/seafile /opt/seafile-data
```
Restore Nginx/SSL (If Applicable):
- Copy the Nginx site config back to /etc/nginx/sites-available/ and enable it (ln -s ...).
- Restore the /etc/letsencrypt directory from backup or run Certbot again to get new certificates for the domain (often easier if IP changed).
- Test Nginx config (nginx -t) and reload (systemctl reload nginx).

Start Services:

sudo -u seafile /opt/seafile/seafile-server-latest/seafile.sh start
sudo -u seafile /opt/seafile/seafile-server-latest/seahub.sh start-gunicorn # Or your systemd service

Test Thoroughly: Access via browser, log in, check libraries, upload/download, check desktop client sync.

Recovery from Docker backups follows a similar logic: restore host volumes, restore docker-compose.yml, ensure configs inside the restored seafile-data volume are correct, then run docker compose up -d.

Regularly test your recovery procedure on a separate test machine to ensure your backups are valid and the process works!

Workshop Performing a Manual Backup

Objective: To manually perform the core steps of backing up a running Seafile instance (databases and data directory) without setting up full automation.

Prerequisites:

A running Seafile instance (Manual install assumed here for mysqldump clarity, but concepts apply to Docker).
Access to the server command line with sudo.
Know your Seafile database password (YOUR_SEAFILE_DB_PASSWORD).
Know the path to your Seafile data directory (SEAFILE_DATA_DIR, e.g., /opt/seafile-data).
Know the path to your Seafile installation (SEAFILE_INSTALL_DIR, e.g., /opt/seafile).
A location to store the backup (e.g., /tmp/seafile-backup).

Steps:

Create Backup Directory:

TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BACKUP_ROOT="/tmp/seafile-backup" # Use a temporary location for this workshop
BACKUP_DIR="$BACKUP_ROOT/$TIMESTAMP"
sudo mkdir -p "$BACKUP_DIR/database"
sudo mkdir -p "$BACKUP_DIR/data"
sudo mkdir -p "$BACKUP_DIR/config"
echo "Backup directory: $BACKUP_DIR"

Stop Seafile Services:

echo "Stopping Seafile services..."
# Adjust paths and user if different
sudo -u seafile /opt/seafile/seafile-server-latest/seahub.sh stop
sudo -u seafile /opt/seafile/seafile-server-latest/seafile.sh stop
echo "Services stopped."
sleep 5 # Give them a moment

Backup Databases:

echo "Backing up databases..."
DB_PASS='YOUR_SEAFILE_DB_PASSWORD' # Replace with your actual password
sudo mysqldump --user=seafile --password="$DB_PASS" --host=localhost ccnet-db > "$BACKUP_DIR/database/ccnet-db.sql"
sudo mysqldump --user=seafile --password="$DB_PASS" --host=localhost seafile-db > "$BACKUP_DIR/database/seafile-db.sql"
sudo mysqldump --user=seafile --password="$DB_PASS" --host=localhost seahub-db > "$BACKUP_DIR/database/seahub-db.sql"
echo "Database backup complete. Verifying files:"
ls -lh "$BACKUP_DIR/database/"
# Check that files exist and have non-zero size

Backup Seafile Data Directory:

echo "Backing up Seafile data directory..."
SEAFILE_DATA_DIR="/opt/seafile-data" # Adjust if needed
sudo rsync -az --info=progress2 "$SEAFILE_DATA_DIR/" "$BACKUP_DIR/data/"
# Using --info=progress2 shows overall progress for large directories
echo "Data directory backup complete."

Backup Configuration:

echo "Backing up configuration..."
SEAFILE_INSTALL_DIR="/opt/seafile" # Adjust if needed
sudo cp -a "$SEAFILE_INSTALL_DIR/conf" "$BACKUP_DIR/config/"
sudo cp -a "$SEAFILE_INSTALL_DIR/seafile-server-latest/seafile.sh" "$BACKUP_DIR/config/" # Example: backup start script
sudo cp -a "$SEAFILE_INSTALL_DIR/seafile-server-latest/seahub.sh" "$BACKUP_DIR/config/"   # Example: backup start script
echo "Configuration backup complete."

Restart Seafile Services:

echo "Restarting Seafile services..."
# Adjust paths and user if different
sudo -u seafile /opt/seafile/seafile-server-latest/seafile.sh start
sudo -u seafile /opt/seafile/seafile-server-latest/seahub.sh start-gunicorn # Or relevant start command
echo "Services restarted."
sleep 10 # Give them time to initialize
# Test access via browser briefly

Inspect Backup:

echo "Backup created at: $BACKUP_DIR"
ls -lR "$BACKUP_DIR" | head -n 20 # View top-level structure and some files
# Calculate total backup size (optional)
sudo du -sh "$BACKUP_DIR"

Cleanup (Important for Workshop):

echo "Workshop complete. Cleaning up temporary backup..."
sudo rm -rf "$BACKUP_ROOT"
echo "Cleanup finished."

Outcome: You have manually executed the essential steps of a Seafile backup: stopping services, dumping databases, copying the data directory, and copying configuration files. You have created a point-in-time backup (and then cleaned it up for the workshop). This exercise demonstrates the procedure that should be automated for regular protection.

12. Security Hardening

While Seafile itself is designed with security in mind, securing the underlying server and implementing best practices is crucial for protecting your data from unauthorized access, attacks, and vulnerabilities.

System-Level Security

Keep System Updated: Regularly apply security patches to your operating system and all installed packages.

sudo apt update && sudo apt upgrade -y # Debian/Ubuntu
# sudo yum update -y # CentOS/RHEL
# Consider enabling automatic security updates

Firewall Configuration: Use a firewall (ufw on Ubuntu, firewalld on CentOS) to block all incoming ports except those explicitly needed.
- Essential Ports:
  - 22 (SSH - ideally rate-limited or key-only access)
  - 80 (HTTP - for Let's Encrypt challenge and redirect to HTTPS)
  - 443 (HTTPS - Nginx/Apache reverse proxy)
- Internal Ports (Should NOT be open to the internet):
  - 8000 (Seahub default)
  - 8082 (seaf-server default)
  - 10001 (ccnet)
  - 11211 (Memcached - bind to localhost only)
  - 3306 (MySQL/MariaDB - bind to localhost only)
  - 5432 (PostgreSQL - bind to localhost only)
- Example (ufw):
```
sudo ufw allow ssh # Or specific port number
sudo ufw allow 'Nginx Full' # Allows 80/tcp and 443/tcp
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw enable
sudo ufw status verbose
```
SSH Security:
- Use Key-Based Authentication: Disable password authentication for SSH and use SSH keys exclusively. Edit /etc/ssh/sshd_config: PasswordAuthentication no.
- Change Default Port: Move SSH from port 22 to a non-standard port (e.g., 2244). Update firewall rules accordingly. Port 2244 in sshd_config.
- Limit User Access: Allow SSH login only for specific users or groups (AllowUsers user1 user2 or AllowGroups sshusers in sshd_config).
- Use Fail2ban: (See below)

Intrusion Detection and Prevention (Fail2ban)

Purpose: Fail2ban scans log files (e.g., SSH, Nginx, Seafile) for patterns matching failed login attempts or malicious activity and temporarily or permanently bans the offending IP addresses using firewall rules.

Installation:

sudo apt install -y fail2ban
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

Configuration: Fail2ban's configuration is in /etc/fail2ban/. Create local overrides instead of editing default files.

Copy jail.conf to jail.local: sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local
Edit jail.local: sudo nano /etc/fail2ban/jail.local
- Adjust bantime, findtime, maxretry under [DEFAULT].
- Enable specific jails by adding enabled = true under their section (e.g., [sshd]).

Seafile-Specific Filters: Create filters to monitor Seafile login failures in Nginx logs or potentially Seahub logs (if logging failures clearly).

Filter (/etc/fail2ban/filter.d/seafile-auth.conf):

[Definition]
# Example for Nginx access log (adjust log format/path if needed)
# Assuming failed logins result in POST /api2/auth-token/ with non-200 status
# Or check seahub.log for specific failure messages
# This needs careful tailoring to your specific log messages indicating auth failure!
failregex = ^<HOST> .*POST /api2/auth-token/.* (400|401|403) .*$
           ^<HOST> .*POST /accounts/login/.* (400|401|403) .*$
ignoreregex =

Jail (/etc/fail2ban/jail.local):

[seafile-auth]
enabled = true
port = http,https # Check ports 80 and 443
filter = seafile-auth
logpath = /var/log/nginx/seahub.access.log # Or /opt/seafile/logs/seahub.log if logging failures there
maxretry = 5
bantime = 1h # Ban for 1 hour
findtime = 10m # 5 failures within 10 minutes

Restart Fail2ban: sudo systemctl restart fail2ban
Check Status: sudo fail2ban-client status, sudo fail2ban-client status seafile-auth

Seafile Application Security

Use HTTPS: Already covered with the reverse proxy setup. Absolutely essential.

Strong Passwords: Enforce strong password policies for users.

In seahub_settings.py:

PASSWORD_MIN_LENGTH = 10 # Increase minimum length
# Pro Edition might offer more complex checks (uppercase, numbers, etc.)
# PASSWORD_STRENGTH_CHECKER = ... # Requires custom implementation or Pro features
FORCE_PASSWORD_CHANGE = True # Force change after admin reset

Two-Factor Authentication (2FA): Highly recommended. Adds a significant layer of security. Users will need an authenticator app (Google Authenticator, Authy, etc.).
- Enable in seahub_settings.py:
```
ENABLE_TWO_FACTOR_AUTH = True
```
- Restart Seahub.
- Users can then enable 2FA in their personal Settings -> Security section by scanning a QR code.
Regularly Review Admin Access: Limit the number of administrator accounts to only those who strictly need it.
Review Sharing Links: Periodically review active public sharing links (System Admin -> Links). Encourage users to set passwords and expiration dates on sensitive links. Admins can disable or delete risky links.
Disable Unused Features: If you don't use features like public registration, disable them (ENABLE_SIGNUP = False in seahub_settings.py or via Admin UI).
Check Seafile Security Notices: Monitor the Seafile blog/website for any security advisories related to the versions you are running and apply updates promptly.
File Scanning (Advanced): Integrate ClamAV or similar antivirus scanners to scan uploaded files, especially if accepting uploads from untrusted sources (e.g., via upload links). This requires custom scripting or using Seafile Pro features that might have built-in integration.

Docker Security (If Applicable)

Run as Non-Root: Configure containers to run processes as non-root users where possible (the official Seafile image generally does this internally).
Limit Capabilities: Drop unnecessary Docker capabilities for containers.
Network Segmentation: Use custom Docker networks to isolate containers. The provided docker-compose.yml creates seafile-net. Ensure containers only expose necessary ports to that network unless explicitly needed externally (like the reverse proxy).
Volume Permissions: Ensure host volume mount points have appropriate, non-excessive permissions.
Scan Images: Use tools like docker scan (uses Snyk) or Trivy to scan your Docker images for known vulnerabilities.

Security is an ongoing process, not a one-time setup. Regularly review your configuration, stay updated, and monitor logs.

Workshop Enabling Two-Factor Authentication (2FA)

Objective: To enable 2FA on the Seafile server and configure it for a user account.

Prerequisites:

A running Seafile instance (Docker or Manual) with HTTPS configured.
Access to the server command line with sudo privileges.
A text editor (nano).
An authenticator app installed on your smartphone (e.g., Google Authenticator, Authy, Microsoft Authenticator).
Access to a regular user account (can be the admin account for testing).

Steps:

Enable 2FA in Configuration:
- Locate and edit seahub_settings.py:
  - Docker: sudo nano /opt/seafile-docker/seafile-data/seafile/conf/seahub_settings.py
  - Manual: sudo nano /opt/seafile/conf/seahub_settings.py
- Add the following line at the end of the file (or change it from False to True if it exists):
```
# Enable Two Factor Authentication
ENABLE_TWO_FACTOR_AUTH = True
```
- Save the file (Ctrl+X, Y, Enter).

Restart Seahub:

Docker:

cd /opt/seafile-docker
sudo docker compose restart seafile

Manual Install:

# Adjust user/path if needed
sudo -u seafile /opt/seafile/seafile-server-latest/seahub.sh restart # Or Gunicorn restart / systemd restart

Wait a few moments for the service to come back up.

Configure 2FA for User Account:
- Log in to the Seafile web interface as the user for whom you want to enable 2FA (this can be your admin account or any other user).
- Click the user avatar in the top-right corner -> "Settings".
- In the left sidebar, click "Security".
- You should now see a "Two-Factor Authentication" section. Click the "Enable" button.
Scan QR Code:
- Seafile will display a QR code and a secret key (text format).
- Open your authenticator app on your smartphone.
- Choose the option to add a new account (often a '+' button).
- Select "Scan QR code". Point your phone's camera at the QR code displayed by Seafile.
- Your authenticator app should recognize it and add an entry, usually named after your Seafile email/username and server. It will start generating 6-digit time-based codes.
- (Alternative/Backup): Copy the textual secret key provided by Seafile and store it securely (e.g., in a password manager). You can use this key to manually add the account to an authenticator app if you can't scan the QR code.
Verify Code:
- Enter the current 6-digit code displayed in your authenticator app into the verification box on the Seafile page.
- Click "Verify and Enable".
Save Recovery Codes:
- Seafile will display a list of one-time recovery codes. These are extremely important! If you lose access to your authenticator app (e.g., lose your phone), these codes are the only way to regain access to your account.
- Copy these codes and store them in a very safe place, separate from your authenticator app (e.g., print them out, save them in a secure password manager).
- Check the box confirming you have saved the codes. Click "Done".
Test 2FA Login:
- Log out of your Seafile account.
- Log back in. Enter your username and password as usual.
- You should now be prompted for a "Verification Code".
- Open your authenticator app and enter the current 6-digit code for your Seafile account.
- Click "Verify". You should be logged in successfully.

Outcome: You have successfully enabled the 2FA requirement server-wide and configured it for your user account using a mobile authenticator app. Your account is now significantly more secure against unauthorized access, even if your password were to be compromised. Remember the importance of safeguarding your recovery codes.

13. Integrating with External Services

Seafile's capabilities can be extended by integrating it with other self-hosted or external services, most commonly for centralized authentication (LDAP/AD) or online document editing (ONLYOFFICE/Collabora).

LDAP/Active Directory Integration

Purpose: Allows users to log in to Seafile using their existing credentials from a central directory service like OpenLDAP or Microsoft Active Directory, instead of managing separate Seafile passwords. Simplifies user management in organizations or universities.
Prerequisites:
- A running LDAP or AD server accessible from your Seafile server.
- LDAP/AD server details: Hostname/IP, Port (e.g., 389 for LDAP, 636 for LDAPS), Base DN (Distinguished Name) for searching users, Admin Bind DN and Password (a service account with permission to search the directory), User search filter, attribute mapping (which AD/LDAP attribute corresponds to Seafile's email, name, etc.).
- Python LDAP library installed:
  - Manual Install: sudo pip3 install python-ldap (or python3-ldap via apt if available and compatible). Ensure LDAP development libraries like libsasl2-dev and libldap2-dev are installed first (sudo apt install libsasl2-dev libldap2-dev).
  - Docker: The official image usually includes the necessary library.

Configuration (ccnet.conf): The primary configuration happens in /opt/seafile/conf/ccnet.conf (or the mapped Docker path). Add an [LDAP] section (or [LDAPSync] for sync features).

# Example for OpenLDAP (adjust for your environment)
[LDAP]
# LDAP server address (use ldaps:// for SSL)
HOST = ldap://ldap.example.com
# Base DN for searching users
BASE = ou=users,dc=example,dc=com
# Bind DN (service account) - Can often be anonymous if LDAP server allows
# USER_DN = cn=admin,dc=example,dc=com
# PASSWORD = service_account_password
# User search filter (objectClass is common)
FILTER = (objectClass=inetOrgPerson)
# Attribute to use as the Seafile login ID (usually mail or uid)
LOGIN_ATTR = mail
# Use paged results for large directories (optional but recommended)
USE_PAGED_RESULTS = true
# Follow referrals (optional)
# FOLLOW_REFERRALS = false

# --- Attribute Mapping ---
# Map LDAP attributes to Seafile user properties
# Defaults: Email=mail, Name=cn, UserID=mail, Department=department
# Adjust based on your LDAP schema!
# LOGIN_ATTR = uid # If using uid instead of mail for login
# EMAIL = mail
# NAME = displayName
# DEPARTMENT = departmentNumber

# --- Optional: Encrypted Connection (LDAPS) ---
# HOST = ldaps://ldap.example.com
# You might need to configure certificate verification:
# TLS_CACERT = /path/to/ca/certificate.pem
# TLS_REQCRT = demand # Verify server certificate

# Example for Active Directory (adjust for your environment)
[LDAP]
HOST = ldap://ad.example.local # Use ldaps:// for secure AD
# Base DN - often starts from the root or a specific OU
BASE = cn=users,dc=example,dc=local
# AD service account requires format: user@domain or domain\user
USER_DN = CN=SeafileService,OU=ServiceAccounts,DC=example,DC=local
PASSWORD = service_account_password
# Common AD user filter
FILTER = (objectClass=user)
# UserPrincipalName or sAMAccountName are common login attributes
LOGIN_ATTR = userPrincipalName
USE_PAGED_RESULTS = true

# --- Attribute Mapping (AD Defaults) ---
# EMAIL = mail
# NAME = cn # Or 'displayName'
# DEPARTMENT = department

Testing: Use the check-ldap script provided with Seafile (usually requires manual install environment or docker exec):

# Manual Install (adjust path)
cd /opt/seafile/seafile-server-latest/
./pro/pro.py ldapsync --test # For Pro sync feature
./check-ldap # Basic connectivity/search test (might be deprecated, check manual)

# Docker (adjust container name)
sudo docker compose exec seafile /opt/seafile/seafile-server-latest/check-ldap
# Or specific pro test if applicable

Restart: Restart Ccnet and Seahub after configuration changes.
- Docker: sudo docker compose restart seafile
- Manual: sudo -u seafile .../seafile.sh restart && sudo -u seafile .../seahub.sh restart
Login: Users should now be able to log in using their LDAP/AD email (or the attribute specified in LOGIN_ATTR) and password. The first time a user logs in via LDAP, their Seafile account is typically auto-created.

ONLYOFFICE/Collabora Online Integration

Purpose: Allows users to view and collaboratively edit documents (DOCX, XLSX, PPTX), spreadsheets, and presentations directly within the Seafile web interface using a self-hosted or commercial online office suite.
Prerequisites:
- A running ONLYOFFICE Docs server (Community Edition is free, formerly Document Server) OR a Collabora Online Development Edition (CODE) server. These are separate applications that need their own installation (Docker is highly recommended for them).
- The ONLYOFFICE/Collabora server must be accessible (HTTPS recommended) from both the Seafile server and end-user browsers.
- Seafile server configured with HTTPS (required by office servers). SERVICE_URL and FILE_SERVER_ROOT in seahub_settings.py must be correct https://... URLs.

Configuration (seahub_settings.py): Add the relevant section to /opt/seafile/conf/seahub_settings.py (or mapped Docker path).

# --- ONLYOFFICE Integration ---
ENABLE_ONLYOFFICE = True
# Verify the SSL certificate of the ONLYOFFICE server (recommended!)
VERIFY_ONLYOFFICE_CERTIFICATE = True
# URL pointing to your ONLYOFFICE Docs server's internal address
# Seafile server needs to reach this URL.
ONLYOFFICE_API_ENDPOINT = "https://onlyoffice.yourdomain.com/"
# URL pointing to your ONLYOFFICE Docs server's public address
# End-user browsers need to reach this URL to load the editor interface.
# Often the same as API_ENDPOINT if not behind complex network setup.
ONLYOFFICE_SERVICE_URL = "https://onlyoffice.yourdomain.com/"
# Secret key for signing requests between Seafile and ONLYOFFICE (JWT)
# Must be IDENTICAL in Seafile config and ONLYOFFICE config (local.json or env variable).
ONLYOFFICE_JWT_SECRET = "YOUR_VERY_STRONG_SECRET_JWT_KEY"
# Optional: Specify allowed file types
# ONLYOFFICE_FILE_EXTENSION = ('docx', 'xlsx', 'pptx', 'doc', 'xls', 'ppt')
# Optional: Set editor interface language
# ONLYOFFICE_DESKTOP_EDITOR_LANG = 'en'

# --- Collabora Online Integration ---
ENABLE_COLLABORA_OFFICE = True
# Verify the SSL certificate of the Collabora server (recommended!)
VERIFY_COLLABORA_CERTIFICATE = True
# URL pointing to your Collabora Online server (WOPI discovery endpoint)
# Seafile server needs to reach this.
COLLABORA_API_ENDPOINT = "https://collabora.yourdomain.com/"
# Public URL for Collabora Online server (used by browsers)
# Often the same as API_ENDPOINT.
COLLABORA_SERVICE_URL = "https://collabora.yourdomain.com/"
# Optional: Specify allowed file types
# COLLABORA_FILE_EXTENSION = ('odt', 'ods', 'odp', 'docx', 'xlsx', 'pptx')
# Optional: Set interface language
# COLLABORA_OFFICE_LANG = 'en-US'

ONLYOFFICE JWT Configuration: Ensure the same ONLYOFFICE_JWT_SECRET is configured on the ONLYOFFICE Docs server itself. This is usually done via environment variables (JWT_SECRET) if using Docker, or by editing its local.json configuration file.
Restart: Restart Seahub after configuration changes.
- Docker: sudo docker compose restart seafile
- Manual: sudo -u seafile .../seahub.sh restart
Usage: When browsing files in Seahub, supported document types should now have an "Edit" or "View" button that opens them within the integrated ONLYOFFICE or Collabora interface. Multiple users opening the same document simultaneously can see each other's edits in real-time.

Integration requires careful configuration of URLs, secrets, and network accessibility between the different services. Always consult the official Seafile manual and the documentation for ONLYOFFICE Docs or Collabora Online for the most up-to-date instructions.

Workshop Integrating with ONLYOFFICE (Conceptual/Prep)

Objective: To prepare the Seafile configuration for ONLYOFFICE integration, understanding the required settings, even if a separate ONLYOFFICE server isn't fully set up yet.

Prerequisites:

A running Seafile instance with HTTPS configured (SERVICE_URL starting with https://).
Access to edit seahub_settings.py.
Hypothetical ONLYOFFICE server URL: https://onlyoffice.yourdomain.com
Hypothetical JWT Secret: MySecretSeafileOnlyOfficeKey123!

Steps:

Plan the Integration:
- Confirm Seafile is accessible via https://seafile.yourdomain.com.
- Confirm SERVICE_URL and FILE_SERVER_ROOT in seahub_settings.py use this HTTPS URL.
- Identify the URL where ONLYOFFICE Docs will be accessible (e.g., https://onlyoffice.yourdomain.com). Both Seafile server and user browsers must be able to reach this.
- Choose a strong, unique JWT secret key.

Edit seahub_settings.py:

Open the configuration file:
- Docker: sudo nano /opt/seafile-docker/seafile-data/seafile/conf/seahub_settings.py
- Manual: sudo nano /opt/seafile/conf/seahub_settings.py

Add the following section at the end, substituting your planned values:

# --- ONLYOFFICE Integration Settings ---
ENABLE_ONLYOFFICE = True
VERIFY_ONLYOFFICE_CERTIFICATE = True # Keep True for production HTTPS
ONLYOFFICE_API_ENDPOINT = "https://onlyoffice.yourdomain.com/" # Internal URL for Seafile Server
ONLYOFFICE_SERVICE_URL = "https://onlyoffice.yourdomain.com/" # Public URL for browsers
ONLYOFFICE_JWT_SECRET = "MySecretSeafileOnlyOfficeKey123!" # Use your chosen secret

Save the file (Ctrl+X, Y, Enter).

Restart Seahub:
- Docker: cd /opt/seafile-docker && sudo docker compose restart seafile
- Manual: sudo -u seafile .../seahub.sh restart
Verify (Partial):
- Log in to Seafile.
- Navigate to a library containing a supported document type (e.g., .docx, .xlsx).
- Hover over the file. You should now see an "Edit" or "View in ONLYOFFICE" option (or similar).
- Clicking it will likely result in an error because the ONLYOFFICE server isn't actually running at that address or isn't configured with the matching JWT secret yet. However, the appearance of the button confirms Seafile knows about the integration attempt.

Outcome: You have successfully added the necessary configuration to seahub_settings.py to enable ONLYOFFICE integration. You understand which URLs and secrets are required and where to configure them. The next step would be to actually deploy and configure the ONLYOFFICE Docs server itself, ensuring network connectivity and matching the JWT secret.

14. Troubleshooting Common Issues

Even with careful setup, issues can arise. Systematically troubleshooting involves checking logs, verifying configurations, and understanding component interactions.

Symptom: Users cannot log in via web UI or clients. Error messages might include "Incorrect password," "User not found," or generic "Login failed."
Troubleshooting Steps:
1. Verify Credentials: Double-check username (email) and password. Try resetting the password via admin or "Forgot Password" link (if email is configured).
2. Check seahub.log: Located in /opt/seafile/logs/seahub.log (Manual) or view via sudo docker compose logs seafile (Docker). Look for lines around the time of the failed login attempt containing WARNING or ERROR related to authentication (auth, login).
3. Check ccnet.log: Located in /opt/seafile/logs/ccnet.log (Manual) or view via Docker logs. Ccnet handles the user backend. Look for errors related to database connections or user lookups.
4. Database Connectivity: Ensure ccnet-db and seahub-db are reachable and the credentials in ccnet.conf and seahub_settings.py are correct. Test connection manually (mysql -u seafile -p ...).
5. LDAP/AD Issues (If Used):
  - Check ccnet.log for LDAP-specific errors (connection refused, bind failure, user not found in LDAP).
  - Verify LDAP server is running and accessible from Seafile server (use ldapsearch or ping).
  - Verify USER_DN, PASSWORD, BASE, FILTER in ccnet.conf are correct.
  - Test with check-ldap script (see LDAP section).
6. Reverse Proxy Issues: Incorrect proxy headers (X-Forwarded-Proto, X-Forwarded-Host) can sometimes interfere. Ensure Nginx/Apache config matches the Seafile HTTPS setup. Check Nginx error logs (/var/log/nginx/seahub.error.log).
7. Fail2ban: Check if the user's IP address has been banned: sudo fail2ban-client status <jail_name>. Unban if necessary (sudo fail2ban-client set <jail_name> unbanip <IP_ADDRESS>).
8. Time Synchronization: Ensure server time is accurate (use ntp or chrony). Large time drifts can sometimes affect authentication protocols or session validation.

File Synchronization Problems

Symptom: Desktop client shows errors, files not uploading/downloading, sync icon stuck or shows an error (e.g., red 'x').
Troubleshooting Steps:
1. Check Client Logs: The Seafile desktop client has its own logs. Access them via the client's settings or main interface ("View Logs"). Look for specific error messages (connection errors, permission denied, file locked, quota exceeded).
2. Check Server Logs:
  - seafile.log: Located in /opt/seafile/logs/seafile.log (Manual) or via Docker logs. Logs core file operation errors (I/O errors, database errors related to file records).
  - controller.log: /opt/seafile/logs/controller.log (Manual) or Docker logs. Logs interactions between components.
  - Nginx/Apache Logs: Check seafile.access.log and seafile.error.log (or paths defined in your proxy config) for errors related to /seafhttp requests (e.g., timeouts, 4xx/5xx errors).
3. Verify SERVICE_URL and FILE_SERVER_ROOT: This is the most common cause. Ensure these values in seahub_settings.py are absolutely correct (correct http/https, domain name/IP) and match your reverse proxy setup. The client uses these URLs to find the server and file transfer endpoints. Incorrect values lead to connection failures for file transfers. Restart Seahub after changes.
4. Check Network Connectivity: Can the client machine reach the server address (ping, browser access)? Can the client reach the file server port (usually 8082 internally, accessed via port 443//seafhttp through the proxy)? Firewalls on client or server?
5. Reverse Proxy Configuration: Ensure the location /seafhttp { ... } block in Nginx/Apache is correctly configured to proxy to 127.0.0.1:8082 (Manual) or seafile:8082 (Docker). Check timeouts (proxy_read_timeout, etc.) and client_max_body_size in the Nginx config.
6. Permissions/Quota: Does the user have write permission for the library? Has the user exceeded their storage quota (check Admin UI)? Client logs often indicate these issues.
7. File Path Length/Invalid Characters: Extremely long file paths or files with characters incompatible with the server/client OS can sometimes cause issues. Try renaming/moving the problematic file.
8. File Locking: Is the file locked by another user (check Web UI)?
9. Disk Space: Is the server's data directory full? Is the client's local disk full? (df -h on server/client).
10. Restart Services: Try restarting Seafile server (seafile.sh restart) and Seahub (seahub.sh restart / Docker restart) on the server, and restart the desktop client.

Web Interface (Seahub) Issues

Symptom: Web UI not loading, pages display incorrectly (missing CSS/JS), features not working (e.g., file upload fails, avatars missing).
Troubleshooting Steps:
1. Check Seahub Process: Is Seahub running?
  - Manual: ps aux | grep gunicorn (or run_seahub.py). Check systemd service status: sudo systemctl status seahub.
  - Docker: sudo docker compose ps. Ensure seafile container is Up.
2. Check Seahub Logs: seahub.log (or Docker logs) for Python tracebacks or specific errors. Also check Gunicorn logs (gunicorn.access.log, gunicorn.error.log) if using Gunicorn.
3. Check Nginx/Apache Logs: seahub.access.log, seahub.error.log for errors related to the main / location block. 502 Bad Gateway often means Seahub (Gunicorn/port 8000) is down or Nginx can't reach it. 504 Gateway Timeout might mean Seahub is overloaded or stuck.
4. Verify SERVICE_URL and FILE_SERVER_ROOT: Yes, again! Incorrect values break CSS/JS loading, image/avatar display, download links, etc. Ensure they use https:// and the correct domain.
5. Media Files (CSS/JS):
  - Manual Install: Ensure the location /media { alias ...; } block in Nginx points to the correct seahub/media directory. Check filesystem permissions for that directory.
  - Docker: If you removed the /media block from Nginx (common), ensure Seahub is running correctly to serve these files via the / proxy_pass. If issues persist, check file permissions inside the container volume (/shared/seafile/seafile-server-latest/seahub/media).
6. Database Connectivity: Check seahub_settings.py database settings and ensure the seahub-db is reachable. Errors often appear in seahub.log.
7. Caching Issues: If using Memcached, ensure it's running (sudo systemctl status memcached or docker ps) and reachable from Seahub (LOCATION in seahub_settings.py). Try restarting Memcached. As a temporary test, comment out the CACHES setting in seahub_settings.py and restart Seahub to see if caching was the issue (performance will degrade).
8. Browser Issues: Clear browser cache and cookies. Try a different browser or private/incognito mode to rule out browser extensions or cached data problems. Check the browser's developer console (F12) for JavaScript errors or network requests failing (404s, 500s).

Performance Problems

Symptom: Web UI is slow, file transfers are slow, server CPU/RAM usage is high.
Troubleshooting Steps:
1. Monitor Resources: Use htop, iotop, vmstat to identify the bottleneck (CPU, RAM, Disk I/O, Network). Is it mysqld, postgres, gunicorn/python, seaf-server, nginx, or memcached consuming resources?
2. Tune Components: Refer to the "Performance Tuning" section:
  - Increase Gunicorn workers (SEAFILE_WEB_WORKERS or --workers).
  - Increase seaf-server worker threads (worker_threads in seafile.conf).
  - Ensure Memcached is enabled and has sufficient memory.
  - Optimize database configuration (mysqltuner, pgtune, check max_connections, sufficient RAM).
3. Check Network: Use tools like iperf3 to test network throughput between client and server, and between Seafile server and database server (if separate).
4. Analyze Slow Queries: Enable slow query logging in your database to identify inefficient queries.
5. Hardware Upgrade: If consistently resource-bound despite tuning, consider adding more RAM, faster SSDs, or more CPU cores.

Troubleshooting is often a process of elimination. Check logs first, verify configurations (especially URLs!), check resource usage, and test connectivity between components.

Workshop Diagnosing a Configuration Error

Objective: To intentionally introduce a common configuration error (SERVICE_URL), observe the resulting problems in the web UI, and use logs/debugging steps to identify and fix it.

Prerequisites:

A working Seafile instance with Nginx/HTTPS.
Access to edit seahub_settings.py.
Access to server logs (Nginx, Seafile).
Web browser with developer tools (F12).

Steps:

Introduce the Error:
- Edit seahub_settings.py:
  - Docker: sudo nano /opt/seafile-docker/seafile-data/seafile/conf/seahub_settings.py
  - Manual: sudo nano /opt/seafile/conf/seahub_settings.py
- Find the SERVICE_URL line. Change it from the correct https://... URL to an incorrect one, for example, change https to http:
```
# INTRODUCE ERROR HERE! Change https to http
SERVICE_URL = "http://seafile.yourdomain.com"
# Leave FILE_SERVER_ROOT as SERVICE_URL + '/seafhttp' for now
```
- Save the file.
Restart Seahub:
- Docker: cd /opt/seafile-docker && sudo docker compose restart seafile
- Manual: sudo -u seafile .../seahub.sh restart
Observe the Problem:
- Clear your browser cache thoroughly or use a private/incognito window.
- Try accessing your Seafile instance via the correct https://seafile.yourdomain.com URL.
- Symptoms: What do you notice? Likely issues include:
  - Page loads partially or without styling (CSS missing).
  - Images/Avatars might be broken.
  - Login might work, but navigating libraries or downloading files might fail.
  - The browser might show "mixed content" warnings (trying to load HTTP resources on an HTTPS page).
Debug Step 1: Browser Developer Tools:
- With the broken Seafile page loaded, open your browser's developer tools (usually F12).
- Go to the "Console" tab. Look for errors, especially "Mixed Content" errors indicating attempts to load http://... resources on an https://... page.
- Go to the "Network" tab. Refresh the page (F5). Look for requests that are failing (Status 404 Not Found or others) or requests going to the wrong URL scheme (http instead of https). Pay attention to requests for CSS, JS, image files, and API calls. You'll likely see requests to http://seafile.yourdomain.com/... failing because your Nginx is redirecting HTTP to HTTPS, or the browser is blocking them.
Debug Step 2: Check Logs (Less Direct for this specific error):
- While logs might not scream "SERVICE_URL is wrong!", check seahub.log or Docker logs for any secondary errors that might occur due to the misconfiguration (though often the primary issue is client-side rendering failure).
- Check Nginx access logs (seahub.access.log). You might see requests coming in for https but potentially Seafile generating internal links using http.
Identify the Cause: Based on the browser developer tools (Mixed Content errors, failed requests to http URLs), the prime suspect is that Seafile is generating incorrect URLs using http instead of https. This points directly to the SERVICE_URL setting.
Fix the Error:
- Edit seahub_settings.py again.
- Change SERVICE_URL back to the correct https:// value:
```
SERVICE_URL = "https://seafile.yourdomain.com"
```
- Save the file.
Restart Seahub:
- Docker: cd /opt/seafile-docker && sudo docker compose restart seafile
- Manual: sudo -u seafile .../seahub.sh restart
Verify the Fix:
- Clear browser cache again or use a new private window.
- Access https://seafile.yourdomain.com.
- The page should now load correctly with all styling, images, and functionality restored. Check the Developer Console again - the Mixed Content errors should be gone.

Outcome: You have experienced a common issue caused by an incorrect SERVICE_URL, observed its symptoms (broken web UI, mixed content errors), used browser developer tools as the primary diagnostic tool, identified the misconfiguration, and successfully fixed it. This reinforces the critical importance of the SERVICE_URL setting.

15. Maintenance and Upgrades

Regular maintenance and timely upgrades are essential for keeping your Seafile instance secure, stable, and performant.

Routine Maintenance Tasks

Monitor Disk Space: Regularly check the disk usage of your Seafile data directory, database volumes, and log directories. (df -h, du -sh /path/to/data). Plan for growth or implement cleanup strategies.
Check Logs: Periodically review Seafile logs (seafile.log, seahub.log, controller.log, Nginx/Apache logs, database logs, fail2ban logs) for recurring errors or warnings, even if the system seems to be working.
Review Backups: Verify that your backup jobs are running successfully. More importantly, periodically test restoring a backup to a separate test environment to ensure the backups are valid and your recovery procedure works.
System Updates: Keep the underlying operating system and packages updated (sudo apt update && sudo apt upgrade -y). Pay attention to security updates for Nginx/Apache, the database, Python, and Docker.
Clean Library Trash: Encourage users to empty their library trash bins. Configure automatic trash cleanup in seafile.conf if desired:
```
# In seafile.conf [history] section
# Days to keep file revisions (adjust as needed, default is often unlimited)
# keep_days = 30
# Days to keep library trash (default unlimited)
# trash_keep_days = 90
```
Restart seafile.sh after changes. Seafile also has garbage collection (see below).
Seafile Database Maintenance: Run database-specific maintenance tasks like OPTIMIZE TABLE (MySQL/MariaDB) or VACUUM ANALYZE (PostgreSQL) occasionally, especially after large data deletions or changes, to reclaim space and optimize performance. Consult database documentation.

Seafile Garbage Collection (GC)

Purpose: Seafile's block-based storage means that even when files or libraries are deleted (and trash is emptied), the underlying data blocks might still exist on the disk if they were part of previous history snapshots that haven't been explicitly cleaned up. Seafile GC removes these unreferenced blocks, freeing up disk space.
When to Run: Run GC periodically (e.g., weekly or monthly, depending on activity) after users have cleared trash and history retention periods (trash_keep_days in seafile.conf) have passed for deleted items. It is NOT for routine history cleanup.
Procedure:
1. STOP Seafile Server: GC must be run while the seafile-server process is stopped. Seahub can usually remain running.
  - Docker: sudo docker compose stop seafile (or maybe just exec into the container and run seafile.sh stop inside)
  - Manual: sudo -u seafile /opt/seafile/seafile-server-latest/seafile.sh stop
2. Run GC Script:
  - Docker (exec into container):
```
sudo docker compose exec seafile su -s /bin/bash seafile # Get shell as seafile user
cd /opt/seafile/seafile-server-latest/
./seaf-gc.sh
exit # Exit user shell
```
  - Manual Install:
```
sudo -u seafile /opt/seafile/seafile-server-latest/seaf-gc.sh
```
3. Monitor Output: The script will show progress as it scans libraries and removes unused blocks. It can take a significant amount of time depending on the size of your data. Check logs/seafile-gc.log for details.
4. Run GC Dry Run (Optional): Use ./seaf-gc.sh --dry-run first to see what would be deleted without actually deleting anything.
5. Remove Deleted Libraries Immediately (Optional): Use ./seaf-gc.sh --rm-deleted to immediately clean up blocks associated with libraries that have been deleted from the System Admin panel (bypassing trash retention). Use with caution.
6. Restart Seafile Server:
  - Docker: sudo docker compose start seafile
  - Manual: sudo -u seafile /opt/seafile/seafile-server-latest/seafile.sh start

Upgrading Seafile Server

Upgrading keeps you secure and provides new features. Always read the release notes and specific upgrade instructions for the versions you are moving between, as procedures can change. ALWAYS BACK UP EVERYTHING BEFORE STARTING AN UPGRADE.

General Steps (Manual Install):
1. Backup: Perform a full backup (Databases, Data Directory, Configs).
2. Read Release Notes: Check the Seafile Server Manual -> Changelog section for notes on the target version and any intermediate versions you are skipping. Pay attention to required upgrade scripts or configuration changes.
3. Stop Services: seahub.sh stop, seafile.sh stop.
4. Download New Version: Get the new server tarball (seafile-server_X.Y.Z_x86-64.tar.gz).
5. Extract New Version: Extract alongside the current version (e.g., in /opt/seafile/).
```
cd /opt/seafile
sudo tar -xzf /path/to/download/seafile-server_X.Y.Z_x86-64.tar.gz
```
6. Run Upgrade Scripts: This is the critical part. Navigate into the new version's directory (cd /opt/seafile/seafile-server-X.Y.Z/). There will be upgrade scripts (e.g., upgrade/upgrade_A.B_to_C.D.sh). You must run these scripts sequentially for every minor version you are skipping.
  - Example: Upgrading from 9.0.x to 10.0.x might involve running upgrade_9.0_10.0.sh. Upgrading from 8.0.x to 10.0.x might require running upgrade_8.0_9.0.sh then upgrade_9.0_10.0.sh.
  - ALWAYS follow the specific instructions in the manual for your version path.
  - bash # Example - ALWAYS check manual for your specific upgrade path! sudo -u seafile ./upgrade/upgrade_9.0_10.0.sh
  - These scripts update database schemas and potentially modify configuration files. Carefully watch the output for errors.
7. Update seafile-server-latest Symlink: Point the symlink to the new version directory.
```
cd /opt/seafile
sudo rm seafile-server-latest
sudo ln -s seafile-server-X.Y.Z seafile-server-latest # Point to new version
```
8. Check Configuration: Compare your backed-up configuration files (conf directory) with any new default files in the new version. Merge any necessary new settings into your existing configuration files.
9. Start Services: seafile.sh start, seahub.sh start (or Gunicorn/systemd).
10. Test Thoroughly: Check web UI, login, file sync, sharing, etc. Check logs for errors.
General Steps (Docker): Upgrading is often simpler, leveraging pre-built images.
1. Backup: Stop containers (docker compose stop), back up volumes (mysql-data, seafile-data), back up docker-compose.yml. Restart containers (docker compose start).
2. Read Release Notes: Still essential to understand changes.
3. Update docker-compose.yml: Change the image tag for the seafile service to the new version (e.g., image: seafileltd/seafile-mc:10.0.1). You might also need to update the MariaDB or Memcached image versions if recommended.
4. Pull New Image: sudo docker compose pull seafile
5. Stop and Restart Containers:
```
sudo docker compose down # Stops and removes containers (networks/volumes remain)
sudo docker compose up -d # Starts containers using the new image
```
  The entrypoint script within the official Seafile Docker image is designed to automatically run necessary database migrations and upgrade steps on startup when it detects a version change.
6. Check Logs: Monitor the seafile container logs closely during the first startup after the upgrade: sudo docker compose logs -f seafile. Look for messages about database upgrades and successful startup.
7. Test Thoroughly: As with manual upgrades.

Always perform upgrades during a low-usage period and be prepared to roll back using your backups if significant problems occur.

Workshop Performing a Minor Docker Upgrade

Objective: To simulate upgrading Seafile within a Docker environment by changing the image tag in docker-compose.yml.

Prerequisites:

Seafile running via Docker Compose.
Know your current Seafile version (check bottom-left of Seahub UI or System Admin -> Info). Let's assume you are on 10.0.0 and want to upgrade to 10.0.1 (use actual available minor versions).
Access to the server with sudo and docker compose.
Backup: Perform a quick backup (conceptual or real) of your volumes and docker-compose.yml before proceeding. sudo docker compose stop && sudo rsync -a /opt/seafile-docker/seafile-data /mnt/backup/ && sudo rsync -a /opt/seafile-docker/mysql-data /mnt/backup/ && sudo cp /opt/seafile-docker/docker-compose.yml /mnt/backup/ && sudo docker compose start

Steps:

Identify Target Version: Check the Seafile release notes or Docker Hub (seafileltd/seafile-mc) for a recent minor version number available after your current one (e.g., if you are on 10.0.0, look for 10.0.1 or similar). Let's assume 10.0.1 is available and you want to upgrade to it.
Edit docker-compose.yml:
- Navigate to your Docker directory: cd /opt/seafile-docker
- Edit the file: sudo nano docker-compose.yml
- Locate the image: line under the seafile: service.
- Change the tag from your current version (or latest) to the specific target minor version:
```
services:
  # ... db, memcached ...
  seafile:
    # Update this line:
    image: seafileltd/seafile-mc:10.0.1 # Change from :10.0.0 or :latest
    # ... rest of seafile service definition ...
```
- Save the file.

Pull the New Image: Download the specified image version:

sudo docker compose pull seafile
# Observe the download progress

Stop and Recreate Containers: Use down and up to ensure the upgrade scripts in the new image's entrypoint are triggered correctly.

echo "Stopping and removing old containers..."
sudo docker compose down
echo "Starting containers with the new image..."
sudo docker compose up -d

Monitor Logs During Startup: Immediately check the logs of the seafile container. This is where you'll see upgrade activity.

sudo docker compose logs -f seafile
# Look for lines like "Starting Seafile server..."
# Look for potential "Performing database schema upgrade..." messages
# Look for "Seahub is started" or similar success messages.
# Press Ctrl+C to stop following logs once startup seems complete.

If you see errors, the upgrade may have failed. You might need to restore from backup and investigate.

Test the Upgraded Instance:
- Access Seafile via your browser.
- Check the version number displayed in the UI (bottom-left or System Admin -> Info). It should now show the target version (e.g., 10.0.1).
- Log in. Perform basic checks: browse libraries, upload a small file, download a file.
- Check if the desktop client still syncs correctly.

Outcome: You have successfully performed a minor version upgrade of your Dockerized Seafile instance by updating the image tag and letting the container's startup script handle the migration. You understand the process and the importance of monitoring logs during the upgrade.

Conclusion

Congratulations on completing this comprehensive guide to self-hosting Seafile! You have journeyed from the fundamental concepts and basic Docker installation to advanced configurations involving manual setups, reverse proxies with HTTPS, performance tuning, security hardening, external integrations, and crucial maintenance procedures like backups and upgrades.

By now, you should have a solid understanding of:

What Seafile is and the advantages of self-hosting it for data control and privacy.
Core concepts like Libraries, block-level sync, and sharing models.
Installation methods, particularly Docker for ease of use and manual installation for greater control.
Configuring Seafile through its key files (ccnet.conf, seafile.conf, seahub_settings.py) and the web UI.
Securing your instance using Nginx/Apache reverse proxies, Let's Encrypt for HTTPS, firewalls, Fail2ban, and 2FA.
Managing users, groups, and permissions effectively.
Leveraging advanced desktop client features like Selective Sync.
Optimizing performance through caching and worker tuning.
Implementing robust backup and recovery strategies.
Integrating Seafile with services like LDAP and ONLYOFFICE/Collabora.
Troubleshooting common issues using logs and systematic debugging.
Performing routine maintenance and server upgrades.

Self-hosting Seafile is a rewarding endeavor that provides immense value in terms of data ownership, privacy, and customization. It also offers an invaluable learning experience in Linux server administration, networking, security, and application management – skills highly relevant in many technical fields.

While this guide provides a deep dive, the journey doesn't end here. The Seafile ecosystem is active, and new features and best practices emerge. Continue to explore the official Seafile Server Manual, engage with the community forums, and apply your knowledge to tailor your Seafile instance precisely to your needs. Remember that security and maintenance are ongoing responsibilities, crucial for protecting your valuable data.

You are now well-equipped to confidently run and manage your own private cloud storage solution with Seafile. Enjoy the control, flexibility, and privacy it offers!

Cloud Sync & Storage Seafile

Introduction What is Seafile and Why Self-Host It

Basic

1. Core Seafile Concepts Explained

Libraries (Repositories)

Synchronization Mechanisms

Sharing Models

User Roles and Administration

Workshop Understanding Core Concepts

2. Basic Installation via Docker

Prerequisites

Installation Steps

Workshop Basic Docker Installation

3. Initial Server Configuration via Web UI

Accessing System Administration

Key Initial Settings

Workshop Initial Web Configuration

4. Basic Usage Web UI and Desktop Client

Using the Web Interface (Seahub)

Installing and Setting Up the Desktop Client

Basic Syncing Workflow

Workshop Using Seafile

Intermediate

5. Advanced Installation Methods

Choosing a Database Backend

Manual Installation Steps (Example using Ubuntu/Debian and MariaDB)

Install specific libraries via pip (consult manual for exact list and versions!)

Download the server tarball (replace URL with the correct one)

Extract the tarball

Optional: Clean up the tarball

Create a dedicated data directory (outside the installation dir usually)

Workshop Manual Installation (Conceptual)

6. Server Configuration Deep Dive

ccnet.conf

seafile.conf

seahub_settings.py

Workshop Exploring and Modifying Configuration Files

7. Reverse Proxy Setup with Nginx and HTTPS

Prerequisites

Configuration Steps

Workshop Setting Up Nginx and Let's Encrypt

8. User Management and Permissions

User Management (System Admin Panel)

Group Management

Library and Folder Permissions

Roles

Workshop Managing Users, Groups, and Shares

9. Desktop Client Advanced Features

Selective Sync (Cloud File Browser)

Unsyncing a Library

Syncing with Existing Folder

Controlling Sync Intervals and Bandwidth

Workshop Using Advanced Client Features

Advanced

10. Performance Tuning and Scaling

Caching with Memcached

Seahub Concurrency (Gunicorn Workers)

Seafile File Server Workers (seaf-server)

Database Optimization

Filesystem Considerations

Monitoring

Workshop Tuning Gunicorn Workers (Docker)

11. Backup and Recovery Strategies

Components to Back Up

Backup Procedure (Example: Manual Install with MariaDB)

Backup Procedure (Docker)

Recovery Procedure (Example: Manual Install Disaster Recovery)

Workshop Performing a Manual Backup

12. Security Hardening

System-Level Security

Intrusion Detection and Prevention (Fail2ban)

Seafile Application Security

Docker Security (If Applicable)

Workshop Enabling Two-Factor Authentication (2FA)

13. Integrating with External Services

LDAP/Active Directory Integration

ONLYOFFICE/Collabora Online Integration

Workshop Integrating with ONLYOFFICE (Conceptual/Prep)

14. Troubleshooting Common Issues

Login Failures

`ccnet.conf`

`seafile.conf`

`seahub_settings.py`