From 521874a56fe4a054e68bde052b9db2b931defd79 Mon Sep 17 00:00:00 2001 From: "Scott E. Graves" Date: Sat, 22 Feb 2025 19:59:22 -0600 Subject: [PATCH] Complete initial v2.0 documentation #33 --- README.md | 189 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 116 insertions(+), 73 deletions(-) diff --git a/README.md b/README.md index b78006c3..dd1e1f5b 100644 --- a/README.md +++ b/README.md @@ -30,28 +30,45 @@ on Windows. ### Sia -* Initial Configuration - * Sia steps: - * Set the appropriate bucket name and `renterd` API password in `repertory` configuration: - * To use `default` as the bucket name and configuration name: - * `repertory -set HostConfig.ApiPassword ''` - * To use a different bucket name with `default` as the configuration name: - * `repertory -set HostConfig.ApiPassword ''` - * `repertory -set SiaConfig.Bucket ''` - * For all other configurations: - * `repertory --name '' -set HostConfig.ApiPassword ''` - * `repertory --name '' -set SiaConfig.Bucket ''` - * To verify/view all configuration options: - * `repertory -dc` - * `repertory --name '' -dc` - * Example: - * `repertory --name default -dc` -* Mounting on Linux: +#### Initial Configuration + +* Required steps: + * Set the appropriate bucket name and `renterd` API password in `repertory` configuration: + * To use `default` as the bucket name and configuration name, you only need to set the `renterd` API password: + * `repertory -set HostConfig.ApiPassword ''` + * To specify a different bucket name while using `default` as the configuration name: + * `repertory -set HostConfig.ApiPassword ''` + * `repertory -set SiaConfig.Bucket ''` + * For all other configurations: + * `repertory --name '' -set HostConfig.ApiPassword ''` + * `repertory --name '' -set SiaConfig.Bucket ''` + +* Optional steps: + * Set a custom user name used for basic authentication: + * `repertory -set HostConfig.ApiUser ''` + * `repertory --name '' -set HostConfig.ApiUser ''` + * Set the `renterd` API port to a value other than `9980`: + * `repertory -set HostConfig.ApiPort 9981` + * `repertory --name '' -set HostConfig.ApiPort 9981` + * Set a custom agent string: + * `repertory -set HostConfig.AgentString ''` + * `repertory --name '' -set HostConfig.AgentString ''` + +* To verify/view all configuration options: + * `repertory -dc` + * `repertory --name '' -dc` + * Example: + * `repertory --name default -dc` + +#### Mounting + +* Linux: * `repertory /mnt/location` * `repertory --name '' /mnt/location` * Example: * `repertory --name default /mnt/location` -* Mounting on Windows: + +* Windows: * `repertory t:` * `repertory --name '' t:` * Example: @@ -59,47 +76,61 @@ on Windows. ### S3 -* Initial Configuration - * S3 steps: - * Set the appropriate base URL: - * `repertory -s3 --name '' -set S3Config.URL ''` - * Example: - * `repertory -s3 --name minio -set S3Config.URL 'http://localhost:9000'` - * Set the appropriate bucket name: - * `repertory -s3 --name '' -set S3Config.Bucket ''` - * Set the appropriate access key: - * `repertory -s3 --name '' -set S3Config.AccessKey ''` - * Set the appropriate secret key: - * `repertory -s3 --name '' -set S3Config.SecretKey ''` - * For Sia and most local S3 gateway instances, enable path style URL's: - * `repertory -s3 --name '' -set S3Config.UsePathStyle true` - * Optional steps: - * Set an appropriate region. Default is set to `any`: - * `repertory -s3 --name '' -set S3Config.Region ''` - * Enable encrypted file names and file data. Set a strong, random encryption token and be sure to store it in a secure backup location: - * `repertory -s3 --name '' -set S3Config.EncryptionToken ''` - * To verify/view all configuration options: - * `repertory -s3 --name '' -dc` + +#### Initial Configuration + +* Required steps: + * Set the appropriate base URL: + * `repertory -s3 --name '' -set S3Config.URL ''` * Example: - * `repertory -s3 --name minio -dc` -* Mounting on Linux: + * `repertory -s3 --name minio -set S3Config.URL 'http://localhost:9000'` + * Set the appropriate bucket name: + * `repertory -s3 --name '' -set S3Config.Bucket ''` + * Set the appropriate access key: + * `repertory -s3 --name '' -set S3Config.AccessKey ''` + * Set the appropriate secret key: + * `repertory -s3 --name '' -set S3Config.SecretKey ''` + * For Sia and most local S3 gateway instances, enable path style URL's: + * `repertory -s3 --name '' -set S3Config.UsePathStyle true` + +* Optional steps: + * Set an appropriate region. Default is set to `any`: + * `repertory -s3 --name '' -set S3Config.Region ''` + * Enable encrypted file names and file data. Set a strong, random encryption token and be sure to store it in a secure backup location: + * `repertory -s3 --name '' -set S3Config.EncryptionToken ''` + +* To verify/view all configuration options: + * `repertory -s3 --name '' -dc` + * Example: + * `repertory -s3 --name minio -dc` + + +#### Mounting + +* Linux: * `repertory -s3 --name '' /mnt/location` * Example: * `repertory -s3 --name minio /mnt/location` -* Mounting on Windows: + +* Windows: * `repertory -s3 --name '' t:` * Example: * `repertory -s3 --name minio t:` -### Notable Options +### Common Options * `--help` * Display all mount utility options + +* `-f` + * Keep process in foreground on Linux. + * `--name, -na [name]` * The `--name` option can be set to any valid value allowed as a file name for your filesystem. * For Sia, the bucket name will be set to the same value if it is empty in the configuration file. * If the `--name` option is not specified, `default` will be used. * For S3, the `--name` option is required and does not affect the bucket name. + * `-dc` * Display mount configuration * For Sia, `--name` is optional @@ -107,15 +138,18 @@ on Windows. ### Data Directories -* Linux - * `~/.local/repertory2` -* Windows - * `%LOCALAPPDATA%\repertory2` - * Example: - * `C:\Users\Tom\AppData\Local\repertory2` - * IMPORTANT: - * It is highly recommended to exclude this folder from any anti-virus/anti-malware applications as severe performance issues may arise. - * Excluding the mounted drive letter is also highly recommended. +#### Linux + +* `~/.local/repertory2` + +#### Windows + +* `%LOCALAPPDATA%\repertory2` + * Example: + * `C:\Users\Tom\AppData\Local\repertory2` + * IMPORTANT: + * It is highly recommended to exclude this folder from any anti-virus/anti-malware applications as severe performance issues may arise. + * Excluding the mounted drive letter is also highly recommended. ## Remote Mounting @@ -124,28 +158,37 @@ This option is referred to as remote mounting. Instructions TBD. ## Compiling -* Successful compilation will result in all required files being placed in the `dist/` directory -* Linux +Successful compilation will result in all files required for execution to be placed +in the `dist/` directory + + +### Linux + +* Ensure `docker` is installed + * For x86_64: + * RelWithDebInfo: `scripts/make_unix.sh` + * Release: `scripts/make_unix.sh x86_64 Release` + * Debug: `scripts/make_unix.sh x86_64 Debug` + + * For aarch64: + * RelWithDebInfo: `scripts/make_unix.sh aarch64` + * Release: `scripts/make_unix.sh aarch64 Release` + * Debug: `scripts/make_unix.sh aarch64 Debug` + + +### Windows + +* OFFICIAL: Cross-compiling on Linux * Ensure `docker` is installed - * For x86_64: - * RelWithDebInfo: `scripts/make_unix.sh` - * Release: `scripts/make_unix.sh x86_64 Release` - * Debug: `scripts/make_unix.sh x86_64 Debug` - * For aarch64: - * RelWithDebInfo: `scripts/make_unix.sh aarch64` - * Release: `scripts/make_unix.sh aarch64 Release` - * Debug: `scripts/make_unix.sh aarch64 Debug` -* Windows - * OFFICIAL: Cross-compiling on Linux - * Ensure `docker` is installed - * RelWithDebInfo: `scripts/make_win32.sh` - * Release: `scripts/make_win32.sh x86_64 Release` - * Debug: `scripts/make_win32.sh x86_64 Debug` - * UNOFFICIAL: Compiling on Windows - * Ensure latest [MSYS2](https://www.msys2.org/) is installed - * RelWithDebInfo: `scripts\make_win32.cmd` - * Release: `scripts\make_win32.cmd x86_64 Release` - * Debug: `scripts\make_win32.cmd x86_64 Debug` + * RelWithDebInfo: `scripts/make_win32.sh` + * Release: `scripts/make_win32.sh x86_64 Release` + * Debug: `scripts/make_win32.sh x86_64 Debug` + +* UNOFFICIAL: Compiling on Windows + * Ensure latest [MSYS2](https://www.msys2.org/) is installed + * RelWithDebInfo: `scripts\make_win32.cmd` + * Release: `scripts\make_win32.cmd x86_64 Release` + * Debug: `scripts\make_win32.cmd x86_64 Debug` ## Credits