Skip to content

BlockStorage1/repertory

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

11 Commits
.cspell
.cspell
Β 
Β 
assets
assets
Β 
Β 
cmake
cmake
Β 
Β 
docker
docker
Β 
Β 
repertory
repertory
Β 
Β 
scripts
scripts
Β 
Β 
support
support
Β 
Β 
web/repertory
web/repertory
Β 
Β 
.clang-format
.clang-format
Β 
Β 
.clang-tidy
.clang-tidy
Β 
Β 
.clangd
.clangd
Β 
Β 
.gitattributes
.gitattributes
Β 
Β 
.gitignore
.gitignore
Β 
Β 
.jenkins_builds
.jenkins_builds
Β 
Β 
.jenkins_macos
.jenkins_macos
Β 
Β 
.jenkins_msys2
.jenkins_msys2
Β 
Β 
.nvimrc
.nvimrc
Β 
Β 
CHANGELOG.md
CHANGELOG.md
Β 
Β 
CMakeLists.txt
CMakeLists.txt
Β 
Β 
CONTRIBUTORS.md
CONTRIBUTORS.md
Β 
Β 
LICENSE.md
LICENSE.md
Β 
Β 
README.md
README.md
Β 
Β 
config.sh
config.sh
Β 
Β 
developer.pub
developer.pub
Β 
Β 
post_build.sh
post_build.sh
Β 
Β 
project.cmake
project.cmake
Β 
Β 

Repository files navigation

Repertory

/rΔ•pβ€²Ι™r-tΓ΄rβ€³Δ“/
noun
A place, such as a storehouse, where a stock of things is kept; a repository

Repertory allows you to mount S3 and Sia storage as local drives using:

  • FUSE (Linux/macOS)
  • WinFSP (Windows)

It supports:

  • Local mounts
  • Remote encrypted mounts between systems
  • Optional file name and data encryption using XChaCha20-Poly1305 and Argon2id for key generation

πŸ“– Contents

  1. Quick Start (Sia Example)
  2. Details & Features
  3. Minimum Requirements
  4. Data Directories
  5. GUI
  6. Usage
  7. Sia Setup
  8. S3 Setup
  9. Remote Mounting
  10. Compiling from Source
  11. Credits
  12. Developer Public Key
  13. Consult the Wiki for additional information

πŸš€ Quick Start (Sia Example)

πŸ’‘ Want to mount S3 instead?
Skip ahead to S3 Setup β€” the process is almost identical.

This example mounts a Sia bucket from a running renterd instance.

1. Install dependencies

Linux

sudo apt install fuse3   # Debian/Ubuntu
# or
sudo dnf install fuse3   # Fedora

macOS

Windows

2. Configure

Replace placeholders with your actual values:

repertory --name mybucket -set HostConfig.ApiPassword "<renterd api password>"
repertory --name mybucket -set SiaConfig.Bucket "<bucket name>"

Optional:

# If renterd is not running locally
repertory --name mybucket -set HostConfig.HostNameOrIp "<hostname or IP>"

# If renterd uses a non-default port (default 9980)
repertory --name mybucket -set HostConfig.ApiPort <port>

3. Mount

Linux

repertory --name mybucket /mnt/mybucket

macOS

repertory --name mybucket /Volumes/mybucket

Windows

repertory --name mybucket t:

4. Unmount

repertory --name mybucket --unmount

✨ Details and Features

  • Optimized for Plex Media Server.
  • Remote mounting of repertory instances between Linux, macOS, and/or Windows.
    • Securely share your mounts over TCP/IP via XChaCha20-Poly1305 with other systems on your network or over the internet.
  • Cross-platform support (Linux, macOS, and Windows).
  • Optionally encrypt file names and file data via XChaCha20-Poly1305 in S3 mounts.

πŸ“‹ Minimum Requirements

  • Sia: renterd v2.0.0+ for Sia support
  • Linux: requires fusermount3; otherwise, repertory must be manually compiled with libfuse2 support
  • macOS: requires:
  • Windows: requires:

Supported Operating Systems

Only 64-bit operating systems are supported:

  • Linux arm64/aarch64
  • Linux x86_64
  • macOS arm64/aarch64
  • macOS x86_64
  • Windows x86_64 10, 11

πŸ“‚ Data Directories

Linux

~/.local/repertory2/s3
~/.local/repertory2/sia

Windows

%LOCALAPPDATA%\repertory2\s3
%LOCALAPPDATA%\repertory2\sia

IMPORTANT:
It is highly recommended to exclude these folders from any anti-virus/anti-malware applications as severe performance issues may arise. Excluding the mounted drive letter is also highly recommended.

πŸ–₯ GUI

As of v2.0.6-release, mounts can be managed using the Repertory Management Portal.

Launch the portal:

repertory -ui

⚠️ Security tip

  • Change the default UI credentials on first launch (ui.json) or via the portal
  • Default username: repertory
  • Default password: repertory

After first launch, ui.json will be created in the appropriate data directory (see Data Directories). Modify this file directly or use the portal to change the default credentials.

Screenshots

Login screen

alt text

Home screen

alt text

πŸ›  Usage

Important Options

  • --help
    Display all mount utility options.

  • -f
    Keep process in foreground on Linux.

  • --name, -na [name]
    Identifies a unique configuration name to support multiple mounts.
    The --name option can be set to any valid value allowed as a file name for your filesystem.
    The --name option is required.

  • -dc
    Display mount configuration.
    For Sia, the --name option is required.
    For S3, the -s3 and --name options are required.

Unmounting

Remote

repertory -rm 192.168.0.1:20000 --unmount

S3

repertory -s3 --name '<my config name>' --unmount

Sia

repertory --name '<my config name>' --unmount

πŸ”’ Security Best Practices

When enabling encryption tokens for S3 or remote mounts:

  • Use a long, random string.
  • Store it offline (password manager and an offline backup).
  • Losing it means permanent data loss.

☁️ Sia

Sia Initial Configuration

Required steps:

  • Set the appropriate bucket name and renterd API password in repertory configuration:
repertory --name '<my config name>' -set HostConfig.ApiPassword '<my password>'
repertory --name '<my config name>' -set SiaConfig.Bucket '<my bucket name>'

Optional steps:

  • Set a user name used during renterd basic authentication:
repertory --name '<my config name>' -set HostConfig.ApiUser '<my user>'
  • Set a custom agent string (default Sia-Agent):
repertory --name '<my config name>' -set HostConfig.AgentString '<my agent>'
  • Set the host name or IP of the renterd instance (default localhost):
repertory --name '<my config name>' -set HostConfig.HostNameOrIp '<my host name>'
  • Set the renterd API port (default 9980):
repertory --name '<my config name>' -set HostConfig.ApiPort 9981

Verify/view all configuration options:

repertory --name '<my config name>' -dc
# Example:
repertory --name my_bucket -dc

Sia Mounting

Linux

repertory --name '<my config name>' /mnt/location
# Example:
repertory --name my_bucket /mnt/location

macOS

repertory --name '<my config name>' /Volumes/mybucket
# Example:
repertory --name my_bucket /Volumes/mybucket

Windows

repertory --name '<my config name>' t:
# Example:
repertory --name my_bucket t:

Sia Configuration File

{
  "ApiPassword": "<random generated rpc password>",
  "ApiPort": 10000,
  "ApiUser": "repertory",
  "DatabaseType": "rocksdb",
  "DownloadTimeoutSeconds": 30,
  "EnableDownloadTimeout": true,
  "EnableDriveEvents": false,
  "EventLevel": "info",
  "EvictionDelayMinutes": 1,
  "EvictionUseAccessedTime": false,
  "HighFreqIntervalSeconds": 30,
  "HostConfig": {
    "AgentString": "Sia-Agent",
    "ApiPassword": "<renterd api password>",
    "ApiPort": 9980,
    "ApiUser": "",
    "HostNameOrIp": "localhost",
    "Path": "",
    "Protocol": "http",
    "TimeoutMs": 60000
  },
  "LowFreqIntervalSeconds": 3600,
  "MaxCacheSizeBytes": 21474836480,
  "MaxUploadCount": 5,
  "MedFreqIntervalSeconds": 120,
  "OnlineCheckRetrySeconds": 60,
  "PreferredDownloadType": "default",
  "RemoteMount": {
    "ApiPort": 20000,
    "ClientPoolSize": 20,
    "Enable": false,
    "EncryptionToken": ""
  },
  "RetryReadCount": 6,
  "RingBufferFileSize": 512,
  "SiaConfig": {
    "Bucket": "my_bucket"
  },
  "TaskWaitMs": 100,
  "Version": 1
}

πŸͺ£ S3

S3 Initial Configuration

Required steps:

  • Set the appropriate base URL:
repertory -s3 --name '<my config name>' -set S3Config.URL '<my url>'
# Example:
repertory -s3 --name minio -set S3Config.URL 'http://localhost:9000'
  • Set the appropriate bucket name:
repertory -s3 --name '<my config name>' -set S3Config.Bucket '<my bucket name>'
  • Set the appropriate access key:
repertory -s3 --name '<my config name>' -set S3Config.AccessKey '<my access key>'
  • Set the appropriate secret key:
repertory -s3 --name '<my config name>' -set S3Config.SecretKey '<my secret key>'
  • For Sia and most local S3 gateway instances, enable path style URLs:
repertory -s3 --name '<my config name>' -set S3Config.UsePathStyle true

Optional steps:

  • Set an appropriate region. Default is any:
repertory -s3 --name '<my config name>' -set S3Config.Region '<my region>'
  • Enable encrypted file names and file data. Set a strong, random encryption token and store it securely:
repertory -s3 --name '<my config name>' -set S3Config.EncryptionToken '<my strong password>'

Verify/view all configuration options:

repertory -s3 --name '<my config name>' -dc
# Example:
repertory -s3 --name minio -dc

S3 Mounting

Linux

repertory -s3 --name '<my config name>' /mnt/location
# Example:
repertory -s3 --name minio /mnt/location

macOS

repertory -s3 --name '<my config name>' /Volumes/minio
# Example:
repertory -s3 --name minio /Volumes/minio

Windows

repertory -s3 --name '<my config name>' t:
# Example:
repertory -s3 --name minio t:

S3 Configuration File

{
  "ApiPassword": "<random generated rpc password>",
  "ApiPort": 10100,
  "ApiUser": "repertory",
  "DatabaseType": "rocksdb",
  "DownloadTimeoutSeconds": 30,
  "EnableDownloadTimeout": true,
  "EnableDriveEvents": false,
  "EventLevel": "info",
  "EvictionDelayMinutes": 1,
  "EvictionUseAccessedTime": false,
  "HighFreqIntervalSeconds": 30,
  "LowFreqIntervalSeconds": 3600,
  "MaxCacheSizeBytes": 21474836480,
  "MaxUploadCount": 5,
  "MedFreqIntervalSeconds": 120,
  "OnlineCheckRetrySeconds": 60,
  "PreferredDownloadType": "default",
  "RemoteMount": {
    "ApiPort": 20100,
    "ClientPoolSize": 20,
    "Enable": false,
    "EncryptionToken": ""
  },
  "RetryReadCount": 6,
  "RingBufferFileSize": 512,
  "S3Config": {
    "AccessKey": "<my access key>",
    "Bucket": "<my bucket name>",
    "EncryptionToken": "",
    "Region": "any",
    "SecretKey": "<my secret key>",
    "TimeoutMs": 60000,
    "URL": "http://localhost:9000",
    "UsePathStyle": true,
    "UseRegionInURL": false
  },
  "TaskWaitMs": 100,
  "Version": 1
}

🌐 Remote Mounting

repertory allows local mounts to be shared with other computers on your network or over the internet. This option is referred to as remote mounting.

Server Setup

The following steps must be performed on the mount you wish to share with other systems. Changes to configuration will not take effect while a mount is active, so it is recommended to unmount beforehand.

Required steps:

  • Enable remote mount:

    • Sia

      repertory -set RemoteMount.Enable true
repertory --name '<my config name>' -set RemoteMount.Enable true

    • S3

      repertory -set RemoteMount.Enable true
repertory -s3 --name '<my config name>' -set RemoteMount.Enable true

  • Set a secure encryption token:

    • Sia

      repertory -set RemoteMount.EncryptionToken '<my secure password>'
repertory --name '<my config name>' -set RemoteMount.EncryptionToken '<my secure password>'

    • S3

      repertory -s3 --name '<my config name>' -set RemoteMount.EncryptionToken '<my secure password>'

Optional steps:

  • Change the port clients will use to connect to your mount:

    • Sia

      repertory -set RemoteMount.ApiPort 20000
repertory --name '<my config name>' -set RemoteMount.ApiPort 20000

    • S3

      repertory -s3 --name '<my config name>' -set RemoteMount.ApiPort 20000

IMPORTANT:

Be sure to configure your firewall to allow incoming TCP connections on the port configured in RemoteMount.ApiPort.

Remote Mount Configuration File Section

{
  "RemoteMount": {
    "ApiPort": 20000,
    "ClientPoolSize": 20,
    "Enable": true,
    "EncryptionToken": "<my secure password>"
  }
}

Client Setup

Client configuration is provider agnostic, so there's no need to specify -s3 for S3 providers.

Required steps:

  • Set the encryption token to the same value configured during server setup:
repertory -rm <host name or IP>:<port> -set RemoteConfig.EncryptionToken '<my secure password>'
# Replace <host name or IP> with the host name or IP of the server
# Replace <port> with the value of RemoteMount.ApiPort used in the server configuration
# Example:
repertory -rm 192.168.1.10:20000 -set RemoteConfig.EncryptionToken '<my secure password>'
repertory -rm my.host.com:20000 -set RemoteConfig.EncryptionToken '<my secure password>'

Client Remote Mounting

Linux
repertory -rm <host name or IP>:<port> /mnt/location
# Example:
repertory -rm 192.168.1.10:20000 /mnt/location
macOS
repertory -rm <host name or IP>:<port> /Volumes/remotemount
# Example:
repertory -rm 192.168.1.10:20000 /Volumes/remotemount
Windows
repertory -rm <host name or IP>:<port> t:
# Example:
repertory -rm 192.168.1.10:20000 t:

Remote Mount Configuration File

{
  "ApiPassword": "<random generated rpc password>",
  "ApiPort": 10010,
  "ApiUser": "repertory",
  "EnableDriveEvents": false,
  "EventLevel": "info",
  "RemoteConfig": {
    "ApiPort": 20000,
    "EncryptionToken": "<my secure password>",
    "HostNameOrIp": "192.168.1.10",
    "MaxConnections": 20,
    "ReceiveTimeoutMs": 120000,
    "SendTimeoutMs": 30000
  },
  "TaskWaitMs": 100,
  "Version": 1
}

🧰 Compiling

Successful compilation will place all required files for execution in the dist/ directory.

Linux Compilation

  • Ensure docker is installed

  • For x86_64:

    scripts/make_unix.sh x86_64
scripts/make_unix.sh x86_64 Release
scripts/make_unix.sh x86_64 Debug

  • For aarch64:

    scripts/make_unix.sh aarch64
scripts/make_unix.sh aarch64 Release
scripts/make_unix.sh aarch64 Debug

macOS Compilation

  • Ensure Xcode and CMake are installed

  • For x86_64:

    scripts/make_unix.sh x86_64
scripts/make_unix.sh x86_64 Release
scripts/make_unix.sh x86_64 Debug

  • For aarch64:

    scripts/make_unix.sh aarch64
scripts/make_unix.sh aarch64 Release
scripts/make_unix.sh aarch64 Debug

Windows Compilation

  • OFFICIAL: Cross-compiling on Linux

    • Ensure docker is installed

      scripts/make_win32.sh x86_64
scripts/make_win32.sh x86_64 Release
scripts/make_win32.sh x86_64 Debug

  • UNOFFICIAL: Compiling on Windows

    • Ensure latest MSYS2 is installed

      scripts\make_win32.cmd x86_64
scripts\make_win32.cmd x86_64 Release
scripts\make_win32.cmd x86_64 Debug

πŸ“œ Credits

πŸ”‘ Developer Public Key

-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAqXedleDOugdk9sBpgFOA
0+MogIbBF7+iXIIHv8CRBbrrf8nxLSgQvbHQIP0EklebDgLZRgyGI3SSQYj7D957
uNf1//dpkELNzfuezgAyFer9+iH4Svq46HADp5k+ugaK0mMDZM7OLOgo7415/+z4
NIQopv8prMFdxkShr4e4dpR+S6LYMYMVjsi1gnYWaZJMWgzeZouXFSscS1/XDXSE
vr1Jfqme+RmB4Q2QqGcDrY2ijumCJYJzQqlwG6liJ4FNg0U3POTCQDhQmuUoEJe0
/dyiWlo48WQbBu6gUDHbTCCUSZPs2Lc9l65MqOCpX76+VXPYetZgqpMF4GVzb2y9
kETxFNpiMYBlOBZk0I1G33wqVmw46MI5IZMQ2z2F8Mzt1hByUNTgup2IQELCv1a5
a2ACs2TBRuAy1REeHhjLgiA/MpoGX7TpoHCGyo8jBChJVpP9ZHltKoChwDC+bIyx
rgYH3jYDkl2FFuAUJ8zAZl8U1kjqZb9HGq9ootMk34Dbo3IVkc2azB2orEP9F8QV
KxvZZDA9FAFEthSiNf5soJ6mZGLi0es5EWPoKMUEd9tG5bP980DySAWSSRK0AOfE
QShT/z7oG79Orxyomwrb8ZJCi7wEfcCuK1NWgqLVUgXhpi2J9WYS6DAbF3Oh3Hhl
DYSHlcfFBteqNDlR2uFInIECAwEAAQ==
-----END PUBLIC KEY-----

About

Repertory allows you to mount AWS S3 and Sia via FUSE on Linux/macOS or via WinFSP on Windows.

git.fifthgrid.com/BlockStorage/repertory

Topics

fuse blockchain s3 sia winfsp renterd

Resources

Readme

License

View license
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

1 fork
Report repository

Releases 5

v2.0.7-release Latest
Jul 31, 2025
+ 4 releases

Languages