BlockStorage/repertory
1
0
Fork 0
Code Issues 4 Pull Requests Releases 8 Wiki Activity

updated README.md
All checks were successful
BlockStorage/repertory/pipeline/head This commit looks good
Details

Browse Source
This commit is contained in:
Scott E. Graves
2025-09-09 10:25:52 -05:00
parent d6b9a73570
commit b72c1822d5
1 changed files with 177 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files

261
README.md
View File

@@ -1,10 +1,12 @@
# Repertory # Repertory
Repertory allows you to mount **S3** and **Sia** storage as local drives using: Repertory allows you to mount **S3** and **Sia** storage as local drives using:
- **FUSE** (Linux/macOS) - **FUSE** (Linux/macOS)
- **WinFSP** (Windows) - **WinFSP** (Windows)
It supports: It supports:
- Local mounts - Local mounts
- Remote encrypted mounts between systems - Remote encrypted mounts between systems
- Optional file name and data encryption using `XChaCha20-Poly1305` - Optional file name and data encryption using `XChaCha20-Poly1305`
@@ -55,17 +57,20 @@ This example mounts a Sia bucket from a running [renterd](https://github.com/Sia
### 1. Install dependencies ### 1. Install dependencies
**Linux** #### Linux
```bash
``` shell
sudo apt install fuse3 # Debian/Ubuntu sudo apt install fuse3 # Debian/Ubuntu
# or # or
sudo dnf install fuse3 # Fedora sudo dnf install fuse3 # Fedora
``` ```
**macOS** #### macOS
- Install [macFUSE 4.10.2](https://github.com/macfuse/macfuse/releases/download/macfuse-4.10.2/macfuse-4.10.2.dmg) - Install [macFUSE 4.10.2](https://github.com/macfuse/macfuse/releases/download/macfuse-4.10.2/macfuse-4.10.2.dmg)
**Windows** #### Windows
- Install [WinFSP 2025](https://github.com/winfsp/winfsp/releases/download/v2.1/winfsp-2.1.25156.msi) - Install [WinFSP 2025](https://github.com/winfsp/winfsp/releases/download/v2.1/winfsp-2.1.25156.msi)
--- ---
@@ -73,13 +78,15 @@ sudo dnf install fuse3 # Fedora
### 2. Configure ### 2. Configure
Replace placeholders with your values: Replace placeholders with your values:
```bash
``` shell
repertory --name mybucket -set HostConfig.ApiPassword "<renterd api password>" repertory --name mybucket -set HostConfig.ApiPassword "<renterd api password>"
repertory --name mybucket -set SiaConfig.Bucket "<bucket name>" repertory --name mybucket -set SiaConfig.Bucket "<bucket name>"
``` ```
Optional: Optional:
```bash
``` shell
# If renterd is not running locally # If renterd is not running locally
repertory --name mybucket -set HostConfig.HostNameOrIp "<hostname or IP>" repertory --name mybucket -set HostConfig.HostNameOrIp "<hostname or IP>"
@@ -91,18 +98,24 @@ repertory --name mybucket -set HostConfig.ApiPort <port>
### 3. Mount ### 3. Mount
**Linux** <!-- markdownlint-disable-next-line -->
```bash #### Linux
``` shell
repertory --name mybucket /mnt/mybucket repertory --name mybucket /mnt/mybucket
``` ```
**macOS** <!-- markdownlint-disable-next-line -->
```bash #### macOS
``` shell
repertory --name mybucket /Volumes/mybucket repertory --name mybucket /Volumes/mybucket
``` ```
**Windows** <!-- markdownlint-disable-next-line -->
```powershell #### Windows
``` shell
repertory --name mybucket t: repertory --name mybucket t:
``` ```
@@ -110,19 +123,8 @@ repertory --name mybucket t:
### 4. Unmount ### 4. Unmount
**Linux** ``` shell
```bash repertory --name mybucket --unmount
fusermount3 -u /mnt/mybucket
```
**macOS**
```bash
diskutil unmount /Volumes/mybucket
```
**Windows**
```powershell
net use t: /delete
``` ```
--- ---
@@ -160,17 +162,22 @@ Only **64-bit operating systems** are supported:
## 📂 Data Directories ## 📂 Data Directories
**Linux** <!-- markdownlint-disable-next-line -->
``` ### Linux
``` shell
~/.local/repertory2/s3 ~/.local/repertory2/s3
~/.local/repertory2/sia ~/.local/repertory2/sia
``` ```
**Windows** <!-- markdownlint-disable-next-line -->
``` ### Windows
``` shell
%LOCALAPPDATA%\repertory2\s3 %LOCALAPPDATA%\repertory2\s3
%LOCALAPPDATA%\repertory2\sia %LOCALAPPDATA%\repertory2\sia
``` ```
**IMPORTANT:** **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. 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.
@@ -181,9 +188,11 @@ It is highly recommended to **exclude** these folders from any anti-virus/anti-m
As of `v2.0.6-release`, mounts can be managed using the **Repertory Management Portal**. As of `v2.0.6-release`, mounts can be managed using the **Repertory Management Portal**.
Launch the portal: Launch the portal:
```bash
``` shell
repertory -ui repertory -ui
``` ```
- Default username: `repertory` - Default username: `repertory`
- Default password: `repertory` - Default password: `repertory`
@@ -223,19 +232,28 @@ After first launch, `ui.json` will be created in the appropriate data directory
### Unmounting ### Unmounting
**Linux** #### Encrypt
```bash
fusermount3 -u /path/to/mountpoint ``` shell
repertory -en --name '<my config name>' --unmount
``` ```
**macOS** #### Remote
```bash
diskutil unmount /Volumes/yourmount ``` shell
repertory -rm 192.168.0.1:10000 --unmount
``` ```
**Windows** #### S3
```powershell
net use <driveletter>: /delete ``` shell
repertory --name '<my config name>' --unmount
```
### Sia
``` shell
repertory -s3 --name '<my config name>' --unmount
``` ```
--- ---
@@ -243,6 +261,7 @@ net use <driveletter>: /delete
## 🔒 Security Best Practices ## 🔒 Security Best Practices
When enabling **encryption tokens** for S3 or remote mounts: When enabling **encryption tokens** for S3 or remote mounts:
- Use a **long, random string**. - Use a **long, random string**.
- Store it **offline** (password manager and an offline backup). - Store it **offline** (password manager and an offline backup).
- Losing it means **permanent data loss**. - Losing it means **permanent data loss**.
@@ -254,32 +273,43 @@ When enabling **encryption tokens** for S3 or remote mounts:
### Sia Initial Configuration ### Sia Initial Configuration
**Required steps:** **Required steps:**
- Set the appropriate bucket name and `renterd` API password in `repertory` configuration: - Set the appropriate bucket name and `renterd` API password in `repertory` configuration:
```bash
``` shell
repertory --name '<my config name>' -set HostConfig.ApiPassword '<my password>' repertory --name '<my config name>' -set HostConfig.ApiPassword '<my password>'
repertory --name '<my config name>' -set SiaConfig.Bucket '<my bucket name>' repertory --name '<my config name>' -set SiaConfig.Bucket '<my bucket name>'
``` ```
**Optional steps:** **Optional steps:**
- Set a user name used during `renterd` basic authentication: - Set a user name used during `renterd` basic authentication:
```bash
``` shell
repertory --name '<my config name>' -set HostConfig.ApiUser '<my user>' repertory --name '<my config name>' -set HostConfig.ApiUser '<my user>'
``` ```
- Set a custom agent string (default `Sia-Agent`): - Set a custom agent string (default `Sia-Agent`):
```bash
``` shell
repertory --name '<my config name>' -set HostConfig.AgentString '<my agent>' repertory --name '<my config name>' -set HostConfig.AgentString '<my agent>'
``` ```
- Set the host name or IP of the `renterd` instance (default `localhost`): - Set the host name or IP of the `renterd` instance (default `localhost`):
```bash
``` shell
repertory --name '<my config name>' -set HostConfig.HostNameOrIp '<my host name>' repertory --name '<my config name>' -set HostConfig.HostNameOrIp '<my host name>'
``` ```
- Set the `renterd` API port (default `9980`): - Set the `renterd` API port (default `9980`):
```bash
``` shell
repertory --name '<my config name>' -set HostConfig.ApiPort 9981 repertory --name '<my config name>' -set HostConfig.ApiPort 9981
``` ```
**Verify/view all configuration options:** **Verify/view all configuration options:**
```bash
``` shell
repertory --name '<my config name>' -dc repertory --name '<my config name>' -dc
# Example: # Example:
repertory --name my_bucket -dc repertory --name my_bucket -dc
@@ -287,22 +317,28 @@ repertory --name my_bucket -dc
### Sia Mounting ### Sia Mounting
**Linux** <!-- markdownlint-disable-next-line -->
```bash #### Linux
``` shell
repertory --name '<my config name>' /mnt/location repertory --name '<my config name>' /mnt/location
# Example: # Example:
repertory --name my_bucket /mnt/location repertory --name my_bucket /mnt/location
``` ```
**macOS** <!-- markdownlint-disable-next-line -->
```bash #### macOS
``` shell
repertory --name '<my config name>' /Volumes/mybucket repertory --name '<my config name>' /Volumes/mybucket
# Example: # Example:
repertory --name my_bucket /Volumes/mybucket repertory --name my_bucket /Volumes/mybucket
``` ```
**Windows** <!-- markdownlint-disable-next-line -->
```powershell #### Windows
``` shell
repertory --name '<my config name>' t: repertory --name '<my config name>' t:
# Example: # Example:
repertory --name my_bucket t: repertory --name my_bucket t:
@@ -362,41 +398,56 @@ repertory --name my_bucket t:
### S3 Initial Configuration ### S3 Initial Configuration
**Required steps:** **Required steps:**
- Set the appropriate base URL: - Set the appropriate base URL:
```bash
``` shell
repertory -s3 --name '<my config name>' -set S3Config.URL '<my url>' repertory -s3 --name '<my config name>' -set S3Config.URL '<my url>'
# Example: # Example:
repertory -s3 --name minio -set S3Config.URL 'http://localhost:9000' repertory -s3 --name minio -set S3Config.URL 'http://localhost:9000'
``` ```
- Set the appropriate bucket name: - Set the appropriate bucket name:
```bash
``` shell
repertory -s3 --name '<my config name>' -set S3Config.Bucket '<my bucket name>' repertory -s3 --name '<my config name>' -set S3Config.Bucket '<my bucket name>'
``` ```
- Set the appropriate access key: - Set the appropriate access key:
```bash
``` shell
repertory -s3 --name '<my config name>' -set S3Config.AccessKey '<my access key>' repertory -s3 --name '<my config name>' -set S3Config.AccessKey '<my access key>'
``` ```
- Set the appropriate secret key: - Set the appropriate secret key:
```bash
``` shell
repertory -s3 --name '<my config name>' -set S3Config.SecretKey '<my 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: - For Sia and most local S3 gateway instances, enable path style URLs:
```bash
``` shell
repertory -s3 --name '<my config name>' -set S3Config.UsePathStyle true repertory -s3 --name '<my config name>' -set S3Config.UsePathStyle true
``` ```
**Optional steps:** **Optional steps:**
- Set an appropriate region. Default is `any`: - Set an appropriate region. Default is `any`:
```bash
``` shell
repertory -s3 --name '<my config name>' -set S3Config.Region '<my region>' 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: - Enable encrypted file names and file data. Set a strong, random encryption token and store it securely:
```bash
``` shell
repertory -s3 --name '<my config name>' -set S3Config.EncryptionToken '<my strong password>' repertory -s3 --name '<my config name>' -set S3Config.EncryptionToken '<my strong password>'
``` ```
**Verify/view all configuration options:** **Verify/view all configuration options:**
```bash
``` shell
repertory -s3 --name '<my config name>' -dc repertory -s3 --name '<my config name>' -dc
# Example: # Example:
repertory -s3 --name minio -dc repertory -s3 --name minio -dc
@@ -404,22 +455,28 @@ repertory -s3 --name minio -dc
### S3 Mounting ### S3 Mounting
**Linux** <!-- markdownlint-disable-next-line -->
```bash #### Linux
``` shell
repertory -s3 --name '<my config name>' /mnt/location repertory -s3 --name '<my config name>' /mnt/location
# Example: # Example:
repertory -s3 --name minio /mnt/location repertory -s3 --name minio /mnt/location
``` ```
**macOS** <!-- markdownlint-disable-next-line -->
```bash #### macOS
``` shell
repertory -s3 --name '<my config name>' /Volumes/minio repertory -s3 --name '<my config name>' /Volumes/minio
# Example: # Example:
repertory -s3 --name minio /Volumes/minio repertory -s3 --name minio /Volumes/minio
``` ```
**Windows** <!-- markdownlint-disable-next-line -->
```powershell #### Windows
``` shell
repertory -s3 --name '<my config name>' t: repertory -s3 --name '<my config name>' t:
# Example: # Example:
repertory -s3 --name minio t: repertory -s3 --name minio t:
@@ -481,40 +538,56 @@ repertory -s3 --name minio t:
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. 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:** **Required steps:**
- Enable remote mount: - Enable remote mount:
- **Sia** - **Sia**
```bash
``` shell
repertory -set RemoteMount.Enable true repertory -set RemoteMount.Enable true
repertory --name '<my config name>' -set RemoteMount.Enable true repertory --name '<my config name>' -set RemoteMount.Enable true
``` ```
- **S3** - **S3**
```bash
``` shell
repertory -s3 --name '<my config name>' -set RemoteMount.Enable true repertory -s3 --name '<my config name>' -set RemoteMount.Enable true
``` ```
- Set a secure encryption token: - Set a secure encryption token:
- **Sia** - **Sia**
```bash
``` shell
repertory -set RemoteMount.EncryptionToken '<my secure password>' repertory -set RemoteMount.EncryptionToken '<my secure password>'
repertory --name '<my config name>' -set RemoteMount.EncryptionToken '<my secure password>' repertory --name '<my config name>' -set RemoteMount.EncryptionToken '<my secure password>'
``` ```
- **S3** - **S3**
```bash
``` shell
repertory -s3 --name '<my config name>' -set RemoteMount.EncryptionToken '<my secure password>' repertory -s3 --name '<my config name>' -set RemoteMount.EncryptionToken '<my secure password>'
``` ```
**Optional steps:** **Optional steps:**
- Change the port clients will use to connect to your mount: - Change the port clients will use to connect to your mount:
- **Sia** - **Sia**
```bash
``` shell
repertory -set RemoteMount.ApiPort 20000 repertory -set RemoteMount.ApiPort 20000
repertory --name '<my config name>' -set RemoteMount.ApiPort 20000 repertory --name '<my config name>' -set RemoteMount.ApiPort 20000
``` ```
- **S3** - **S3**
```bash
``` shell
repertory -s3 --name '<my config name>' -set RemoteMount.ApiPort 20000 repertory -s3 --name '<my config name>' -set RemoteMount.ApiPort 20000
``` ```
**IMPORTANT:** **IMPORTANT:**
Be sure to configure your firewall to allow incoming TCP connections on the port configured in `RemoteMount.ApiPort`. Be sure to configure your firewall to allow incoming TCP connections on the port configured in `RemoteMount.ApiPort`.
#### Remote Mount Configuration File Section #### Remote Mount Configuration File Section
@@ -535,8 +608,10 @@ Be sure to configure your firewall to allow incoming TCP connections on the port
Client configuration is provider agnostic, so there's no need to specify `-s3` for S3 providers. Client configuration is provider agnostic, so there's no need to specify `-s3` for S3 providers.
**Required steps:** **Required steps:**
- Set the encryption token to the same value configured during server setup: - Set the encryption token to the same value configured during server setup:
```bash
``` shell
repertory -rm <host name or IP>:<port> -set RemoteConfig.EncryptionToken '<my secure password>' 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 <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 # Replace <port> with the value of RemoteMount.ApiPort used in the server configuration
@@ -547,22 +622,28 @@ repertory -rm my.host.com:20000 -set RemoteConfig.EncryptionToken '<my secure pa
#### Client Remote Mounting #### Client Remote Mounting
**Linux** <!-- markdownlint-disable-next-line -->
```bash ##### Linux
``` shell
repertory -rm <host name or IP>:<port> /mnt/location repertory -rm <host name or IP>:<port> /mnt/location
# Example: # Example:
repertory -rm 192.168.1.10:20000 /mnt/location repertory -rm 192.168.1.10:20000 /mnt/location
``` ```
**macOS** <!-- markdownlint-disable-next-line -->
```bash ##### macOS
``` shell
repertory -rm <host name or IP>:<port> /Volumes/remotemount repertory -rm <host name or IP>:<port> /Volumes/remotemount
# Example: # Example:
repertory -rm 192.168.1.10:20000 /Volumes/remotemount repertory -rm 192.168.1.10:20000 /Volumes/remotemount
``` ```
**Windows** <!-- markdownlint-disable-next-line -->
```powershell ##### Windows
``` shell
repertory -rm <host name or IP>:<port> t: repertory -rm <host name or IP>:<port> t:
# Example: # Example:
repertory -rm 192.168.1.10:20000 t: repertory -rm 192.168.1.10:20000 t:
@@ -599,14 +680,18 @@ Successful compilation will place all required files for execution in the `dist/
### Linux Compilation ### Linux Compilation
- Ensure `docker` is installed - Ensure `docker` is installed
- For `x86_64`: - For `x86_64`:
```bash
``` shell
scripts/make_unix.sh x86_64 scripts/make_unix.sh x86_64
scripts/make_unix.sh x86_64 Release scripts/make_unix.sh x86_64 Release
scripts/make_unix.sh x86_64 Debug scripts/make_unix.sh x86_64 Debug
``` ```
- For `aarch64`: - For `aarch64`:
```bash
``` shell
scripts/make_unix.sh aarch64 scripts/make_unix.sh aarch64
scripts/make_unix.sh aarch64 Release scripts/make_unix.sh aarch64 Release
scripts/make_unix.sh aarch64 Debug scripts/make_unix.sh aarch64 Debug
@@ -615,14 +700,18 @@ Successful compilation will place all required files for execution in the `dist/
### macOS Compilation ### macOS Compilation
- Ensure `Xcode` and `CMake` are installed - Ensure `Xcode` and `CMake` are installed
- For `x86_64`: - For `x86_64`:
```bash
``` shell
scripts/make_unix.sh x86_64 scripts/make_unix.sh x86_64
scripts/make_unix.sh x86_64 Release scripts/make_unix.sh x86_64 Release
scripts/make_unix.sh x86_64 Debug scripts/make_unix.sh x86_64 Debug
``` ```
- For `aarch64`: - For `aarch64`:
```bash
``` shell
scripts/make_unix.sh aarch64 scripts/make_unix.sh aarch64
scripts/make_unix.sh aarch64 Release scripts/make_unix.sh aarch64 Release
scripts/make_unix.sh aarch64 Debug scripts/make_unix.sh aarch64 Debug
@@ -631,16 +720,20 @@ Successful compilation will place all required files for execution in the `dist/
### Windows Compilation ### Windows Compilation
- **OFFICIAL: Cross-compiling on Linux** - **OFFICIAL: Cross-compiling on Linux**
- Ensure `docker` is installed - Ensure `docker` is installed
```bash
``` shell
scripts/make_win32.sh x86_64 scripts/make_win32.sh x86_64
scripts/make_win32.sh x86_64 Release scripts/make_win32.sh x86_64 Release
scripts/make_win32.sh x86_64 Debug scripts/make_win32.sh x86_64 Debug
``` ```
- **UNOFFICIAL: Compiling on Windows** - **UNOFFICIAL: Compiling on Windows**
- Ensure latest [MSYS2](https://www.msys2.org/) is installed - Ensure latest [MSYS2](https://www.msys2.org/) is installed
```powershell
``` shell
scripts\make_win32.cmd x86_64 scripts\make_win32.cmd x86_64
scripts\make_win32.cmd x86_64 Release scripts\make_win32.cmd x86_64 Release
scripts\make_win32.cmd x86_64 Debug scripts\make_win32.cmd x86_64 Debug