umputun · umputun · Jan 30, 2022 · Jan 30, 2022
@@ -4,6 +4,7 @@ target
 /logs/
 /target/
 /var/
+/web/
 debug
 debug.test
 .vscode
@@ -17,6 +18,7 @@ remark42
 /bin/
 /backend/var/
 /backend/app/var/
+/backend/web/
 compose-private-backend.yml
 compose-private-frontend.yml
 compose-private.yml

@@ -39,9 +39,9 @@ For a description of the Bot API, see this page: https://core.telegram.org/bots/
 
 ## Authentication
 
-To enable Telegram authentication for the users, set variable `AUTH_TELEGRAM=true`.
+**IMPORTANT: It doesn't work as of 30.01.2022, will be working after [this](https://github.com/umputun/remark42/issues/707) issue resolution** (waits for frontend support).
 
-_Note: this functionality is not fully available yet and still work in progress._
+To enable Telegram authentication for the users, set variable `AUTH_TELEGRAM=true`.
 
 ## Notifications
 
@@ -57,7 +57,7 @@ To integrate notifications about any comment on your sites with remark42 with [T
 
 ### Notifications for users
 
-**IMPORTANT: It doesn't work as of 20.12.2021, will be working after [this](https://github.com/umputun/remark42/issues/830) issue resolution** (waits for frontend support).
+**IMPORTANT: It doesn't work as of 30.01.2022, will be working after [this](https://github.com/umputun/remark42/issues/830) issue resolution** (waits for frontend support).
 
 Enabling Telegram user notifications allows users to sign up for notifications about replies to their messages. To do it, set the variable `NOTIFY_USERS=telegram`.
 

@@ -2,4 +2,46 @@
 title: Backend Development Guidelines
 ---
 
-In Progress...
+You can use a fully functional local version to develop and test both frontend and backend. It requires at least 2GB RAM or swap enabled.
+
+To bring it up, run:
+
+```shell
+cp compose-dev-backend.yml compose-private.yml
+# now, edit / debug `compose-private.yml` to your heart's content
+
+# build and run
+make rundev
+# this is an equivalent of these two commands:
+# docker-compose -f compose-private.yml build
+# docker-compose -f compose-private.yml up
+```
+
+It starts Remark42 on `127.0.0.1:8080` and adds local OAuth2 provider "Dev". To access the UI demo page go to <http://127.0.0.1:8080/web/>. By default, you would be logged in as `dev_user`, defined as admin. You can tweak any of the [supported parameters](https://remark42.com/docs/configuration/parameters/) in corresponded yml file.
+
+**Important**: use `127.0.0.1` and not `localhost` to access the server, as otherwise, CORS will prevent your browser from authentication to work correctly.
+
+Backend Docker Compose config (`compose-dev-backend.yml`) by default skips running frontend related tests. Frontend Docker Compose config (`compose-dev-frontend.yml`) by default skips running backend related tests and sets `NODE_ENV=development` for frontend build.
+
+### Backend development
+
+#### With Docker
+
+Run tests in your IDE, and re-run `make rundev` each time you want to see how your code changes behave to test them at <http://127.0.0.1:8080/web/>.
+
+#### Without docker
+
+You have to [install](https://golang.org/doc/install) the latest stable `go` toolchain to run the backend locally.
+
+In order to have working Remark42 installation you need once to copy frontend static files to `./backend/web` directory from `master` docker image:
+
+```shell
+docker pull umputun/remark42:master
+docker create -ti --name remark42files umputun/remark42:master sh
+docker cp remark42files:/srv/web/ ./backend/
+docker rm -f remark42files
+```
+
+To run backend - `cd backend; go run app/main.go server --dbg --secret=12345 --url=http://127.0.0.1:8080 --admin-passwd=password --site=remark`. It stars backend service with embedded bolt store on port `8080` with basic auth, allowing to authenticate and run requests directly, like this:
+
+`HTTP http://admin:[email protected]:8080/api/v1/find?site=remark&sort=-active&format=tree&url=http://127.0.0.1:8080`
@@ -2,38 +2,104 @@
 title: Frontend Development Guidelines
 ---
 
+### Frontend development
+
+#### Development tools installation
+
+You must have at least 2GB RAM or swap enabled for building.
+
+- install [Node.js 12.22](https://nodejs.org/en/) or higher
+- install [NPM 6.14.16](https://www.npmjs.com/package/npm)
+- run `npm install` inside `./frontend`
+
+Running `npm install` will set up pre-commit hooks into your git repository. They are used to reformat your frontend code using `prettier` and lint with `eslint` and `stylelint` before every commit.
+
+**Important**: use `127.0.0.1` and not `localhost` to access the server, as otherwise, CORS will prevent your browser from authentication to work correctly.
+
+#### Development against demo.remark42.com
+
+This variant of running Remark42 frontend code is preferred when you make a translation or visual adjustments that are easy to see without extensive testing.
+
+For local development mode with Hot Reloading, use `npm start`. In this case, `webpack` will serve files using `webpack-dev-server` on `127.0.0.1:9000`. By visiting <http://127.0.0.1:9000/web/>, you will get a page with the main comments' widget communicating with a demo server backend running on `https://demo.remark42.com`. But you will not be able to log in with any OAuth providers due to security reasons.
+
+You can attach the frontend to the locally running backend by providing the `REMARK_URL` environment variable.
+
+```shell
+npx cross-env REMARK_URL=http://127.0.0.1:8080 npm start
+```
+
+**Note:** If you want to redefine env variables such as `PORT` on your local instance, you can add the `.env` file to the `./frontend` folder and rewrite variables as you wish. For such functional, we use `dotenv`.
+
+#### Development against the local backend
+
+This variant of running Remark42 frontend code is preferred when you need extensive testing of your code changes, as you'll have your backend and configure it as you want, for example, enable any auth and notifications method you need to test. You can use that set up to develop and test both frontend and backend.
+
+To bring the backend up, run:
+
+```shell
+cp compose-dev-frontend.yml compose-private-frontend.yml
+# now, edit / debug `compose-private.yml` to your heart's content
+
+# build and run
+make rundev
+# this is an equivalent of these two commands:
+# docker-compose -f compose-private.yml build
+# docker-compose -f compose-private.yml up
+```
+
+Then in the new terminal tab or window, run the following to start the frontend with Hot Reloading:
+
+```shell
+cd frontend
+npm run dev
+```
+
+Developer build running by `webpack-dev-server` supports devtools for [React](https://reactjs.org/blog/2019/08/15/new-react-devtools.html#how-do-i-get-the-new-devtools) and [Redux](https://github.com/reduxjs/redux-devtools).
+
+It starts Remark42 backend on `127.0.0.1:8080` and adds local OAuth2 provider "Dev". To access the frontend running by Node, go to <http://127.0.0.1:9000/web/>. By default, you would be logged in as `dev_user`, defined as admin. You can tweak any of the [supported parameters](https://remark42.com/docs/configuration/parameters/) in corresponded yml file.
+
+Frontend Docker Compose config (`compose-dev-frontend.yml`) by default skips running backend related tests and sets `NODE_ENV=development` for frontend build.
+
+**Important**: Before submitting your changes as a Pull Request, re-run the backend using the `make rundev` command and test your changes against <http://127.0.0.1:8080/web/>, frontend, built statically (unlike frontend on port 9000, which runs dynamically). That is how Remark42 authors will test your changes once you submit them.
+
+#### Static build
+
+Remark42 frontend can be built statically, and that's how the production version works: frontend is built and then resulting files embedded into the backend, which serves them as-is. Node is not running when a user starts remark42, only the backend written in Go programming language, which also serves pre-built frontend HTML and JS and CSS files.
+
+Run `npm run build` inside `./frontend`, and result files will be saved in `./frontend/public`.
+
 ### Code Style
 
-- the project uses TypeScript to statically analyze code
-- project uses `eslint` and `stylelint` to check frontend code. You can manually run via `npm run lint`
+- The project uses TypeScript to analyze code statically
+- The project uses `eslint` and `stylelint` to check the frontend code. You can manually run via `npm run lint`
 - Git Hooks (via husky) installed automatically on `npm install`. They check and try to fix code style if possible, otherwise commit will be rejected
-- if you want IDE integration, you need `eslint` and `stylelint` plugin to be installed
+- If you want IDE integration, you need `eslint` and `stylelint` plugin to be installed
 
 ### CSS Styles
 
-- now we are migrating to CSS Modules, and this is a recommended way to stylization. A file with styles should be named like `component.module.css`
-- old component styles use BEM notation (at least it should): `block__element_modifier`. Also, there are `mix` classes: `block_modifier`
-- new way to name CSS selectors is camel-case like `blockElemenModifier` and use `classnames` to combine it
-- component base style resides in the component's root directory with a name of component converted to kebab-case. For example, `ListComments` style is located in `./app/components/list-comments/list-component.tsx`
-- any other files should be named also in kebab-case. For example, `./app/utils/get-param.ts`
+- Now we are migrating to CSS Modules, which is a recommended way of stylization. A file with styles should be named like `component.module.css`
+- Old component styles use BEM notation (at least it should): `block__element_modifier`. Also, there are `mix` classes: `block_modifier`
+- The new way to name CSS selectors is camel-case like `blockElemenModifier` and use `classnames` to combine it
+- Component base style resides in the component's root directory with a name of component converted to kebab-case. For example, `ListComments` style is located in `./app/components/list-comments/list-component.tsx`
+- Any other files should also be named in kebab-case. For example, `./app/utils/get-param.ts`
 
 ### Imports
 
-- imports for TypeScript, JavaScript files should be without extension: `./index`, not `./index.ts`
-- if the file resides in the same directory or subdirectory, import should be relative: `./types/something`
-- otherwise, it should be imported by absolute path relative to `src` folder like `common/store` which mapped to `./app/common/store.ts` in webpack, tsconfig and Jest
+- Imports for TypeScript, JavaScript files should be without extension: `./index`, not `./index.ts`
+- If the file resides in the same directory or subdirectory, the import should be relative: `./types/something`
+- Otherwise, it should be imported by absolute path relative to `src` folder like `common/store` which mapped to `./app/common/store.ts` in webpack, tsconfig, and Jest
 
 ### Testing
 
-- project uses `jest` as test harness
+- Project uses `jest` as test harness
 - Jest checks files that match regex `\.(test|spec)\.ts(x?)$`, i.e., `comment.test.tsx`, `comment.spec.ts`
-- tests are running on push attempt
-- example tests can be found in `./app/store/user/reducers.test.ts`, `./app/components/auth-panel/auth-panel.test.tsx`
+- Tests are running on push attempt
+- Example tests can be found in `./app/store/user/reducers.test.ts`, `./app/components/auth-panel/auth-panel.test.tsx`
 
 ### How to add a new locale
 
 Please see [this documentation](https://remark42.com/docs/contributing/translations/).
 
 ### Notes
 
-- frontend part being bundled on docker env gets placed on `/src/web` and is available via `http://{host}/web`. For example, `embed.js` entry point will be available at `http://{host}/web/embed.js`
+Frontend part being bundled on docker env gets placed on `/src/web` and is available via `http://{host}/web`. For example, `embed.js` entry point will be available at `http://{host}/web/embed.js`
@@ -2,70 +2,10 @@
 title: Development
 ---
 
-You can use a fully functional local version to develop and test both frontend and backend. It requires at least 2GB RAM or swap enabled.
-
-To bring it up, run:
-
-```shell
-# if you mainly work on the backend
-cp compose-dev-backend.yml compose-private.yml
-# if you mainly work on frontend
-cp compose-dev-frontend.yml compose-private.yml
-# now, edit / debug `compose-private.yml` to your heart's content
-
-# build and run
-docker-compose -f compose-private.yml build
-docker-compose -f compose-private.yml up
-```
-
-It starts Remark42 on `127.0.0.1:8080` and adds local OAuth2 provider "Dev". To access the UI demo page go to `127.0.0.1:8080/web`. By default, you would be logged in as `dev_user`, defined as admin. You can tweak any of the [supported parameters](https://remark42.com/docs/configuration/parameters/) in corresponded yml file.
-
-Backend Docker Compose config by default skips running frontend related tests. Frontend Docker Compose config by default skips running backend related tests and sets `NODE_ENV=development` for frontend build.
-
 ### Backend development
 
-To run backend locally (development mode, without Docker), you have to have to [install](https://golang.org/doc/install) the latest stable `go` toolchain.
-
-To run backend - `cd backend; go run app/main.go server --dbg --secret=12345 --url=http://127.0.0.1:8080 --admin-passwd=password --site=remark`. It stars backend service with embedded bolt store on port `8080` with basic auth, allowing to authenticate and run requests directly, like this:
-
-`HTTP http://admin:[email protected]:8080/api/v1/find?site=remark&sort=-active&format=tree&url=http://127.0.0.1:8080`
+The frontend development guide can be found [here](https://remark42.com/docs/contributing/development/backend/).
 
 ### Frontend development
 
 The frontend development guide can be found [here](https://remark42.com/docs/contributing/development/frontend/).
-
-#### Build
-
-You must have at least 2GB RAM or swap enabled for building.
-
-- install [Node.js 12.11](https://nodejs.org/en/) or higher
-- install [NPM 6.13.4](https://www.npmjs.com/package/npm)
-- run `npm install` inside `./frontend`
-- run `npm run build` there
-- result files will be saved in `./frontend/public`
-
-**Note:** Running `npm install` will set up pre-commit hooks into your git repository. It used to reformat your frontend code using `prettier` and lint with `eslint` and `stylelint` before every commit.
-
-#### Development server
-
-For local development mode with Hot Reloading, use `npm start` instead of `npm run build`. In this case, `webpack` will serve files using `webpack-dev-server` on `localhost:9000`. By visiting `127.0.0.1:9000/web`, you will get a page with the main comments widget communicating with a demo server backend running on `https://demo.remark42.com`. But you will not be able to log in with any OAuth providers due to security reasons.
-
-You can attach to the locally running backend by providing `REMARK_URL` environment variable.
-
-```shell
-npx cross-env REMARK_URL=http://127.0.0.1:8080 npm start
-```
-
-**Note:** If you want to redefine env variables such as `PORT` on your local instance, you can add `.env` file to `./frontend` folder and rewrite variables as you wish. For such functional, we use `dotenv`.
-
-The best way to start a local developer environment:
-
-```shell
-cp compose-dev-frontend.yml compose-private-frontend.yml
-docker-compose -f compose-private-frontend.yml up --build
-cd frontend
-npm run dev
-```
-
-Developer build running by `webpack-dev-server` supports devtools for [React](https://github.com/facebook/react-devtools) and
-[Redux](https://github.com/zalmoxisus/redux-devtools-extension).
@@ -43,7 +43,7 @@ below to have your translation available to all remark42 users and included in t
     2.  [Run remark42 in Docker](https://github.com/umputun/remark42#development) by issuing the following commands from the root directory of your remark42 fork:
         `shell docker-compose -f compose-dev-frontend.yml build docker-compose -f compose-dev-frontend.yml up `
 
-    3.  open [http://127.0.0.1:8080/web](http://127.0.0.1:8080/web), log in, make a comment, make a reply to a comment, and make sure your translation looks as you expect it to look
-    4.  make a screenshot from [http://127.0.0.1:8080](http://127.0.0.1:8080) with your translation in place
+    3.  open <http://127.0.0.1:8080/web/>, log in, make a comment, make a reply to a comment, and make sure your translation looks as you expect it to look
+    4.  make a screenshot from <http://127.0.0.1:8080> with your translation in place
 
 1.  after all previous steps are done, create a [Pull Request](https://github.com/umputun/remark42/pulls) to umputun/remark42 repo with your changes, attaching a screenshot or two from your local test instance to it