evanqu/foliopath repository overview

⁠FolioPath

English⁠ · 简体中文⁠

📚 A read-only, self-hosted media browser built for browsing complete photo and video sets

No imports. No reorganization. Browse the folders you already have while your originals remain untouched.

⭐ Enjoying FolioPath? Your stars help more people discover the project.

FolioPath directly reads an existing directory tree and lets you browse a folder and all its descendants as one set. It is designed for photography archives, family media, NAS libraries, and collections already organized by project, trip, event, person, or date.

⁠Highlights

• Browse a directory and its descendants without creating albums.
• Keep source paths visible in aggregated views.
• Use adaptive grid and masonry layouts for mixed media dimensions.
• Search by filename, path, media type, date, and scope.
• Zoom, pan, view at 1:1, navigate between items, use fullscreen, and play videos.
• Configure multiple non-overlapping libraries below one read-only /library mount.
• Preserve the last reliable index when a library is offline or a scan is interrupted.
• Run as one container with SQLite and rebuildable thumbnails and posters.

⁠Supported media

Videos are not transcoded, so direct playback depends on browser codec support. SVG, HEIC/HEIF, AVIF, RAW, and other unlisted formats are outside the current support contract.

⁠Quick start

FolioPath requires Linux on amd64 or arm64, Docker, and Docker Compose v2.

Create an empty directory, save the following as compose.yaml, and replace /mnt/photos with the single host directory containing your media:

services:
  foliopath:
    image: evanqu/foliopath:latest
    restart: unless-stopped
    environment:
      TZ: Asia/Shanghai
    ports:
      - "8080:8080"
    volumes:
      - /mnt/photos:/library:ro
      - ./data:/app/data

Start the container:

docker compose up -d

Open http://<your-server-LAN-address>:8080, create the administrator account, then add directories under Administration → Libraries.

For controlled upgrades, replace latest with a specific version tag or immutable digest. See the repository's authoritative Compose file⁠ for configurable path, address, port, image, and timezone values.

⁠Storage and permissions

The container runs as root so a bind-mounted ./data directory created by Docker is writable without a host-side ownership step. Keep /library read-only; root runtime increases the impact of a container compromise, so do not expose FolioPath directly to an untrusted network.

Mount the media tree exactly once at /library. Nested volumes, bind mounts, or other mount points below /library are unsupported and rejected. FolioPath never moves, renames, edits, or deletes original media.

⁠Network safety

Direct HTTP is intended for an authenticated, trusted LAN. For public or otherwise untrusted network access, use an external HTTPS reverse proxy and prevent clients from bypassing it. Review the deployment guide⁠ and security model⁠ before exposing the service.

⁠Documentation and support

• English project overview⁠
• 简体中文项目说明⁠
• Deployment, upgrades, backup, restore, and reverse proxy⁠
• Documentation index⁠
• Issue tracker⁠
• AGPL-3.0-or-later license⁠

Your folders, beautifully browsed.

⁠简体中文

English⁠ · 简体中文⁠

FolioPath 是一款为整套照片和视频浏览而生的只读、自托管媒体浏览器。它直接读取现有目录树，让你把一个文件夹及其所有子目录作为完整内容集浏览，不需要重新上传、建立相册或改变原有归档方式。

适合摄影归档、家庭影像、NAS 媒体库，以及已经按作品、旅行、活动、人物或日期整理好的收藏。

⭐ 喜欢 FolioPath？你的 Star 能帮助更多人发现这个项目。

⁠主要功能

• 穿透浏览文件夹及其所有子目录，无需另建相册。
• 汇总浏览时保留媒体来源路径。
• 使用自适应网格和瀑布流展示不同尺寸的媒体。
• 按文件名、路径、媒体类型、日期和范围搜索。
• 支持缩放、平移、1:1、前后切换、全屏和视频播放。
• 在唯一的只读 /library 挂载下配置多个互不重叠的媒体库。
• 媒体库离线或扫描中断时保留最后可靠索引。
• 使用单容器和 SQLite，并可重建缩略图和视频封面。

⁠支持格式

视频不会转码，能否直接播放取决于浏览器支持的内部编码。SVG、HEIC/HEIF、AVIF、RAW 以及其他未列出的格式不在当前支持范围内。

⁠快速开始

需要 Linux amd64 或 arm64、Docker 和 Docker Compose v2。

新建一个空目录，把下面内容保存为 compose.yaml，并将 /mnt/photos 替换为宿主机上唯一的媒体根目录：

services:
  foliopath:
    image: evanqu/foliopath:latest
    restart: unless-stopped
    environment:
      TZ: Asia/Shanghai
    ports:
      - "8080:8080"
    volumes:
      - /mnt/photos:/library:ro
      - ./data:/app/data

启动容器：

docker compose up -d

打开 http://<服务器局域网地址>:8080，创建管理员账户，然后在 管理中心 → 媒体库 中添加要浏览的目录。

需要可控升级时，请把 latest 替换为明确版本标签或不可变 digest。路径、监听地址、端口、镜像和时区等可配置项见仓库中的权威 Compose 文件⁠。

⁠存储与权限

容器以 root 运行，因此 Docker 自动创建的 bind mount ./data 无需在宿主机额外修改所有权即可写入。必须保持 /library 只读；root 运行会扩大容器被攻破后的影响，因此不要把 FolioPath 直接暴露到不可信网络。

媒体目录只能整体挂载一次到 /library。不支持并会拒绝 /library 下的嵌套 volume、bind mount 或其他挂载点。FolioPath 不会移动、重命名、编辑或删除原始媒体。

⁠网络安全

直接 HTTP 仅适用于经过认证的受信局域网。若要通过公网或其他不可信网络访问，请使用外部 HTTPS 反向代理，并阻止客户端绕过代理直连应用。暴露服务前请阅读部署指南⁠和安全模型⁠。

⁠文档与支持

• 简体中文项目说明⁠
• English project overview⁠
• 部署、升级、备份、恢复与反向代理⁠
• 项目文档索引⁠
• 问题反馈⁠
• AGPL-3.0-or-later 许可证⁠

Your folders, beautifully browsed.