18 KiB
Run Codex
As for now, Codex is implemented only in Nim and can be found in nim-codex repository.
It is a command-line application which may be run in a different ways:
- Using binary
- Run as a daemon in Linux (not supported yet)
- Run as a service in Windows (not supported yet)
- Using Docker
- Using Docker Compose
- Using Ansible
- On Kubernetes
During the run, it is required to pass configuration option to the application, which can be done in a different ways.
Configuration
It is possible to configure Codex node in several ways:
The order of priority is the same as above:
CLI options --> Environment variables --> Configuration file.
Common information
Units
For some configuration options, we can pass values in common units like:
--storage-quota=2m/2M/2mb/2MB
--cache-size
--block-ttl=2s/2S/2m/2M/2h/2H/2d/2D/2w/2W
--block-mi
Logging
Codex uses Chronicles logging library, which allows great flexibility in working with logs. Chronicles has the concept of topics, which categorize log entries into semantic groups.
Using the log-level parameter, you can set the top-level log level like --log-level="trace", but more importantly,
you can set log levels for specific topics like --log-level="info; trace: marketplace,node; error: blockexchange",
which sets the top-level log level to info and then for topics marketplace and node sets the level to trace and so on.
CLI options
codex --help
Usage:
codex [OPTIONS]... command
The following options are available:
--config-file Loads the configuration from a TOML file [=none].
--log-level Sets the log level [=info].
--metrics Enable the metrics server [=false].
--metrics-address Listening address of the metrics server [=127.0.0.1].
--metrics-port Listening HTTP port of the metrics server [=8008].
-d, --data-dir The directory where codex will store configuration and data
[=/root/.cache/codex].
-i, --listen-addrs Multi Addresses to listen on [=/ip4/0.0.0.0/tcp/0].
-a, --nat IP Addresses to announce behind a NAT [=127.0.0.1].
-e, --disc-ip Discovery listen address [=0.0.0.0].
-u, --disc-port Discovery (UDP) port [=8090].
--net-privkey Source of network (secp256k1) private key file path or name [=key].
-b, --bootstrap-node Specifies one or more bootstrap nodes to use when connecting to the network.
--max-peers The maximum number of peers to connect to [=160].
--agent-string Node agent string which is used as identifier in network [=Codex].
--api-bindaddr The REST API bind address [=127.0.0.1].
-p, --api-port The REST Api port [=8080].
--api-cors-origin The REST Api CORS allowed origin for downloading data. '*' will allow all
origins, '' will allow none. [=Disallow all cross origin requests to download
data].
--repo-kind Backend for main repo store (fs, sqlite, leveldb) [=fs].
-q, --storage-quota The size of the total storage quota dedicated to the node [=$DefaultQuotaBytes].
-t, --block-ttl Default block timeout in seconds - 0 disables the ttl [=$DefaultBlockTtl].
--block-mi Time interval in seconds - determines frequency of block maintenance cycle: how
often blocks are checked for expiration and cleanup
[=$DefaultBlockMaintenanceInterval].
--block-mn Number of blocks to check every maintenance cycle [=1000].
-c, --cache-size The size of the block cache, 0 disables the cache - might help on slow hardrives
[=0].
Available sub-commands:
codex persistence [OPTIONS]... command
The following options are available:
--eth-provider The URL of the JSON-RPC API of the Ethereum node [=ws://localhost:8545].
--eth-account The Ethereum account that is used for storage contracts.
--eth-private-key File containing Ethereum private key for storage contracts.
--marketplace-address Address of deployed Marketplace contract.
--validator Enables validator, requires an Ethereum node [=false].
--validator-max-slots Maximum number of slots that the validator monitors [=1000].
--reward-recipient Address to send payouts to (eg rewards and refunds).
Available sub-commands:
codex persistence prover [OPTIONS]...
The following options are available:
-cd, --circuit-dir Directory where Codex will store proof circuit data
[=/root/.cache/codex/circuits].
--circom-r1cs The r1cs file for the storage circuit
[=/root/.cache/codex/circuits/proof_main.r1cs].
--circom-wasm The wasm file for the storage circuit
[=/root/.cache/codex/circuits/proof_main.wasm].
--circom-zkey The zkey file for the storage circuit
[=/root/.cache/codex/circuits/proof_main.zkey].
--circom-no-zkey Ignore the zkey file - use only for testing! [=false].
--proof-samples Number of samples to prove [=5].
--max-slot-depth The maximum depth of the slot tree [=32].
--max-dataset-depth The maximum depth of the dataset tree [=8].
--max-block-depth The maximum depth of the network block merkle tree [=5].
--max-cell-elements The maximum number of elements in a cell [=67].
Environment variables
In order to set a configuration option using environment variables, first find the desired CLI option and then transform it in the following way:
- prepend it with
CODEX_ - make it uppercase
- replace
-with_
For example, to configure --log-level, use CODEX_LOG_LEVEL as the environment variable name.
Warning
Some options can't be configured via environment variables for now. Please read Known issues for more details.
Configuration file
A TOML configuration file can also be used to set configuration values. Configuration option names and corresponding values are placed in the file, separated by =. Configuration option names can be obtained from the codex --help command, and should not include the -- prefix. For example, a node's log level (--log-level) can be configured using TOML as follows:
log-level = "trace"
For option, like bootstrap-node and listen-addrs which accept multiple values we can specify data as an array
listen-addrs = [
"/ip4/0.0.0.0/tcp/7777",
"/ip4/0.0.0.0/tcp/8888"
]
The Codex node can then read the configuration from this file using the --config-file CLI parameter, like codex --config-file=/path/to/your/config.toml.
Run
Basically, we can run Codex in three different modes
- Codex node - useful for local testing/development and basic/files sharing
- Codex node with marketplace support - main mode and should be used by the end users
- Codex storage node - should be used by storage providers or if you would like to sell your local storage
Using binary
Codex node
We can run Codex in a simple way like following:
codex
But, it will use a default data-dir value and we can pass a custom one:
codex --data-dir=./datadir
This will run Codex as an isolated instance, and if we would like to join an existing network, it is required to pass a bootstrap node. We can pass multiple nodes as well:
codex \
--data-dir=./datadir \
--bootstrap-node=spr:CiUIAhIhAiJvIcA_ZwPZ9ugVKDbmqwhJZaig5zKyLiuaicRcCGqLEgIDARo8CicAJQgCEiECIm8hwD9nA9n26BUoNuarCEllqKDnMrIuK5qJxFwIaosQ3d6esAYaCwoJBJ_f8zKRAnU6KkYwRAIgM0MvWNJL296kJ9gWvfatfmVvT-A7O2s8Mxp8l9c8EW0CIC-h-H-jBVSgFjg3Eny2u33qF7BDnWFzo7fGfZ7_qc9P \
--bootstrap-node=spr:CiUIAhIhAyUvcPkKoGE7-gh84RmKIPHJPdsX5Ugm_IHVJgF-Mmu_EgIDARo8CicAJQgCEiEDJS9w-QqgYTv6CHzhGYog8ck92xflSCb8gdUmAX4ya78QoemesAYaCwoJBES39Q2RAnVOKkYwRAIgLi3rouyaZFS_Uilx8k99ySdQCP1tsmLR21tDb9p8LcgCIG30o5YnEooQ1n6tgm9fCT7s53k6XlxyeSkD_uIO9mb3
Important
Make sure you are using a proper value for the network you would like to join.
Also, to make your Codex node accessible for other network participants, it is required to specify a public IP address which can be used to access your node:
codex \
--data-dir=./datadir \
--bootstrap-node=spr:CiUIAhIhAiJvIcA_ZwPZ9ugVKDbmqwhJZaig5zKyLiuaicRcCGqLEgIDARo8CicAJQgCEiECIm8hwD9nA9n26BUoNuarCEllqKDnMrIuK5qJxFwIaosQ3d6esAYaCwoJBJ_f8zKRAnU6KkYwRAIgM0MvWNJL296kJ9gWvfatfmVvT-A7O2s8Mxp8l9c8EW0CIC-h-H-jBVSgFjg3Eny2u33qF7BDnWFzo7fGfZ7_qc9P \
--nat=<your public IP>
Tip
We can set public IP using curl and IP lookup service, like ip.codex.storage.
After that, node will announce itself using your public IP and dynamic TCP port for libp2p transport (data transfer), which can be adjusted in the following way:
codex \
--data-dir=./datadir \
--bootstrap-node=spr:CiUIAhIhAiJvIcA_ZwPZ9ugVKDbmqwhJZaig5zKyLiuaicRcCGqLEgIDARo8CicAJQgCEiECIm8hwD9nA9n26BUoNuarCEllqKDnMrIuK5qJxFwIaosQ3d6esAYaCwoJBJ_f8zKRAnU6KkYwRAIgM0MvWNJL296kJ9gWvfatfmVvT-A7O2s8Mxp8l9c8EW0CIC-h-H-jBVSgFjg3Eny2u33qF7BDnWFzo7fGfZ7_qc9P \
--nat=`curl -s https://ip.codex.storage` \
--listen-addrs=/ip4/0.0.0.0/tcp/8070
In that way, node will announce itself using the following multiaddress:
/ip4/<your public IP>/tcp/8070
and we can check that via API call:
curl -s localhost:8080/api/codex/v1/debug/info | jq -r '.announceAddresses'
[
"/ip4/<your public IP>/tcp/8070"
]
Basically, for P2P communication we should set/adjust two ports:
| # | Protocol function | CLI option | Example |
|---|---|---|---|
| 1 | Discovery | --disc-port |
--disc-port=8090 |
| 2 | Transport | --listen-addrs |
--listen-addrs=/ip4/0.0.0.0/tcp/8070 |
And, also it is required to setup port-forwarding on your Internet device, please read Known issues for more details.
So, a fully working basic configuration will looks like following:
codex \
--data-dir=./datadir \
--bootstrap-node=spr:CiUIAhIhAiJvIcA_ZwPZ9ugVKDbmqwhJZaig5zKyLiuaicRcCGqLEgIDARo8CicAJQgCEiECIm8hwD9nA9n26BUoNuarCEllqKDnMrIuK5qJxFwIaosQ3d6esAYaCwoJBJ_f8zKRAnU6KkYwRAIgM0MvWNJL296kJ9gWvfatfmVvT-A7O2s8Mxp8l9c8EW0CIC-h-H-jBVSgFjg3Eny2u33qF7BDnWFzo7fGfZ7_qc9P \
--nat=`curl -s https://ip.codex.storage` \
--disc-port=8090 \
--listen-addrs=/ip4/0.0.0.0/tcp/8070
After node is up and running and port-forwarding configurations was done, we should be able to Upload a file/Download a file in the network. And to be able to purchase storage, we should run Codex node with marketplace support.
Codex node with marketplace support
Marketplace support permits to purchase the storage in Codex network. Basically, we should add just a persistence sub-command and required CLI options to the previous run.
Note
Please ignore
--eth-accountCLI option, read Known issues for more details.
-
For a daily use, we should consider to run a local blockchain node based on the network you would like to join. That process is described in the Join Testnet(🚧), but for quick start we can use a public RPC endpoint.
-
Create a file with ethereum private key and set a proper permissions.
key=$(curl -s https://key.codex.storage) echo $key | awk -F ':' '/address/ {print $2}' >eth.address echo $key | awk -F ':' '/private/ {print $2}' >eth.key chmod 600 eth.keyCaution
Please use mentioned key generation service for demo purpose only.
-
Specify bootstrap nodes and marketplace address based on the network you would like to join.
-
Run the node
codex \ persistence \ --data-dir=./datadir \ --bootstrap-node=spr:CiUIAhIhAiJvIcA_ZwPZ9ugVKDbmqwhJZaig5zKyLiuaicRcCGqLEgIDARo8CicAJQgCEiECIm8hwD9nA9n26BUoNuarCEllqKDnMrIuK5qJxFwIaosQ3d6esAYaCwoJBJ_f8zKRAnU6KkYwRAIgM0MvWNJL296kJ9gWvfatfmVvT-A7O2s8Mxp8l9c8EW0CIC-h-H-jBVSgFjg3Eny2u33qF7BDnWFzo7fGfZ7_qc9P \ --nat=`curl -s https://ip.codex.storage` \ --disc-port=8090 \ --listen-addrs=/ip4/0.0.0.0/tcp/8070 \ --eth-provider=https://rpc.testnet.codex.storage \ --eth-private-key=eth.key \ --marketplace-address=0xB119d28d3A1bFD281b23A0890B4c1B626EE8F6F0
After node is up and running, you just need to fill-up your ethereum address (cat eth.address) with the tokens and then you should be able to Purchase storage.
Codex storage node
Codex storage node should be run by storage providers or in case you would like to sell your local storage. For that, we should use configuration for Codex node with marketplace support and additionally use prover sub-command and required CLI options.
That sub-command will make Codex to listen for a proof request on the blockchain and answer them. To compute an answer for the proof request, Codex will use stored data and circuit files generated by the code in the codex-storage-proofs-circuits repository.
Every network uses its own generated set of the files which are stored in the codex-contracts-eth repository and also uploaded to the CDN. Hash of the set is also known by the marketplace smart contract.
To download circuit files and make them available to Codex app, we have a stand-alone utility - cirdl. It can be compiled from the sources (make cirdl) or downloaded from the GitHub release page (work in progress - Rework circuit downloader #882).
You would need to pass a bootstrap nodes, blockchain RPC endpoint and marketplace address based on the network you would like to join.
-
Download circuit files
# Create circuit files folder mkdir -p ./datadir/circuit # Download circuit files cirdl \ ./datadir/circuit \ https://rpc.testnet.codex.storage \ 0xB119d28d3A1bFD281b23A0890B4c1B626EE8F6F0 -
Start Codex storage node
codex \ persistence \ prover \ --data-dir=./datadir \ --bootstrap-node=spr:CiUIAhIhAiJvIcA_ZwPZ9ugVKDbmqwhJZaig5zKyLiuaicRcCGqLEgIDARo8CicAJQgCEiECIm8hwD9nA9n26BUoNuarCEllqKDnMrIuK5qJxFwIaosQ3d6esAYaCwoJBJ_f8zKRAnU6KkYwRAIgM0MvWNJL296kJ9gWvfatfmVvT-A7O2s8Mxp8l9c8EW0CIC-h-H-jBVSgFjg3Eny2u33qF7BDnWFzo7fGfZ7_qc9P \ --nat=`curl -s https://ip.codex.storage` \ --disc-port=8090 \ --listen-addrs=/ip4/0.0.0.0/tcp/8070 \ --eth-provider=https://rpc.testnet.codex.storage \ --eth-private-key=eth.key \ --marketplace-address=0xB119d28d3A1bFD281b23A0890B4c1B626EE8F6F0 \ --circom-r1cs=./datadir/circuits/proof_main.r1cs \ --circom-wasm=./datadir/circuits/proof_main.wasm \ --circom-zkey=./datadir/circuits/proof_main.zkey
After node is up and running, you just need to fill-up your ethereum address (cat eth.address) with the tokens and then you should be able to Create storage availability.
Run as a daemon in Linux
This functionality is not supported yet 🚧
Run as a service in Windows
This functionality is not supported yet 🚧
Using Docker
To be added 🚧
Using Docker Compose
To be added 🚧
Using Ansible
Planning 🚧
On Kubernetes
To be added 🚧
Helm chart code is available in helm-charts repository, but chart was not published yet.
Known issues
- Environment variables like
CODEX_BOOTSTRAP_NODEandCODEX_LISTEN_ADDRSdoes not support multiple values. Please check [Feature request] Support multiple SPR records via environment variable #525, for more information. - Sub-commands configuration like
persistenceandpersistence provercan't be done via environment variables for now. - NAT traversal #753 is not implemented yet and we would need to setup port-forwarding for discovery and transport protocols.
- Please ignore
--eth-accountCLI option - Drop support for --eth-account #727.