iroh start command

[b5]

Command for starting a long-running iroh process that participates in an IPFS network.

$ iroh start --help
iroh-start
start a long running iroh process

USAGE:
    iroh start

OPTIONS:
    -h, --help    Print help information

Iroh start kicks off a long running process that manages p2p connections, serves
any configured APIs, and proxies access for other iroh processes to shared 
resources like store and network connections. While iroh start is running iroh 
will initiate connections to other peers in the network to both provide and 
fetch content, all of which can be governed through configuration.

When iroh start is running, it acquires a lock on shared resources. Running an
iroh command from another terminal will be executed as a remote procedure call
on the 'iroh start' process. To check if a command will run through 'iroh start'
use `iroh status`.

Shutdown

To stop iroh start, send a SIGINT signal to it (e.g. by pressing 'Ctrl-C')
or send a SIGTERM signal to it (e.g. with 'kill'). It may take a while for the
daemon to shutdown gracefully, but it can be killed forcibly by sending a
second signal.

This is analagous to kubo daemon.

Differences from Kubo

Kubo has 17 flags on kubo daemon, none of which we plan to support in the v0.1.0 release.

[faassen]

How do we know whether to start iroh one or iroh cloud? Or do we go for just starting iroh one for now?

[faassen]

I slightly prefer iroh serve over iroh start. iroh serve implies there's some kind a server you can connect to, whereas iroh start doesn't.

Related to this: in #175 we discussed implicitly starting the iroh services if we use other commands. I don't know whether it'd shut down after command completion or continue running in the background as a service for other commands to use. I think the latter may be rather too confusing, though.

[faassen]

I'll note that iroh-one currently defines a bunch of options already to start it, and currently it errors out if you don't supply --store-path. I think we should go with the principle that iroh-one should just work without configuration and default to some path for th store, like iroh-one-store or something.

The other options are something to review in the near future.

[b5]

How do we know whether to start iroh one or iroh cloud? Or do we go for just starting iroh one for now?

Great question. We've decided to skip trying to figure out what starting iroh cloud from a single command would be because deploying cloud is super involved and platform dependent. So start will only apply to iroh one for the foreseeable future.

I slightly prefer iroh serve over iroh start. iroh serve implies there's some kind a server you can connect to, whereas iroh start doesn't.

See, I think you're right, and yet many folks in web3 will scream at us because "it's not a server! decentralize!". We'll have to leave some space to let others weigh in, but the distinction is silly imho, and I'd vote we go with iroh serve because it's the most clear label for the command. It's a server. There happens to be lots of them and they can talk to each other.

Related to this: in #175 we discussed implicitly starting the iroh services if we use other commands.

Let's not do that. One-off commands that don't have a server process to delegate to should release all resources upon completion. Yes, this might be slow. It'll be our job to make it fast in the long run.

I'll note that iroh-one currently defines a bunch of options already to start it, and currently it errors out if you don't supply --store-path. I think we should go with the principle that iroh-one should just work without configuration and default to some path for the store, like iroh-one-store or something.

We should pick a default store path, creating it automatically if it doesn't exist. Default path should be inside a store directory in the application files location, so $HOME/.local/share/iroh/store on linux.

[Winterhuman]

I think iroh serve could be confused for something else, new users might mistake serve for providing or syncing the repo's data to the network rather than a daemon process (I still see many new users think content itself is uploaded to IPFS), using the full name of server would make this as clear as possible. Also, is there any reason the term daemon is being avoided here?

[dignifiedquire]

both server and serve are too little in my opinion. It starts a p2p server, a gateway server and a database. Please let’s just stick with start and stop, any additional qualifiers are half truths we need to explain and can confusee users.

[dignifiedquire]

nginx is even simpler, you just run nginx, no additional command, just options for configuration

[dignifiedquire]

I bring up nginx as it is a much better example of software to take inspiration from when it comes to UX than kubo.

[b5]

is there any reason the term daemon is being avoided here?

We think we can do better in terms of UX. deamon isn't obvious to a newcomer for a command that should be invoked. Kubo puts kubo daemon in the "advanced" command group, yet kubo cat for a non-local CID requires running a deamon. If we're going to run this command often, let's give it a common name and group it with often-used commands.

both server and serve are too little in my opinion. It starts a p2p server, a gateway server and a database.

Agree with this. Let's stick with start.

[faassen]

My current understanding:

• There's a separate iroh-one binary

• iroh start starts this as a sub-process. share a CLI between iroh one and iroh cloud #175

[faassen]

I'm wondering whether the decision to have the iroh CLI be a thin wrapper makes iroh start something we don't want to do yet; it's extra work and there are unanswered quetions. iroh start starts iroh-one, but if you want to start iroh-cloud in the future we don't really know whether iroh start even makes sense. Why not maintain iroh-one as the official way to start iroh then?

[faassen]

[copied from Discord]

The more I think about it given the change in direction I think we should maintain iroh-ctl as a crate for the iroh CLI for now, and have iroh-one be the way to start iroh, and have no iroh start at all for the time being. Because the proposed behavior for iroh start means it just passes stuff along to iroh-one, and we have no meaning for iroh start for iroh-cloud, and we may never have a useful meaning for it with iroh-cloud (as fundamentally it's separate processes likely to be running on separate servers started by something else).

If we make iroh start start iroh-one we're really saying "please install binary iroh-one and iroh both, and iroh start won't work if you don't have iroh-one." That's cumbersome and tricky to debug if it goes wrong. We make everyone's life simpler by saying "to start iroh-one, run it", and "to control iroh, use the iroh command".

[faassen]

I get that we want iroh to be a single entry point into iroh and that there's a start for that reason. Here are some reasons I have trouble with this approach:

• With iroh-cloud, iroh start should be actively avoided. Now these are advanced users so it's not a biggie, but it's still weird that we have such fundamental looking commands in the top CLI namespace that should not be used.

• In the possible future that we're not going to do right now, where we have a fat iroh that automatically runs enough of iroh in the background to complete a iroh get or iroh add, again iroh start and iroh stop become confusing. Do I start first and then add? What's the difference? How do I tell what's happening from each other? We may never go into this future but it's a trade-off.

• When iroh start fails due to installation problems, people need to learn about iroh-one anyway. Whereas if we just explained run iroh-one it's clear from the start. Maybe this won't happen very often.

• iroh-one has a bunch of command line arguments. iroh start would need to forward them all. To have a good -h in iroh start it somehow needs to replicate these, but at the same time cannot depend on the iroh-one codebase. So either:

  • we only make iroh start do a strict subset of iroh-one (and refer people to iroh-one if they want to do the rest)
  • we're maintaining the CLI twice with the risk of skew between them
  • we're maintaining some kind of odd -h forwarding behavior
  • we forward all CLI args but don't document them in iroh start
  • we have to extract a special package just for the CLI types of iroh-one so we can reuse it in iroh

The last reason weighs most strongly on my mind as we have to get this right sooner rather than later. The other reasons do contribute to my worry though.

[faassen]

Here's what iroh-one takes as arguments right now:

Usage: iroh-one [OPTIONS]

Options:
  -p, --gateway-port <GATEWAY_PORT>  Gateway
  -w, --writeable <WRITEABLE>        [possible values: true, false]
  -f, --fetch <FETCH>                [possible values: true, false]
  -c, --cache <CACHE>                [possible values: true, false]
      --metrics                      
      --tracing                      
      --denylist                     
      --store-path <STORE_PATH>      Path to the store
      --cfg <CFG>                    
  -h, --help                         Print help information
  -V, --version                      Print version information

the best route I can see to make sure iroh start takes the same CLI arguments is to extract the CLI structs from iroh-one and maintain them in a new iroh-one-clap crate. (I think iroh-one-cli is not the right name, as the CLI is still implemented in iroh-one).

[b5]

Please think about this from the perspective of a first time user. We've designed iroh so it can't do anything at all without a running daemon. How on earth could we not provide a first time user with a simple command to get them up & running?

Asking users to learn things is a big ask. Asking users to learn about 2 things is a bigger ask. Our architectural choices mean the daemon & CLI are in separate binaries, but that's our problem, and it's our job to push learning about multiple binaries until they actually need it.

With iroh-cloud, iroh start should be actively avoided...

Not actively avoided. Anyone working with cloud is going to need to read the manual. Running a local node is a common pattern for talking to a remote node via the IPFS protocol. We will absolutely write guides where DevOps users deploy somewhere in the cloud, then run iroh start to spin up a local node & confirm they can connect to their new remote.

In the future we also want to allow hybridized configurations where some services are backed by remotes (for example: serve gateway & p2p with a local iroh node, but talk to a cloud-backed store). That setup will be defined in configuration and still work with iroh start.

In the possible future that we're not going to do right now ...

Let's not code against a possible future we've explicitly decided against. Iroh requires a daemon process. Users need an easy way to start the daemon. They don't care about a command that might go away one day.

we only make iroh start do a strict subset of iroh-one (and refer people to iroh-one if they want to do the rest)

Let's do this. I don't think start should accept any flags, which is why I specified it should have none in the help text that opens this issue.

Let's look at if this way: iroh start is a porcelain command. If you needed to manually construct git commits using plumbing commands, you wouldn't be so inclined to use git, would you?

[faassen]

a possible future
we've explicitly decided against. Iroh
requires a daemon process.

Ah, I hadn't realized that the idea that iroh get etc will run the necessary services implictly was definitely off the table forever.