Skip to content

server-install.md

Latest commit

 

History

History
362 lines (263 loc) · 11.3 KB

server-install.md

File metadata and controls

362 lines (263 loc) · 11.3 KB

FileDepot Server Install

This guide turns a clean Linux machine into a FileDepot server.

The current server distribution is Docker-based. It keeps this repository as the single entry point for FileDepot while using compatible server containers underneath. Over time, those server components can be rebranded, wrapped, or replaced more deeply.

Requirements

  • Ubuntu or Debian-style Linux host.
  • Root access or sudo.
  • Public DNS name or LAN IP address for the server.
  • At least 2 GB RAM and 2 CPU cores recommended.

Quick Install

From the FileDepot repository:

sudo FILEDEPOT_HOSTNAME=depot.example.com \
  FILEDEPOT_PROTOCOL=https \
  FILEDEPOT_ADMIN_EMAIL=admin@example.com \
  FILEDEPOT_ADMIN_PASSWORD='change-this-password' \
  scripts/install-filedepot-server.sh

This creates an HTTPS FileDepot server. Point DNS at the server first if you are using a hostname, and keep ports 80 and 443 open.

For a LAN-only install, use the server IP instead of a DNS name:

sudo FILEDEPOT_HOSTNAME=192.168.1.50 \
  FILEDEPOT_PROTOCOL=http \
  FILEDEPOT_ADMIN_EMAIL=admin@example.com \
  FILEDEPOT_ADMIN_PASSWORD='change-this-password' \
  scripts/install-filedepot-server.sh

Trusted HTTPS generally needs a DNS hostname that points to your server. Browsers may warn when using HTTPS directly against a private IP address.

The installer writes compose files to:

/opt/filedepot

Persistent data is stored under:

/opt/filedepot-data
/opt/filedepot-mysql
/opt/filedepot-caddy

Check The Server

sudo /opt/filedepot/smoke-test-filedepot-server.sh

The smoke test checks the containers, Seahub startup, public login page, branding assets, Wiki disablement, and captcha lockout settings. It exits nonzero and prints recent logs if the build is not healthy.

If the server has moved and .env still contains an older internal hostname, point the smoke test at the current reachable URL without changing the repo:

sudo FILEDEPOT_SMOKE_BASE_URL=https://your-current-host /opt/filedepot/smoke-test-filedepot-server.sh

You can also inspect containers manually:

cd /opt/filedepot
sudo docker compose ps
sudo docker compose logs --tail=100

Open the server in a browser:

https://your-hostname

Doctor And Repair

Run the doctor when anything looks odd after an install, update, hostname change, or server move:

sudo /opt/filedepot/filedepot-doctor.sh

Apply the safe repair pass:

sudo /opt/filedepot/filedepot-doctor.sh --repair

The doctor checks Docker, Compose, environment values, container health, Seahub startup, branding settings, Wiki disablement, captcha cleanup, public assets, and then runs the smoke test.

Backup And Restore

Create a backup:

sudo /opt/filedepot/filedepot-backup.sh

Backups are written to /opt/filedepot-backups by default and include:

  • /opt/filedepot
  • /opt/filedepot-data, excluding logs
  • a MariaDB dump when the database container is reachable

Restore a backup:

sudo /opt/filedepot/filedepot-restore.sh /opt/filedepot-backups/filedepot-backup-YYYYmmdd-HHMMSS.tar.gz

Keep production backups outside the server as well as on the server.

Semantic Search

FileDepot includes a semantic search sidecar. It returns ranked files and passages, and can optionally generate cited answers when an AI provider is configured. The sidecar forwards the signed-in user's FileDepot session cookie to the internal server API, so it indexes only depots and files that user can already access.

Fresh installs enable semantic search by default. To enable it on an existing server:

cd ~/FileDepot
git pull
sudo scripts/enable-filedepot-ai-search.sh
sudo scripts/apply-filedepot-server-branding.sh

To disable it during install:

sudo FILEDEPOT_ENABLE_AI_SEARCH=0 scripts/install-filedepot-server.sh

To enable Claude answers, add these values to /opt/filedepot/.env, then rerun sudo scripts/enable-filedepot-ai-search.sh from the repo:

FILEDEPOT_AI_PROVIDER=anthropic
FILEDEPOT_AI_MODEL=claude-haiku-4-5-20251001
ANTHROPIC_API_KEY=your-key-here
FILEDEPOT_AI_REDACT_SECRETS=true
FILEDEPOT_AI_MAX_PROVIDER_PASSAGE_CHARS=1400
FILEDEPOT_AI_ANSWER_CACHE_TTL=604800
FILEDEPOT_AI_MAX_RAG_PASSAGES=12

Keep the key out of git. The provider layer is intentionally configurable so FileDepot can support local/on-prem inference endpoints later.

System Admin includes an AI Providers panel that drafts these server settings plus embedding, vector, redaction, cache, and source-limit options. The panel outputs .env lines to apply on the server; it does not store API keys or secrets in the browser. Use Copy apply command from that panel on the FileDepot server to validate settings, update /opt/filedepot/.env, rebuild/restart AI search, and reapply branding.

External providers receive only the top matched passages, not whole files. Before a passage is sent out, FileDepot masks likely passwords, API keys, tokens, private keys, bearer/basic auth values, and connection-string passwords. Leave FILEDEPOT_AI_REDACT_SECRETS=true for cloud providers.

When an answer provider is enabled, FileDepot uses a retrieval-augmented generation flow: retrieve permission-scoped passages, ask the provider for a short JSON answer, show optional detail bullets, and render clickable source references back to the matching FileDepot documents.

Answers are cached for seven days by default to reduce token usage. Cache keys include the signed-in user's session, query, provider/model, redaction setting, and selected source passages. Users still see fresh search results while cached answers display their age in the answer card.

The AI sidecar also includes a vector retrieval foundation. By default it uses local_hash, a deterministic local embedding provider that stores passage vectors in SQLite without calling an external provider. Keyword scoring remains primary, and vector scores are blended in with a bounded weight so exact matches stay stable while the code path is ready for Qdrant, pgvector, OpenSearch, cloud embedding providers, or on-prem embedding providers later.

Optional vector settings:

FILEDEPOT_AI_VECTOR_SEARCH=true
FILEDEPOT_AI_EMBEDDING_PROVIDER=local_hash
FILEDEPOT_AI_EMBEDDING_MODEL=local_hash
FILEDEPOT_AI_VECTOR_STORE_BACKEND=sqlite
FILEDEPOT_AI_VECTOR_DIMENSIONS=384
FILEDEPOT_AI_VECTOR_WEIGHT=0.25
FILEDEPOT_AI_VECTOR_MIN_SCORE=0.08

FILEDEPOT_AI_VECTOR_BACKEND=local_hash remains supported as a legacy alias for the embedding provider.

External Sources

FileDepot includes an administrator-facing External Sources panel in System Admin. Use it to draft read-only SMB, NTFS, or mounted-folder sources that will be connected to the AI indexing pipeline in a later permission-safe phase.

For now, mount the source on the Docker host first, then describe the mounted path with FILEDEPOT_AI_EXTERNAL_SOURCES_JSON in /opt/filedepot/.env:

FILEDEPOT_AI_EXTERNAL_SOURCES_JSON=[{"name":"Accounting Share","path":"/mnt/filedepot-sources/accounting","type":"smb","enabled":true,"read_only":true,"permission_mode":"admin","notes":"Mounted read-only on the FileDepot server"}]

Do not put passwords, access keys, or SMB credentials in the UI or this environment value. Keep credentials in the operating system mount configuration or a secrets manager. The sidecar exposes a sanitized status at /ai-search/external-sources; indexing for these paths remains off until the connector permission model is enabled.

FileDepot Server Image

The repo includes a first-class image scaffold at docker/filedepot-server/Dockerfile. It extends the compatible server base image and bakes in FileDepot branding assets plus a startup branding hook.

Build locally:

docker build -f docker/filedepot-server/Dockerfile -t filedepot-server:local .

Use it for an install:

sudo FILEDEPOT_IMAGE=filedepot-server:local scripts/install-filedepot-server.sh

This image path is the place to move more branding and compatibility logic over time so FileDepot becomes less dependent on runtime patching.

Releases

FileDepot versions use the date-based vYYYY.MM.DD.NNN pattern (e.g. v2026.06.04.001). Once the tree is clean and the smoke test passes, create and push a release tag:

scripts/create-filedepot-release.sh v2026.06.04.002

Use the admin email/password you supplied during install.

For a LAN-only install, open:

http://your-server-ip

Apply FileDepot Branding

The installer applies the official FileDepot brand assets, login background, admin info text, FileDepot version, blue UI accents, About dialog, help cleanup, and AI search wording automatically. To reapply branding after an existing install:

cd ~/FileDepot
git pull
sudo scripts/apply-filedepot-server-branding.sh

The helper writes the official FileDepot brand assets under Seahub's seahub-data/custom directory:

  • filedepot_app_icon.png - square app icon, 1024x1024
  • filedepot_wordmark.png - horizontal wordmark, 149x32
  • filedepot_favicon.png - favicon/app icon, 32x32

It also updates seahub_settings.py with:

SITE_NAME = 'FileDepot'
SITE_TITLE = 'FileDepot'
ENABLE_SETTINGS_VIA_WEB = False
LOGO_PATH = 'custom/filedepot_wordmark.png'
LOGO_WIDTH = 149
LOGO_HEIGHT = 32
FAVICON_PATH = 'custom/filedepot_favicon.png'
BRANDING_CSS = 'custom/filedepot_branding.css?v=<asset-version>'
LOGIN_ATTEMPT_LIMIT = 1000000
FREEZE_USER_ON_LOGIN_FAILED = False
ENABLE_WIKI = False

FileDepot versions use a date-based scheme: vYYYY.MM.DD.NNN, where the first three parts are the calendar date and NNN is a zero-padded build counter that resets each day (e.g. v2026.06.04.001, then v2026.06.04.002 later the same day). The current version lives in the VERSION file; the branding helper uses it by default and rewrites the System Admin info page so it no longer displays "Community Edition" or the upstream server version. To preview or apply a specific version:

sudo FILEDEPOT_VERSION=v2026.06.04.002 scripts/apply-filedepot-server-branding.sh

If your install uses non-default paths, pass them explicitly:

sudo FILEDEPOT_INSTALL_DIR=/opt/filedepot \
  FILEDEPOT_DATA_DIR=/opt/filedepot-data \
  scripts/apply-filedepot-server-branding.sh

Force Existing Install To HTTPS

For an existing FileDepot server, update the deployed protocol without recreating data:

cd ~/FileDepot
git pull
sudo scripts/set-filedepot-server-https.sh

Then open:

https://your-hostname-or-ip

Start, Stop, Restart

cd /opt/filedepot
sudo docker compose up -d
sudo docker compose stop
sudo docker compose restart

Reset Or Add Admin User

sudo docker exec -it seafile /opt/seafile/seafile-server-latest/reset-admin.sh

Clean Test Reinstall

This deletes server data. Use only on a throwaway test machine.

cd /opt/filedepot
sudo docker compose down
sudo rm -rf /opt/filedepot /opt/filedepot-data /opt/filedepot-mysql /opt/filedepot-caddy

Then rerun the installer.

Notes

  • The client command names currently remain seaf-cli and seaf-daemon.
  • The first server package is intentionally deployment-focused. It gives users one FileDepot repo to clone and one server install path to run.
  • Future work should replace visible compatibility names, fork or vendor required server-side dependencies, and provide branded server container images.