At Oxide, RFDs (Requests for Discussion) play a crucial role in driving our architectural and design decisions. They document the processes, APIs, and tools that we use. To learn more about the RFD process, you can read RFD 1: Requests for Discussion.
This repo represents the web frontend for browsing, searching, and reading RFDs, not to be
confused with oxidecomputer/rfd, a private repo
that houses RFD content and discussion, or
oxidecomputer/rfd-api, the backend that serves
RFD content to this site and gives us granular per-user control over RFD access. You can
read more about this site and how we use it in our blog post
A Tool for Discussion.
The site is built with Remix, a full stack React web framework.
rfd-api collects the RFDs from
oxidecomputer/rfd, stores them in a database, and serves them through an HTTP API, which
this site uses. RFD discussions come from an associated pull request on GitHub. These are
linked to from the document and displayed inline alongside the text.
Documents are rendered with
react-asciidoc, a work-in-progress React
AsciiDoc renderer we've created, built on top of
asciidoctor.js.
Our site is hosted on Vercel and this repo uses the Vercel adapter, but Remix can be deployed to any JS runtime.
This repo is public because others are interested in the RFD process and the tooling we've built around it. In its present state, it's the code we're using on our deployed site and is tightly coupled to us and our design system. We're open to PRs that improve this site, especially if they make the repo easier for others to use and contribute to. However, we are a small company, and the primary goal of this repo is as an internal tool for Oxide, so we can't guarantee that PRs will be integrated.
npm v7 or higher is recommended due to
lockfileVersion: 2
in package-lock.json.
npm installnpm run devand go to http://localhost:3000. The site will live-reload on file changes. The site should work with local RFDs (without search) without having to set any env vars. See below on how to set up local RFD preview.
To preview an RFD you're working on in the site, use the LOCAL_RFD_REPO env var to tell
the site to pull content from your local clone of the rfd repo instead of the API. No
other env vars (such as the ones that let you talk to CIO) are required. For example:
LOCAL_RFD_REPO=~/oxide/rfd npm run devThen go to localhost:3000/rfd/0123 as normal. When you edit the file in the other repo,
the page will reload automatically. The index also works in local mode: it lists all RFDs it
can see locally.
Note that this does not pull RFDs from all branches like the production site does. It simply reads files from the specified directory, so it will only have access to files on the current branch. Missing RFDs will 404. If you are working on two RFDs and they're on different branches, you cannot preview both at the same time unless you make a temporary combined branch that contains both.
When running in a non-local mode, the following settings must be specified:
-
SESSION_SECRET- Key that will be used to signed cookies -
RFD_API- Backend RFD API to communicate with (i.e. https://api.server.com) -
RFD_API_CLIENT_ID- OAuth client id create via the RFD API -
RFD_API_CLIENT_SECRET- OAuth client secret create via the RFD API -
RFD_API_GOOGLE_CALLBACK_URL- Should be of the form ofhttps://{rfd_site_hostname}/auth/google/callback -
RFD_API_GITHUB_CALLBACK_URL- Should be of the form ofhttps://{rfd_site_hostname}/auth/github/callback -
STORAGE_URL- Url of bucket for static assets -
STORAGE_KEY_NAME- Name of the key defined inSTORAGE_KEY -
STORAGE_KEY- Key for generating signed static asset urls -
GITHUB_APP_ID- App id for fetching GitHub PR discussions -
GITHUB_INSTALLATION_ID- Installation id of GitHub App -
GITHUB_PRIVATE_KEY- Private key of the GitHub app for discussion fetching
Unless otherwise noted, all components are licensed under the Mozilla Public License Version 2.0.