onboarding suggestions

[davepacheco]

It took me a little while to get going. Here are some things I think might help. I could fix some of these but I'm not sure how you want to do it -- some of this is because the current experience is oriented around what it will look like for real customers. But in the meantime I think it's likely to confuse current users (mostly our own developers). I'm not sure how you want to balance that.

tl;dr:

• README instructions that start with git clone and end with running a successful command. It's a pretty stock cargo run, but I think you have to run login first, and it's not clear what the prompt inputs are supposed to be (see below).
• The README refers to OXIDE_TEST_API_HOST and OXIDE_TEST_API_TOKEN, but I don't think these are the right names. They don't appear in the source code anywhere. It's also not clear what their value should be. Anyway, I guess they're really only for the tests?
• If you've never run login, the tool seems to print "No hosts found" no matter what command you run. It seems like it could print something along the lines of "No local credentials found. Please run login first."
• In the login flow, it asks for a hostname. I'd suggest we say this should be a URL. When I hear "hostname" I expect it doesn't include a port, and then I wonder where to put that. This also lets the user specify http (for test environments) vs. https. Also, I was surprised that it doesn't accept an IP address. (Actually, it accepts 127.0.0.1, but then I got an error about it being an invalid dnsname.) Is that intentional?
• In the login flow, it tells you where you can get an API token, but I don't think the URL it gives you corresponds to anything we implement today.
• In the login flow, it wasn't clear what the API token was supposed to be. I figured it was oxide-spoof-001de000-05e4-4000-8000-000000004007 but should we document that in the README or something?
• nit (obviously didn't throw me off): In the login flow, the prompts have two colons after them.

---

More details, in case it's a useful sort of first-user-research-log: I kept trying to run commands:

$ target/debug/oxide api /organizations
No hosts found

I thought "maybe it's like aws configure" and I found config, so I ran that. But it seems to configure basics about the tool and not the hosts it's trying to connect to.

From the README, I found the OXIDE_TEST_API env vars and tried those, with no effect. My bad for only skimming the README and not noticing that that's just for running tests (and also those are the wrong names).

At this point I started digging in the source for that error message and stumbled by accident on something called "login", so I looked for a login command, and that was important. The first time, since it asked for a host, I gave it 127.0.0.1 (where I'm running Nexus):

$ target/debug/oxide auth login
Oxide instance hostname:: 127.0.0.1
Tip: you can generate an API Token here https://127.0.0.1/account
Paste your authentication token:: oxide-spoof-001de000-05e4-4000-8000-000000004007
error sending request for url (https://127.0.0.1/session/me): error trying to connect: tcp connect error: Connection refused (os error 146)

Makes sense -- I'm running it on a different port than 80. Still, I don't normally expect that "host" can include "host and port". Fixed that:

$ target/debug/oxide auth login
Oxide instance hostname:: 127.0.0.1:12220
Tip: you can generate an API Token here https://127.0.0.1:12220/account
Paste your authentication token:: oxide-spoof-001de000-05e4-4000-8000-000000004007
error sending request for url (https://127.0.0.1:12220/session/me): error trying to connect: invalid dnsname

It looks like it doesn't accept 127.0.0.1 because it always does a DNS resolution. In this case I can use localhost:

$ target/debug/oxide auth login
Oxide instance hostname:: localhost:12220
Tip: you can generate an API Token here https://localhost:12220/account
Paste your authentication token:: oxide-spoof-001de000-05e4-4000-8000-000000004007
✔ Logged in as 001de000-05e4-4000-8000-000000004007

$ target/debug/oxide api /organizations
{
  "items": [],
  "next_page": null
}

Success!

[jessfraz]

The README refers to OXIDE_TEST_API_HOST and OXIDE_TEST_API_TOKEN, but I don't think these are the right names. They don't appear in the source code anywhere. It's also not clear what their value should be. Anyway, I guess they're really only for the tests?

This is only for the tests and I fixed in the readme sorry about that, its OXIDE_TEST_TOKEN and OXIDE_TEST_HOST.
And the tests will tell you if you didn't set these as well

And for the record this readme will only be seen by contributors the docs are what actually matters, I linked to them from the readme as they will be the canonical source of truth.

If you've never run login, the tool seems to print "No hosts found" no matter what command you run. It seems like it could print something along the lines of "No local credentials found. Please run login first."

Fixed the error to be No hosts found. Try logging in with oxide auth login.

In the login flow, it asks for a hostname. I'd suggest we say this should be a URL. When I hear "hostname" I expect it doesn't include a port, and then I wonder where to put that. This also lets the user specify http (for test environments) vs. https. Also, I was surprised that it doesn't accept an IP address. (Actually, it accepts 127.0.0.1, but then I got an error about it being an invalid dnsname.) Is that intentional?

seems weird it wouldn't work w 127.0.0.1, for the record it does accept http/https

ill look into the error
but seems like its more like the naming of it as a host that you don't like? or that is unintuitive?

In the login flow, it tells you where you can get an API token, but I don't think the URL it gives you corresponds to anything we implement today.

Theres a TODO in the code its a placeholder for now, we don't know the URL yet.

In the login flow, it wasn't clear what the API token was supposed to be. I figured it was oxide-spoof-001de000-05e4-4000-8000-000000004007 but should we document that in the README or something?

Will that spoof token exist for ever I mostly didn't document in the readme in case it disappears one day, but can add it in was just curious
nit (obviously didn't throw me off): In the login flow, the prompts have two colons after them.

[jessfraz]

another question would be are we going to require that customer deployments are at an https address, I feel like most would be so it makes the host prompt a bit nicer if that is the case but I know the env variables (not the prompt) work for "http://" addresses

[jessfraz]

but the prompt assumes https:// since i figured customer deployments would be secure but unsure if that is even true

[davepacheco]

Thanks for those fixes!

If you've never run login, the tool seems to print "No hosts found" no matter what command you run. It seems like it could print something along the lines of "No local credentials found. Please run login first."

Fixed the error to be No hosts found. Try logging in with oxide auth login.

Sweet! That's definitely were I spent the most time.

In the login flow, it asks for a hostname. I'd suggest we say this should be a URL. When I hear "hostname" I expect it doesn't include a port, and then I wonder where to put that. This also lets the user specify http (for test environments) vs. https. Also, I was surprised that it doesn't accept an IP address. (Actually, it accepts 127.0.0.1, but then I got an error about it being an invalid dnsname.) Is that intentional?

seems weird it wouldn't work w 127.0.0.1, for the record it does accept http/https

ill look into the error but seems like its more like the naming of it as a host that you don't like? or that is unintuitive?

Cool. If it already accepts http/https and a port then I'd just call it a URL in the prompt.

Yeah, I think it's a separate issue that the IP address didn't work.

In the login flow, it tells you where you can get an API token, but I don't think the URL it gives you corresponds to anything we implement today.

Theres a TODO in the code its a placeholder for now, we don't know the URL yet.

Yeah, makes sense.

In the login flow, it wasn't clear what the API token was supposed to be. I figured it was oxide-spoof-001de000-05e4-4000-8000-000000004007 but should we document that in the README or something?

Will that spoof token exist for ever I mostly didn't document in the readme in case it disappears one day, but can add it in was just curious nit (obviously didn't throw me off): In the login flow, the prompts have two colons after them.

I think the question is where do we want to put documentation for today's users (i.e., Oxide engineers)? It doesn't have to be here. But somewhere we should have something that says "hey, if you want to use this thing, you need a token. The current implementation is this spoof auth scheme. Here's what you can provide."

[jessfraz]

yeah I added the token to the readme for now

[jessfraz]

okay made some edits to the prompt and how it works to make it more clear for insecure oxide instances with http://

[jessfraz]

oxidecomputer/oxide.rs@addd8dc

[jessfraz]

I think with that I've addressed all of yours but will keep this open if others find things while testing, I also open sourced the repo, such that now, the clis you all have downloaded will be able to check if there's updates and we make sure everyone is using the latest