Detailed Tutorial
Except for the initialization, the steps are the same for test and live environment.
1. Test/Live instance
Before starting the daemon, and before anything at all can be done, we need to setup the key store and register the instance.
You need three things for live:
- id
- secret key
- pass phrase
1. Id
You pick an id that is anything you want, but you need to include it in all cli calls. (It keys instances on the physical device to TCP ports used by corresponding daemon, and needs to be unique.)
2. Secret key
Secret key is a 32 byte hex. For the main network this is your EVM hex. For a test network, any 32-byte hex will do as EVM-key.
3. Pass phrase
You need a passphrase to encrypt the secret on file. There is no validation of passphrase entropy currently, so you may use anything, but not empty.
There are three env options: live, and the two test envs local and mock net. I will here show mock net and live only, as local net needs separate setup of a local network.
Examples use Windows CMD syntax.
Note:
The instance register on your device is located at
C:\Users\<YourUser>\AppData\Local\ryyn\index.toml
It’s not something you need to think about normally, but if you have previously tested an older version, you may need to delete this file due to format incompatibility. (If you have run instances that you have scrapped and want to reuse the id, then you’d see an error since the id is already registered. Simplest is to just pick another id. But you could also edit this file.) This is a temporary lack of ergonomics.
1.1 A) Initialize test instance
Expand for details
Use the terminal from the path where you keep ryyn.exe. (Keep this one for cli calls, and use another one for the daemon in later steps.)
.\ryyn.exe <id> init-mock <secret_key> <passphrase> <device_nr> <test_run_dir>
Device nr is e.g. the sequence nr of simulated devices; 0, 1 .. etc.
Test run dir is the custom path where you want the simulated network and the instance app dirs to reside.
For example:
.\ryyn.exe alice init-mock deadbeef... myStrongPass 123 \my\path
After that we start the actual backend, a daemon that will receive all the requests from the CLI.
Jump to 1.2 for those instructions.
1.1 B) Initialize live instance
The pattern is:
.\ryyn.exe <id> init <evm-key> <passphrase>
Say you id this instance as t-0.
.\ryyn.exe t-0 init <evm-key> abc123
With this the application data will be stored at the default location e.g.
C:\Users\<YourUser>\AppData\Local\ryyn\t-0
Expand for Custom install root and wsp key:
ryyn bob init deadbeef.. myStrongPass --wsp-key feedbeab..
ryyn alice init deadbeef.. myStrongPass --install-root /custom/folder --json
--wsp-key gives the option to separate EVM-key from the workspace, so that you can use the workspace with any EVM-key, that way connecting instances do not need to share EVM-key. Without this optimal parameter your workspace key will be derived from the EVM key.
The wsp key is stored in a separate file next to the evm key in the app dir.
--json is for using the cli programmatically.
For this tutorial I will use a dedicated folder for my live workspace tutorial, placed together with other workspaces in workspaces, and I will let every instance have an id in the following pattern: t-<ordinal> so the first is t-0:
.\ryyn.exe t-0 init <evm-key> abc123 --install-root <abs-path>\workspaces\tutorial --wsp-key <wsp-key>
You don’t need to create the full path in before hand, it is created for you.
So now we have the app dir of t-0 here:
<abs-path>\workspaces\tutorial\ryyn\t-0
(The path unnecessarily includes ryyn between workspace and instance level, that will be fixed.)
1.2 Start daemon:
This is the only direct call to the daemon, used to spin it up when it is not running.
In this call the passphrase is included as an env var, so that the daemon can decrypt your secret key.
You do not need to include passphrase in subsequent interactions with the cli, as the daemon keeps the key in memory while it is running.
The id is included as well, this is used by the daemon to lookup the other details of your instance.
Open a new terminal window for the daemon in the path of the daemon binary.
With the information from previous step, the call is this:
set "RYYN_PWD=abc123" && .\ryyn_daemon.exe t-0
The daemon is now running and the application is ready to use.
After having started the daemon, leave the terminal window open, this keeps the daemon alive. (You can run it in background as well, but for tutorial, do it like this.) You will be able to follow the internal workings as it outputs logs to the terminal window.
2. Using the app
2.1 Display info
From the path of the cli binary:
.\ryyn.exe t-0 info
You will see a table of vaults, mounts and devices.
At this stage, only your device will show.
2.2 Add instance
Initiate another instance using the same steps as above, but with a distinct id. In this example t-1:
.\ryyn.exe t-1 init <evm-key> abc123
And the app dir will be at
C:\Users\<YourUser>\AppData\Local\ryyn\t-1
..
Or, if you went with custom path and/or wsp key:
.\ryyn.exe t-1 init <evm-key> abc123 --install-root <abs-path>\workspaces\tutorial --wsp-key <wsp-key>
You will now have its app dir here:
<abs-path>\workspaces\tutorial\ryyn\t-1
..
Start it just like the other one.
Open a new terminal window for the daemon in the path of the daemon binary and enter:
set "RYYN_PWD=abc123" && .\ryyn_daemon.exe t-1
You will immediately see activity in the first daemon terminal window.
If we display info on any of t-0/t-1:
.\ryyn.exe t-0 info
This will now show two devices.
2.3 Create vault
Note:
You may want to start clean and simple to observe the behavior without noise, and for that reason use an empty folder to create a vault of.
But when you are ready, go ahead and create vaults from folders with existing files.
Create a vault:
.\ryyn.exe t-0 vault create D:\path\to\vault
This will also mount the vault (the returned value is the id of the mount).
We display info again:
.\ryyn.exe t-0 info
This will now also show a vault and a mount.
You can see in the daemon terminal window that the corresponding logs show there.
You will use the vault id listed there in the next step.
2.4 Mount vault
Now you want t-1 to mount the vault created by t-0. Use the vault id that you saw when listing the info in previous step.
Mount the vault:
.\ryyn.exe t-1 vault mount <vault-id> <path> [any-name]
Test to create or drag and drop files of various types and sizes into the path. You can see in the daemon terminal window what happens. There will be a lot of activity.
You will be able to browse into the mount dirs of both and see the results. Especially satisfying is to see the other one, while you add files in the first one.
Overview cli usage
Usage:
ryyn <ID> <COMMAND> [SUBCOMMAND] [ARGS]
Commands:
init <secret_key> <passphrase> [--install-root <path>] [--wsp-key <key>] [--json]
Initialize the application. The secret key must be a valid EVM key.
Supply 'install-root' as an option when needed.
init-local <secret_key> <passphrase> [--install-root <path>] [--wsp-key <key>] [--json]
Initialize the application. The secret key must be a valid EVM key.
Supply 'install-root' as an option when needed.
init-mock <secret_key> <passphrase> <device_nr> <test_run_dir> [--wsp-key <key>] [--json]
Initialize a test instance with a secret key and passphrase.
Requires a device number and a test run directory.
info [--json]
Display the current system info.
vault create <path> [--json]
Create a vault from the folder and mount it.
vault mount <vault_prefix> <path> [name] [--json]
Mount a vault to the folder with an optional mount name.
shutdown [--json]
Gracefully stop the running service.
Options:
--json Output machine-readable JSON (valid for all commands).
--wsp-key <KEY> Optional workspace key (valid with 'init', 'init-local' and 'init-mock').
--install-root <PATH> Optional install root (valid with 'init' or 'init-local'). The app will be installed at '<install_root>/ryyn'.
Examples:
ryyn alice init-mock deadbeef.. myStrongPass 2 /instance/folder --json
ryyn alice init-local deadbeef.. myStrongPass /my/folder --wsp-key feedbeab.. --json
ryyn bob init deadbeef.. myStrongPass --wsp-key feedbeab..
ryyn alpha init deadbeef.. myStrongPass --install-root /custom/folder --json
ryyn beta vault create /my/folder
ryyn gamma vault mount deadbeef.. /my/folder docs
(some additional visual info here, although slightly outdated)
I’m not available over the weekend. Hope I didn’t miss anything 