Merge pull request #507 from ylei-tsubame/docs/ui-readmes

Web UI: READMEs

striker-ui-api/README.md

@@ -0,0 +1,33 @@
+# Anvil system striker web interface API
+
+## About NPM projects
+In essence, this module and the striker web interface module share the same management workflows:
+* All `npm` commands must be executed at the project root or lower level(s).
+* To prepare the workspace, run `npm install`.
+* To produce a production build, run `npm run build`.
+
+One major difference is there's no live development mode in this project.
+
+See the striker we interface's [README](../striker-ui/README.md) for more details.
+
+## Run prerequisites
+* This API module is targetted at NodeJS version 10, which is the default on CentOS/RHEL 8.
+* All executables/files listed in `src/lib/consts/SERVER_PATHS.ts` and their respective dependencies are required.
+
+## Build
+Run `npm run build` to produce a minified script at `out/index.js`. The output script can be executed with NodeJS assuming all prerequisites are met.
+
+There's no need to remove the old build prior to a new build because the build process always overwrites the one file.
+
+`systemd` expects the build to be placed exactly at `/usr/share/striker-ui-api/index.js` on a striker.
+
+## Logs
+At the time of writing, no logging library was added. Logs are either `stdout` or `stderr` without levels. When the API runs as a service, its logs can be viewed with `journalctl --unit striker-ui-api`.
+
+Due to the large amount of logs produced, it's highly recommended to note the time of a test, and specify a time frame with `journalctl --since <date parsable time> --until <date parsable time>` to help with the search.
+
+## Systemd service
+The service file of this API module is located in `../units/`. Environment varibles can be set with the `Environment=<variable name>=<value>` directive, i.e., to set the main server's port to `80`, use `Environment=PORT=80`.
+
+## Environment varibles
+Variables can be set to affect the API's funtionalities, i.e. listen on a different port. A complete list with explanations is located at `src/lib/consts/ENV.ts`

striker-ui/README.md

@@ -1,34 +1,46 @@
-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).
+# Anvil system striker web interface
 
-## Getting Started
+# Notes
 
-First, run the development server:
+- All NPM commands **must** be executed at the root folder of this UI module, where the `package.json` is located.
+- For those unfamiliar with git and/or the web technologies involved, it's highly recommended to clone a fresh repo as a test workspace.
 
-```bash
-npm run dev
-# or
-yarn dev
-```
+## Development prerequisites
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+- NodeJS LTS is recommended, version >= 14 is required.
+- NPM latest is recommended, version >= 6 is required.
 
-You can start editing the page by modifying `pages/index.js`. The page auto-updates as you edit the file.
+"required" means this project was started with roughly the specified version; earlier version may work.
 
-[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`.
+For Fedora, NPM is included as a dependency of NodeJS; running `sudo dnf install nodejs` should be enough.
 
-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.
+## Installation
 
-## Learn More
+Run `npm install` to download all production and development dependencies. The NPM packages will be collectively placed into a folder named `node_modules` in the root of this project.
 
-To learn more about Next.js, take a look at the following resources:
+## Live development
 
-- [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.
+Run `npm run dev` to start a local development server that listens on port 3000. Any source code changes after the dev server has started will trigger a quick partial rebuild, the changes will be reflected shortly in the browser.
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome!
+However, it's highly recommended to perform a clear-cache reload, which is usually `CTRL` + `F5`, because changes may not always reflect correctly.
 
-## Deploy on Vercel
+## Production build
 
-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.
+Run `rm -rf out && npm run build` to remove the existing build output and generate a new one. It's highly recommended to remove the old build before building a new one because the some of the generated files won't replace the old files, thus old files will remain when the whole output directory gets committed/copied.
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.
+The build is expected to be placed into the `/var/www/html/` directory on a striker.
+
+At the time of writing, the build is committed to the repository to keep the whole project's building process offline. NPM requires network to fetch dependencies before building. Ideally, the build shouldn't be included, but we cannot remove the it from repo until there's a reliable way to separate the download and build tasks.
+
+## Logs
+
+At the time of writing, no logging library has been added due to other priorities. The recommended debug logging is to temporarily add any appropriate `console` functions to suspicious areas, i.e. before and after the location where an exception was thrown.
+
+## Test with striker API
+
+Most of the API requires authentication to access. At the time of writing, the striker API can only produce cookies with its domain (including port) after successfully authenticating a user. Therefore, the striker UI must be accessed from the same location to allow the browser to read the session cookies.
+
+There are 2 tested methods to achive same-domain:
+
+1. Make changes to the source and produce a **production** build. Copy the new build to the striker and access the UI by connecting to the striker.
+2. Install a proxy/load balance server, forward `<domain>/` (root) to the server hosting the web UI, and forward `<domain>/api/` to the API. When accessing the UI, the browser only accesses the proxy and will consider the two locations to be under the same domain. thus it will see the cookies produced by authentication. A recommended server with easy-to-understand configuration is `nginx`; it's available via `dnf`.