This repository contains the source code that powers Flow's Developer Portal: https://developers.flow.com
Project requires:
- Node >= 16
- Yarn >= 1.22.18
git clone https://github.com/onflow/developer-portal.git
You'll need to acquire the project's .env
file before continuing.
-
Add the
.env
file to the project root. -
docker compose up
-or, to also bring up Storybook-
docker compose --profile storybook up
Main application: http://localhost:3000/
Storybook: http://localhost:6006/ (if started using --profile storybook
)
Use the first version of the commands below if the your compose environment and container are running. Use the second version if the environment is not up or if you want to run them in a new container (this may leave orphan containers running if you run docker compose down
).
-
Connect to Redis via
redis-cli
:docker compose exec cache redis-cli -h cache -a flow_docs
docker compose run cache redis-cli -h cache -a flow_docs
-
Remove all cache data from Redis:
docker compose exec cache redis-cli -h cache -a flow_docs FLUSHALL
docker compose run cache redis-cli -h cache -a flow_docs FLUSHALL
-
Ensure node_modules is up-to-date.
docker compose restart app-yarn
()docker compose run app-yarn
- Add the
.env
file to the project root. yarn
- (Optional, if redis is not running locally) Start a redis instance:
docker run -v redis_data:/data -p 6379:6379 --name flowdocs-cache -d redis:alpine redis-server --requirepass flow_docs
- Run the desired application:
yarn run dev
to run the Docs Site (https://localhost:3000)yarn storybook
to run Storybook (https://localhost:6006)
- If you use
npm
by accident, remove anypackage.lock
files and runyarn
from the root.
- Use
yarn add <your-dep> -W
(-W
flag is necessary for now, or you'll get an error). - All deps can be installed in project root.
- Do not import anything from
@remix/**
or any components/code form the app project into the design system. The design system is meant to be standalone, and re-usable shold we change application platforms.
-
Any new environemnt variable added to
.env
should also be added to thedocker-compose.yml
-
Environment variables are handled different in remax apps, see documentation here https://remix.run/docs/en/v1/guides/envvars
The doc site pull the markdown files existing in various onflow
repositories. To see the Github Actions that triggers processing of the markdown files (i.e. refreshing cache), go to any of the repos and click on the Actions
tab.
List of repository sources:
⚠ Currently data cached in redis is not invalidated from new builds, so e.g. you might see cached mdx and markdown data from previous builds. to work around this, you need to manually remove keys from redis.
Commits pushed to the main
branch are automatically deployed to staging. Commits pushed to the production
branch are automatically deployed to production. See deploy.yml for details.
Recommended workflow to promote changes from main
(staging) to production is:
- Create a PR, production branch is locked down and a reviewer is required
- Test in staging when a PR is merged to
main
branch and deployed. - Likewise, Test when PR is merged to
production
and deployed.
If deploys fail to go out, and the github actions hang indefinitely, a workaround to fix this is:
-
Cancel the build
-
Delete the fly app that is prefixed with
fly-builder-
, this can be done through CLI as shown below, or through the fly dashboard$ fly apps list NAME OWNER STATUS LATEST DEPLOY flow-docs flow-docs running 2022-06-22T00:07:40Z flow-docs-staging flow-docs running 7m45s ago fly-builder-muddy-wildflower-4301 flow-docs pending $ fly apps destroy fly-builder-muddy-wildflower-4301 ...
-
Re-run the build by going to the latest commit on the appropriate branch, clicking "Re-run jobs", and then "Re-run failed jobs"
-
Build should succeed
- "Bad Credentials" error
- This occurs when the personal access token used expires
- Create a new personal access token with a long expiration and update fly.io
- User will need to be in
Flow Docs
organization on fly.io (Put in a IT ticket to get access if needed) - Need to install fly.io tools
brew install flyctl
more info: https://fly.io/docs/hands-on/install-flyctl/ - List secrets for flow-docs-staging
fly secrets list -a flow-docs-staging
- Update bot github token with new access token from a user that is in onFlow organization
fly secrets set BOT_GITHUB_TOKEN=github_pat_11A...MVuk -a flow-docs-staging
- This will trigger staging content checker webhook to be deployed using the new BOT_GITHUB_TOKEN value
- There are 4 icons needed
- Landing (only needed if cms doc collection has it's own landing page like Cadence and Mobile)
- Image files go in app/ui/design-system/images/ directory
- Dropdown Menu icon named as "xxx-sm.svg"
- Menu icon, shows what section the user is on "xxxx.svg" like tool-cadence.svg, tool-mobile.svg
- Landing page icon like tool-cadence-landing.svg, configuration is located in
app/ui/design-system/src/lib/Components/InternalLandingHeader/icons.ts
- Images are svg so they can scale
- Light and Dark theme changes the svg's backgrounds
- For landing page images need to add the name to schema
app/data/doc-collection-manifest-schema.json
so that flow-docs.json validation passes