From b72c1822d51ca1ead89fc35496f37d10763a120e Mon Sep 17 00:00:00 2001 From: "Scott E. Graves" Date: Tue, 9 Sep 2025 10:25:52 -0500 Subject: [PATCH] updated README.md --- README.md | 261 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 177 insertions(+), 84 deletions(-) diff --git a/README.md b/README.md index 0e173e9b..7fd2dcc1 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,12 @@ # Repertory 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` @@ -55,17 +57,20 @@ This example mounts a Sia bucket from a running [renterd](https://github.com/Sia ### 1. Install dependencies -**Linux** -```bash +#### Linux + +``` shell sudo apt install fuse3 # Debian/Ubuntu # or 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) -**Windows** +#### Windows + - 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 Replace placeholders with your values: -```bash + +``` shell repertory --name mybucket -set HostConfig.ApiPassword "" repertory --name mybucket -set SiaConfig.Bucket "" ``` Optional: -```bash + +``` shell # If renterd is not running locally repertory --name mybucket -set HostConfig.HostNameOrIp "" @@ -91,18 +98,24 @@ repertory --name mybucket -set HostConfig.ApiPort ### 3. Mount -**Linux** -```bash + +#### Linux + +``` shell repertory --name mybucket /mnt/mybucket ``` -**macOS** -```bash + +#### macOS + +``` shell repertory --name mybucket /Volumes/mybucket ``` -**Windows** -```powershell + +#### Windows + +``` shell repertory --name mybucket t: ``` @@ -110,19 +123,8 @@ repertory --name mybucket t: ### 4. Unmount -**Linux** -```bash -fusermount3 -u /mnt/mybucket -``` - -**macOS** -```bash -diskutil unmount /Volumes/mybucket -``` - -**Windows** -```powershell -net use t: /delete +``` shell +repertory --name mybucket --unmount ``` --- @@ -160,17 +162,22 @@ Only **64-bit operating systems** are supported: ## 📂 Data Directories -**Linux** -``` + +### Linux + +``` shell ~/.local/repertory2/s3 ~/.local/repertory2/sia ``` -**Windows** -``` + +### Windows + +``` shell %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. @@ -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**. Launch the portal: -```bash + +``` shell repertory -ui ``` + - Default username: `repertory` - Default password: `repertory` @@ -223,19 +232,28 @@ After first launch, `ui.json` will be created in the appropriate data directory ### Unmounting -**Linux** -```bash -fusermount3 -u /path/to/mountpoint +#### Encrypt + +``` shell +repertory -en --name '' --unmount ``` -**macOS** -```bash -diskutil unmount /Volumes/yourmount +#### Remote + +``` shell +repertory -rm 192.168.0.1:10000 --unmount ``` -**Windows** -```powershell -net use : /delete +#### S3 + +``` shell +repertory --name '' --unmount +``` + +### Sia + +``` shell +repertory -s3 --name '' --unmount ``` --- @@ -243,6 +261,7 @@ net use : /delete ## 🔒 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**. @@ -254,32 +273,43 @@ When enabling **encryption tokens** for S3 or remote mounts: ### Sia Initial Configuration **Required steps:** + - Set the appropriate bucket name and `renterd` API password in `repertory` configuration: -```bash + +``` shell repertory --name '' -set HostConfig.ApiPassword '' repertory --name '' -set SiaConfig.Bucket '' ``` **Optional steps:** + - Set a user name used during `renterd` basic authentication: -```bash + +``` shell repertory --name '' -set HostConfig.ApiUser '' ``` + - Set a custom agent string (default `Sia-Agent`): -```bash + +``` shell repertory --name '' -set HostConfig.AgentString '' ``` + - Set the host name or IP of the `renterd` instance (default `localhost`): -```bash + +``` shell repertory --name '' -set HostConfig.HostNameOrIp '' ``` + - Set the `renterd` API port (default `9980`): -```bash + +``` shell repertory --name '' -set HostConfig.ApiPort 9981 ``` **Verify/view all configuration options:** -```bash + +``` shell repertory --name '' -dc # Example: repertory --name my_bucket -dc @@ -287,22 +317,28 @@ repertory --name my_bucket -dc ### Sia Mounting -**Linux** -```bash + +#### Linux + +``` shell repertory --name '' /mnt/location # Example: repertory --name my_bucket /mnt/location ``` -**macOS** -```bash + +#### macOS + +``` shell repertory --name '' /Volumes/mybucket # Example: repertory --name my_bucket /Volumes/mybucket ``` -**Windows** -```powershell + +#### Windows + +``` shell repertory --name '' t: # Example: repertory --name my_bucket t: @@ -362,41 +398,56 @@ repertory --name my_bucket t: ### S3 Initial Configuration **Required steps:** + - Set the appropriate base URL: -```bash + +``` shell repertory -s3 --name '' -set S3Config.URL '' # Example: repertory -s3 --name minio -set S3Config.URL 'http://localhost:9000' ``` + - Set the appropriate bucket name: -```bash + +``` shell repertory -s3 --name '' -set S3Config.Bucket '' ``` + - Set the appropriate access key: -```bash + +``` shell repertory -s3 --name '' -set S3Config.AccessKey '' ``` + - Set the appropriate secret key: -```bash + +``` shell repertory -s3 --name '' -set S3Config.SecretKey '' ``` + - For Sia and most local S3 gateway instances, enable path style URLs: -```bash + +``` shell repertory -s3 --name '' -set S3Config.UsePathStyle true ``` **Optional steps:** + - Set an appropriate region. Default is `any`: -```bash + +``` shell repertory -s3 --name '' -set S3Config.Region '' ``` + - Enable encrypted file names and file data. Set a strong, random encryption token and store it securely: -```bash + +``` shell repertory -s3 --name '' -set S3Config.EncryptionToken '' ``` **Verify/view all configuration options:** -```bash + +``` shell repertory -s3 --name '' -dc # Example: repertory -s3 --name minio -dc @@ -404,22 +455,28 @@ repertory -s3 --name minio -dc ### S3 Mounting -**Linux** -```bash + +#### Linux + +``` shell repertory -s3 --name '' /mnt/location # Example: repertory -s3 --name minio /mnt/location ``` -**macOS** -```bash + +#### macOS + +``` shell repertory -s3 --name '' /Volumes/minio # Example: repertory -s3 --name minio /Volumes/minio ``` -**Windows** -```powershell + +#### Windows + +``` shell repertory -s3 --name '' t: # Example: 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. **Required steps:** + - Enable remote mount: + - **Sia** - ```bash + + ``` shell repertory -set RemoteMount.Enable true repertory --name '' -set RemoteMount.Enable true ``` + - **S3** - ```bash + + ``` shell repertory -s3 --name '' -set RemoteMount.Enable true ``` + - Set a secure encryption token: + - **Sia** - ```bash + + ``` shell repertory -set RemoteMount.EncryptionToken '' repertory --name '' -set RemoteMount.EncryptionToken '' ``` + - **S3** - ```bash + + ``` shell repertory -s3 --name '' -set RemoteMount.EncryptionToken '' ``` **Optional steps:** + - Change the port clients will use to connect to your mount: + - **Sia** - ```bash + + ``` shell repertory -set RemoteMount.ApiPort 20000 repertory --name '' -set RemoteMount.ApiPort 20000 ``` + - **S3** - ```bash + + ``` shell repertory -s3 --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 @@ -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. **Required steps:** + - Set the encryption token to the same value configured during server setup: -```bash + +``` shell repertory -rm : -set RemoteConfig.EncryptionToken '' # Replace with the host name or IP of the server # Replace with the value of RemoteMount.ApiPort used in the server configuration @@ -547,22 +622,28 @@ repertory -rm my.host.com:20000 -set RemoteConfig.EncryptionToken ' +##### Linux + +``` shell repertory -rm : /mnt/location # Example: repertory -rm 192.168.1.10:20000 /mnt/location ``` -**macOS** -```bash + +##### macOS + +``` shell repertory -rm : /Volumes/remotemount # Example: repertory -rm 192.168.1.10:20000 /Volumes/remotemount ``` -**Windows** -```powershell + +##### Windows + +``` shell repertory -rm : t: # Example: 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 - Ensure `docker` is installed + - For `x86_64`: - ```bash + + ``` shell scripts/make_unix.sh x86_64 scripts/make_unix.sh x86_64 Release scripts/make_unix.sh x86_64 Debug ``` + - For `aarch64`: - ```bash + + ``` shell scripts/make_unix.sh aarch64 scripts/make_unix.sh aarch64 Release scripts/make_unix.sh aarch64 Debug @@ -615,14 +700,18 @@ Successful compilation will place all required files for execution in the `dist/ ### macOS Compilation - Ensure `Xcode` and `CMake` are installed + - For `x86_64`: - ```bash + + ``` shell scripts/make_unix.sh x86_64 scripts/make_unix.sh x86_64 Release scripts/make_unix.sh x86_64 Debug ``` + - For `aarch64`: - ```bash + + ``` shell scripts/make_unix.sh aarch64 scripts/make_unix.sh aarch64 Release scripts/make_unix.sh aarch64 Debug @@ -631,16 +720,20 @@ Successful compilation will place all required files for execution in the `dist/ ### Windows Compilation - **OFFICIAL: Cross-compiling on Linux** + - Ensure `docker` is installed - ```bash + + ``` shell 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](https://www.msys2.org/) is installed - ```powershell + + ``` shell scripts\make_win32.cmd x86_64 scripts\make_win32.cmd x86_64 Release scripts\make_win32.cmd x86_64 Debug