From 3e1d4cfd31012287376169a7a65a5b8ac53bd19d Mon Sep 17 00:00:00 2001 From: Hector Sanjuan Date: Tue, 24 Oct 2023 12:20:18 +0200 Subject: [PATCH] Documentation --- README.md | 2 +- main.go | 91 +++++++++++++++++++++++++++++++++++++++++-------------- 2 files changed, 70 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 51d77c3..7b31c40 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ ## About Rainbow is an implementation of the [IPFS HTTP Gateway API](https://specs.ipfs.tech/http-gateways), -based on [boxo](https://github.com/ipfs/boxo) which is the tooling the powers [kubo](https://github.com/ipfs/kubo). +based on [boxo](https://github.com/ipfs/boxo) which is the tooling the powers [Kubo](https://github.com/ipfs/kubo). Rainbow uses the same Go code as the HTTP gateway in Kubo, but is fully specialized to just be a gateway: diff --git a/main.go b/main.go index 8f0adb2..b832ce0 100644 --- a/main.go +++ b/main.go @@ -31,6 +31,46 @@ var goLog = logging.Logger("rainbow") func main() { app := cli.NewApp() + app.Name = "rainbow" + app.Usage = "The IPFS HTTP gateway daemon" + app.Version = version + app.Description = ` +Rainbow runs an IPFS HTTP gateway. + +An IPFS HTTP gateway is able to fetch content from the IPFS network and serve +it via HTTP, so that it becomes seamless to browse the web, when the web is +stored and provided by peers in the IPFS network. + +HTTP gateways are also able to facilitate download of any IPFS content (not +only websites, but any supported content-addressed Merkle-DAG), in formats +that are suitable for verification client-side (i.e. CAR files). + +Rainbow is optimized to perform the tasks of a gateway and only that, making +opinionated choices on the configration and setup of internal +components. Rainbow aims to serve production environments, where gateways are +deployed as a public service meant to be accessible by anyone. Rainbow acts as +a client to the IPFS network and does not serve or provide content to +it. Rainbow cannot be used to store or pin IPFS content, other than that +temporailly served over HTTP. Rainbow is just a gateway. + +Persistent configuration and data is stored in $RAINBOW_DATADIR (by default, +the folder in which rainbow is run). + +EXAMPLES + +Launch a gateway with randomly generated libp2p.key (will be written to +$RAINBOW_DATADIR/libp2p.key and used in subsequent runs): + + $ rainbow + +Generate an identity seed and launch a gateway: + + $ rainbow gen-seed > $RAINBOW_DATADIR/seed + $ rainbow --seed-index 0 + +(other rainbow gateways can use the same seed with different indexes to + derivate their identities) +` app.Flags = []cli.Flag{ @@ -38,96 +78,97 @@ func main() { Name: "datadir", Value: "", EnvVars: []string{"RAINBOW_DATADIR"}, - Usage: "specify the directory that cache data will be stored", + Usage: "Directory for persistent data (keys, blocks, denylists)", }, &cli.StringFlag{ Name: "seed", Value: "", EnvVars: []string{"RAINBOW_SEED"}, - Usage: "Specify a seed to derive peerID from (needs --seed-index). Best to use CREDENTIALS_DIRECTORY/seed", + Usage: "Seed to derive peerID from. Generate with gen-seed. Needs --seed-index. Best to use $CREDENTIALS_DIRECTORY/seed or $RAINBOW_DATADIR/seed.", }, &cli.IntFlag{ Name: "seed-index", Value: -1, EnvVars: []string{"RAINBOW_SEED_INDEX"}, - Usage: "Specify an index to derivate the peerID from the key (needs --seed)", + Usage: "Index to derivate the peerID (needs --seed)", }, &cli.StringFlag{ Name: "gateway-domains", Value: "", EnvVars: []string{"RAINBOW_GATEWAY_DOMAINS"}, - Usage: "Set to enable legacy gateway on these domains. Comma-separated list.", + Usage: "Legacy path-gateway domains. Comma-separated list.", }, &cli.StringFlag{ Name: "subdomain-gateway-domains", Value: "", EnvVars: []string{"RAINBOW_SUBDOMAIN_GATEWAY_DOMAINS"}, - Usage: "Set to enable legacy gateway on these domains. Comma-separated list.", + Usage: "Subdomain gateway domains. Comma-separated list.", }, &cli.StringFlag{ Name: "gateway-listen-address", Value: "127.0.0.1:8090", EnvVars: []string{"RAINBOW_GATEWAY_LISTEN_ADDRESS"}, - Usage: "listen address for the gateway endpoint", + Usage: "Listen address for the gateway endpoint", }, &cli.StringFlag{ Name: "ctl-listen-address", Value: "127.0.0.1:8091", EnvVars: []string{"RAINBOW_CTL_LISTEN_ADDRESS"}, - Usage: "listen address for the internal control api and metrics", + Usage: "Listen address for the management api and metrics", }, &cli.IntFlag{ Name: "connmgr-low", Value: 100, EnvVars: []string{"RAINBOW_CONNMGR_LOW"}, - Usage: "libp2p connection manager 'low' water mark", + Usage: "Minimum number of connections to keep", }, &cli.IntFlag{ Name: "connmgr-high", Value: 3000, EnvVars: []string{"RAINBOW_CONNMGR_HIGH"}, - Usage: "libp2p connection manager 'high' water mark", + Usage: "Maximum number of connections to keep", }, &cli.DurationFlag{ Name: "connmgr-grace", Value: time.Minute, EnvVars: []string{"RAINBOW_CONNMGR_GRACE_PERIOD"}, - Usage: "libp2p connection manager grace period", + Usage: "Minimum connection TTL", }, &cli.IntFlag{ Name: "inmem-block-cache", Value: 1 << 30, EnvVars: []string{"RAINBOW_INMEM_BLOCK_CACHE"}, - Usage: "Size of the in-memory block cache. 0 to disable (disables compression too)", + Usage: "Size of the in-memory block cache. 0 to disable (disables compression on disk too)", }, &cli.Uint64Flag{ Name: "max-memory", Value: 0, EnvVars: []string{"RAINBOW_MAX_MEMORY"}, - Usage: "Libp2p resource manager max memory. Defaults to system's memory * 0.85", + Usage: "Max memory to use. Defaults to 85% of the system's available RAM", }, &cli.Uint64Flag{ Name: "max-fd", Value: 0, EnvVars: []string{"RAINBOW_MAX_FD"}, - Usage: "Libp2p resource manager file description limit. Defaults to the process' fd-limit/2", + Usage: "Maximum number of file descriptors. Defaults to 50% of the process' limit", }, &cli.StringFlag{ Name: "routing", Value: "", - Usage: "RoutingV1 Endpoint (if none is supplied use the Amino DHT and cid.contact)", + Usage: "RoutingV1 Endpoint (otherwise Amino DHT and cid.contact is used)", }, &cli.BoolFlag{ - Name: "dht-fallback-shared-host", - Value: false, - Usage: "If using an Amino DHT client should the libp2p host be shared with the data downloading host", + Name: "dht-share-host", + Value: false, + EnvVars: []string{"RAINBOW_DHT_SHARED_HOST"}, + Usage: "If false, DHT operations are run using an ephemeral peer, separate from the main one", }, &cli.StringFlag{ Name: "denylists", Value: "", EnvVars: []string{"RAINBOW_DENYLISTS"}, - Usage: "Denylist subscriptions (comma-separated)", + Usage: "Denylist HTTP subscriptions (comma-separated). Must be append-only denylists", }, } @@ -139,6 +180,15 @@ func main() { Running this command will generate a random seed and print it. The value can be used with the RAINBOW_SEED env-var to use key-derivation from a single seed to create libp2p identities for the gateway. + +The seed can be provided to rainbow by: + + - Storing it in $RAINBOW_DATADIR/seed + - Storing it in $CREDENTIALS_DIRECTORY/seed + - Passing the --seed flag + +In all cases the --seed-index flag will be necessary. Multiple gateways can +share the same seed as long as the indexes are different. `, Flags: []cli.Flag{}, Action: func(c *cli.Context) error { @@ -152,9 +202,6 @@ to create libp2p identities for the gateway. }, } - app.Name = "rainbow" - app.Usage = "a standalone ipfs gateway" - app.Version = version app.Action = func(cctx *cli.Context) error { ddir := cctx.String("datadir") cdns := newCachedDNS(dnsCacheRefreshInterval) @@ -209,7 +256,7 @@ to create libp2p identities for the gateway. InMemBlockCache: cctx.Int64("inmem-block-cache"), RoutingV1: cctx.String("routing"), KuboRPCURLs: getEnvs(EnvKuboRPC, DefaultKuboRPC), - DHTSharedHost: cctx.Bool("dht-fallback-shared-host"), + DHTSharedHost: cctx.Bool("dht-shared-host"), DenylistSubs: getCommaSeparatedList(cctx.String("denylists")), }