docs: Fixes and new guides from quick-start beta testing - #238
Conversation
fcbbd20 to
ea8c9e1
Compare
| ## Migrating from FoundriesFactory | ||
| Have an existing factory with provisioned devices? The | ||
| [migration guide](./docs/migration.md) covers signing with your factory PKI, | ||
| importing your fleet's TUF root, and repointing devices at this server. |
There was a problem hiding this comment.
I think this should somehow be part of "quick-start" section. Otherwise it implies you could do a quick-start and then migrate from a FoundriesFactory which won't work.
or - we leave it like this and assume that while our initial users will mostly be FF users, eventually that will be the exception.
There was a problem hiding this comment.
Leaving for now and we can move this if needed in a later PR.
| docker compose run --rm server --datadir=/data pki-init --dnsname <HOSTNAME> --factory <FACTORY> | ||
| docker compose run --rm server --datadir=/data auth-init --test | ||
| docker compose run --rm server --datadir=/data tuf-init | ||
| docker compose up -d |
There was a problem hiding this comment.
this is probably the right way. However, we could introduce an entrypoint.sh script that detects an unprovisioned /data directory and run these command automagically.
There was a problem hiding this comment.
I didn't want to hard-code the Dockerfile to a "development" container. In theory, a user can provision the datadir whichever way they want it and then spin the same container. I also wasn't sure what the e2e section and our CI were using the container for and didn't wan to break them.
There was a problem hiding this comment.
doesn't have to be in the Dockerfile - the entrypoint can be mounted via your compose yml
ea8c9e1 to
dec4984
Compare
|
Rebased on |
818fff4 to
0474031
Compare
kprosise
left a comment
kprosise
left a comment
There was a problem hiding this comment.
Syntax and style suggestions provided. There are other issues with these pages, such as the frequency of pointing readers to other pages.
There needs to be a balance between not repeating content, and having a focused flow; directing a reader to a different page breaks the flow adding to their cogitative load.
Links can also frequently be combined with the first mention of the content, rather than a "…see link".
That said, these issues can be worked on in follow up PRs.
kprosise
left a comment
kprosise
left a comment
There was a problem hiding this comment.
Syntax and style suggestions provided. There are other issues with these pages, such as the frequency of pointing readers to other pages.
There needs to be a balance between not repeating content, and having a focused flow; directing a reader to a different page breaks the flow adding to their cogitative load.
Links can also frequently be combined with the first mention of the content, rather than a "…see link".
That said, these issues can be worked on in follow up PRs.
doanac
left a comment
doanac
left a comment
There was a problem hiding this comment.
I only have a couple nits. I think we should go ahead and get this merged soon as its an overall improvement. We can circle back and start to think more about bigger usability topics.
0474031 to
2d0ca69
Compare
|
Rebase to Next I'll apply comments |
2d0ca69 to
466bde8
Compare
|
This was a really nice clean up. Thank you for the reviews! I applied mostly all of the changes requested (those that weren't applied, I didn't resolve) and reflowed the docs around those edits so that we keep our typical 80-char width in the .md files. Hopefully that doesn't make this too hard to re-review. I added a STYLE.md to #235 based on the findings here. |
The note framed the auth-init dependency as import-specific, but a plain tuf-init also fails without the HMAC secret, and the root-key backup warning applies to both paths. Signed-off-by: Michael Scott <mike@foundries.io> Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The guide ended by naming sota.toml settings without their values and never explained how a device obtains its mTLS client certificate. Show enrollment with fio-device-register pointed at this server. Signed-off-by: Michael Scott <mike@foundries.io> Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The Factory-PKI signing flow and the TUF root import only apply to users bringing an existing FoundriesFactory fleet to this server, yet the quick-start walked every reader through them. Collect them in docs/migration.md, organized as a migration: sign the server TLS certificate with the Factory PKI, import the fleet's TUF root, and repoint provisioned devices at the new gateway — the last giving the sota.toml server settings their actual values. While moving the content: document the local sign-csr signing alternative, correct the roots tarball command to download-roots, and fix a heading typo. Link the guide from README.md, the quick-start, and run-locally's limitations. Signed-off-by: Michael Scott <mike@foundries.io> Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Document standing up an evaluation server in Docker: build the image from contrib/server/Dockerfile, initialize the datadir through the container, and serve — including the docker compose quick launch, the existing-Factory-PKI variant, and a warning that the published ports listen on all host interfaces. The image build fails when the embedded UI assets are Git-LFS pointer stubs, and a server built from such a checkout refuses to start; describe that behavior and the git lfs pull recovery. Signed-off-by: Michael Scott <mike@foundries.io> Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The compose instructions ran a bare auth-init, which configures no auth provider and leaves serve unable to start; index the directory contents and defer setup steps to the container guide. Signed-off-by: Michael Scott <mike@foundries.io> Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Document the serve listen-address flags, the certificate lifetime options, and manual device registration against POST /v1/devices — the flow behind fio-device-register, for devices without it. The gateway port is baked into enrollment sota.toml files, so it must be chosen before enrolling devices. Signed-off-by: Michael Scott <mike@foundries.io> Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The --auth mode wraps the local provider documented in docs/auth.md; point readers at it. Signed-off-by: Michael Scott <mike@foundries.io> Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
466bde8 to
84b9cd7
Compare
|
Re-re-based on |
|
Merging on @doanac approval. We can pickup the loose ends in a new PR (or as needed). |
FYI, per our style guidelines, we use 100-char as a suggestion, and semantic line breaks are strongly encouraged (not strongly enforced as a lot of folks have struggled with the idea in the past) |
These docs are kind of messy with regards to that. Its been more written around 72ish character line break. I think some big change for doing semantic lines would be nice; but it might take some effort to fix unless claude can do it easily. |
I have a task to teach claude to do just that…first few attempts have failed hilariously however. |
3 participants
Doc fixes and new guides from walking the quick start as a new user.
fio-device-register (and mention fioup).
quick start: factory-PKI signing, TUF root import, repointing devices.
serve, compose quick launch;
contrib/README.mdbecomes an index.manual device registration against
POST /v1/devices.