From 4ad46a45e434dbf883468641f4bbf67303a84d53 Mon Sep 17 00:00:00 2001 From: Keith Stevens Date: Wed, 21 Dec 2022 13:15:44 +0900 Subject: [PATCH] Updating the README files to be a bit more comprehensive --- scripts/endtoend-demo/README.md | 8 +-- website/README.md | 120 +++++++++++++++++++++++++------- 2 files changed, 97 insertions(+), 31 deletions(-) diff --git a/scripts/endtoend-demo/README.md b/scripts/endtoend-demo/README.md index 49b193a5..2d738453 100644 --- a/scripts/endtoend-demo/README.md +++ b/scripts/endtoend-demo/README.md @@ -1,18 +1,14 @@ # End to End Demo -This sets up an entire stack needed to run Open Assistant, including the website, backend, and associated dependent services. +This sets up an entire stack needed to run Open Assistant, including the +website, backend, and associated dependent services. To start the service, do the following: ```sh docker compose up --build -cd ../../website -npx prisma db push ``` -NOTE: we're working on making the prisma step integrated into the docker -initialization process. - Then, navigate to `http://localhost:3000` and interact with the website. When logging in, navigate to `http://localhost:1080` to get the magic email login link. diff --git a/website/README.md b/website/README.md index d88f6bed..7d57ceaa 100644 --- a/website/README.md +++ b/website/README.md @@ -1,31 +1,109 @@ -This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app). +# Open-Assistant NextJS Website -## Required Environment Variables +## Purpose -This requires: +This provides a comprehensive webapp interface for LAION's Open Assistant +project. Initially it will support: -- `NEXT_PUBLIC_SUPABASE_URL`: A supabase Authorization URL -- `NEXT_PUBLIC_SUPABASE_ANON_KEY`: A public supabase key for Authorization +1. User registration using either Discord or Email. +1. Adding responses to incomplete Open Assistant tasks. +1. Rating or Ranking responses to Open Assistant tasks. +1. Viewing an activity leaderboard. +1. Tracking community wide updates. -These can both be optained from the Supabase project settings page. +This interface compliments the Discord bot and will give access to the same +underlying tasks. -## Getting Started +## Contributing -First, run the development server: +### Major Dependencies -```bash -npm run dev -# or -yarn dev -``` +This website is built using: -Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. +1. [npm](https://www.npmjs.com/): The node package manager for building. +1. [React](https://reactjs.org/): The core frontend framework. +1. [Next.js](https://nextjs.org/): A React scaffolding framework to streamline + development. +1. [Prisma](https://www.prisma.io/): An ORM to interact with a web specific + [Postgres](https://www.postgresql.org/) database. +1. [NextAuth.js](https://next-auth.js.org/): A user authentication framework + to ensure we handle accounts with best practices. +1. [TailwindCSS](https://tailwindcss.com/): A general purpose framework for + styling any component. +1. [Chakra-UI](https://chakra-ui.com/): A wide collection of pre-built UI + components that generally look pretty good. -You can start editing the page by modifying `pages/index.js`. The page auto-updates as you edit the file. +### Set up your environment -[API routes](https://nextjs.org/docs/api-routes/introduction) can be accessed on [http://localhost:3000/api/hello](http://localhost:3000/api/hello). This endpoint can be edited in `pages/api/hello.js`. +To contribute to the website, make sure you have the following setup and +installed: -The `pages/api` directory is mapped to `/api/*`. Files in this directory are treated as [API routes](https://nextjs.org/docs/api-routes/introduction) instead of React pages. +1. [NVM](https://github.com/nvm-sh/nvm): The Node Version Manager makes it + easy to ensure you have the right NodeJS version installed. Once installed, + run `nvm use 16` to use Node 16.x. The website is known to be stable with + NodeJS version 16.x. This will install both Node and NPM. +1. [Docker](https://www.docker.com/): We use docker to simplify running + dependent services. + +### Getting everything up and running + +If you're doing active development we suggest the following workflow: + +1. In one tab, navigate to + `${OPEN_ASSISTANT_ROOT}/scripts/frontend-development`. +1. Run `docker compose up --build`. You can optionally include `-d` to detach and + later track the logs if desired. +1. In another tab navigate to `${OPEN_ASSISTANT_ROOT/website`. +1. Run `npm install` +1. Run `npx prisma db push` (This is also needed when you restart the docker + stack from scratch). +1. Run `npm run dev`. Now the website is up and running locally at + `http://localhost:3000`. +1. To create an account, login via the user using email authentication and + navigate to `http://localhost:1080`. Check the email listed and click the + log in link. You're now logged in and authenticated. + +## Code Layout + +### React Code + +All react code is under `src/` with a few sub directories: + +1. `pages/`: All pages a user could navigate too and API URLs which are under `pages/api/`. +1. `components/`: All re-usable React components. If something gets used + twice we should create a component and put it here. +1. `lib/`: A generic place to store library files that are used anywhere. + This doesn't have much structure yet. + +NOTE: `styles/` can be ignored for now. + +### Database + +All database configurations are stored in `prisma/schema.prisma`. + +### Static Content + +All static images, fonts, svgs, etc are stored in `public/`. + +### Styles + +We're not really using CSS styles. `styles/` can be ignored. + +## Best Practices + +When writing code for the website, we have a few best practices: + +1. When importing packages import external dependencies first then local + dependencies. Order them alphabetically according to the package name. +1. When trying to implement something new, check if + [Chakra-UI](https://chakra-ui.com/) has components that are close enough to + your need. For example Sliders, Radio Buttons, Progress indicators, etc. They + have a lot and we can save time by re-using what they have and tweaking the + style as needed. +1. Format everything with [Prettier](https://prettier.io/). This is done by + default with pre-submits. We currently don't have any custom settings. +1. Define functional React components (with types for all properties when + feasible). ## Learn More @@ -33,11 +111,3 @@ To learn more about Next.js, take a look at the following resources: - [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. - [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. - -You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome! - -## Deploy on Vercel - -The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js. - -Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.