Documentation

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:
 

main.go

@@ -31,103 +31,144 @@ 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{
 
 		&cli.StringFlag{
 			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")),
 		}