From d5dfbb575ab775ed82f6dae7a5ed1526699345c0 Mon Sep 17 00:00:00 2001 From: Tilman Vatteroth Date: Fri, 11 Nov 2022 11:27:05 +0100 Subject: [PATCH] fix(docs): adjust frontend and reverse proxy docs Signed-off-by: Tilman Vatteroth --- README.md | 12 ++- .../.gitignore | 0 .../Caddyfile | 0 docs/content/dev/getting-started.md | 37 ++++--- docs/content/dev/setup/backend.md | 19 ++++ docs/content/dev/setup/frontend.md | 97 +++++++++++++++++++ frontend/README.md | 94 ------------------ frontend/dev-reverse-proxy/run-caddy.sh | 16 --- 8 files changed, 148 insertions(+), 127 deletions(-) rename {frontend/dev-reverse-proxy => dev-reverse-proxy}/.gitignore (100%) rename {frontend/dev-reverse-proxy => dev-reverse-proxy}/Caddyfile (100%) create mode 100644 docs/content/dev/setup/backend.md create mode 100644 docs/content/dev/setup/frontend.md delete mode 100644 frontend/README.md delete mode 100644 frontend/dev-reverse-proxy/run-caddy.sh diff --git a/README.md b/README.md index 5eceb21b3..4f3a4de96 100644 --- a/README.md +++ b/README.md @@ -32,11 +32,19 @@ We are currently working on HedgeDoc 2, a complete rewrite of HedgeDoc. Please n - This branch contains the latest development code and does not implement all features yet. **If you are looking for the 1.x source code, have a look at the [master branch](https://github.com/hedgedoc/hedgedoc/tree/master).** -- HedgeDoc 2 will be split in two components: the backend (this repo) and the frontend in - the [react-client repo](https://github.com/hedgedoc/react-client). - The 1.x release is maintenance-only. We do not accept feature requests or PRs for this release anymore and may choose to close non-critical bug reports, if the bug will be non-existent in 2.0. +- HedgeDoc 2 will be split in two components. The backend and the frontend. Both are present in this repository. +## Development +Information for setting up a local development environment can be found in the [developer documentation](./docs/content/dev/getting-started.md) + +## HedgeDoc 2 UI Test +Curious about the new look and feel of HedgeDoc 2? We provide a demo of the new UI on [hedgedoc.dev](https://hedgedoc.dev). This +version uses mocked data and has no data persistence. + +The UI test is hosted by [netlify](https://netlify.com). Please check +their [privacy policy](https://netlify.com/privacy) as well as [ours](https://hedgedoc.org/privacy-policy). ## Contributions diff --git a/frontend/dev-reverse-proxy/.gitignore b/dev-reverse-proxy/.gitignore similarity index 100% rename from frontend/dev-reverse-proxy/.gitignore rename to dev-reverse-proxy/.gitignore diff --git a/frontend/dev-reverse-proxy/Caddyfile b/dev-reverse-proxy/Caddyfile similarity index 100% rename from frontend/dev-reverse-proxy/Caddyfile rename to dev-reverse-proxy/Caddyfile diff --git a/docs/content/dev/getting-started.md b/docs/content/dev/getting-started.md index f6ac1847b..ba1433c4e 100644 --- a/docs/content/dev/getting-started.md +++ b/docs/content/dev/getting-started.md @@ -1,21 +1,28 @@ # Getting started -## Preparing for running the backend code +## Preparation -**ToDo:** Document how to set up development environment using docker. - -1. Clone the repository with `git clone https://github.com/hedgedoc/hedgedoc.git` - (cloning is the preferred way, but you can also download and unzip a release) - -2. Enter the directory and run `yarn install`. - -3. Run `cp .env.example .env` to use the example configuration. - - Alternatively, set up a [.env](../config/index.md) or set up - [environment variables](../config/index.md) yourself. - -4. Run `openssl rand -hex 16 | sed -E 's/(.*)/HD_SESSION_SECRET=\1/' >> .env` to generate a session secret if you have not set one manually before. +Setup the [backend](./setup/backend.md) and the [frontend](./setup/frontend.md). ## Running backend and frontend together -The documentation for setting up the frontend and how to use it and the backend together can be found in the [frontend repository README](https://github.com/hedgedoc/react-client/blob/main/README.md). +To use backend and frontend together in development mode you'll need a local reverse proxy that combines both services under one URL origin. +We recommend to use our pre-configured [caddy](https://caddyserver.com/) configuration. + +### Prepare the backend + +In the `backend` directory +1. make sure that `HD_DOMAIN` in `.env` is set to `http://localhost:8080`. +2. start the backend by running `yarn start:dev`. + +### Preparing the frontend + +In the frontend directory +1. Start the frontend in dev or production mode using any method described in the [frontend setup documentation](./setup/frontend.md). + If you use the production build then make sure that you set the environment variable `HD_EDITOR_BASE_URL` to the same value as `HD_DOMAIN` in the backend. + +### Running the reverse proxy + +1. Download the latest version of caddy from [the caddy website](https://caddyserver.com/). You don't need any plugin. Place the downloaded binary in the directory `dev-reverse-proxy`. Don't forget to mark the file as executable using `chmod +x caddy` +2. Start the reverse proxy using `./caddy run`. +3. Open your browser on http://localhost:8080 diff --git a/docs/content/dev/setup/backend.md b/docs/content/dev/setup/backend.md new file mode 100644 index 000000000..f96464182 --- /dev/null +++ b/docs/content/dev/setup/backend.md @@ -0,0 +1,19 @@ + + +## Setting up the backend + +**ToDo:** Document how to set up development environment using docker. + +You need at least Node 14 (we recommend Node 18) and [yarn](https://yarnpkg.com/). +You MUST use yarn! There is no support for npm. + +1. Clone this repo (e.g. `git clone https://github.com/hedgedoc/hedgedoc.git hedgedoc`) +2. Go into the backend directory (e.g. `cd hedgedoc/backend`) +3. Run `yarn install` +4. Create an environment file. We recommend to use the example file by running `cp .env.example .env` + You can modify this file according to the [configuration documentation](../config/index.md). +5. Run `openssl rand -hex 16 | sed -E 's/(.*)/HD_SESSION_SECRET=\1/' >> .env` to generate a session secret if you have not set one manually before. diff --git a/docs/content/dev/setup/frontend.md b/docs/content/dev/setup/frontend.md new file mode 100644 index 000000000..1e68977ae --- /dev/null +++ b/docs/content/dev/setup/frontend.md @@ -0,0 +1,97 @@ + + +# Setting up the frontend + +You need at least Node 14 (we recommend Node 18) and [yarn](https://yarnpkg.com/). +You MUST use yarn! There is no support for npm. + +1. Clone this repo (e.g. `git clone https://github.com/hedgedoc/hedgedoc.git hedgedoc`) +2. Go into the frontend directory (e.g. `cd hedgedoc/frontend`) +3. Run `yarn install` + +## Development mode + +### Mocked Backend Mode + +To start the development mode run `yarn run dev`. If not configured otherwise the development mode will run in mock-mode +which +emulates a HedgeDoc backend. +The app should run now and be available under [http://localhost:3001](http://localhost:3001) in your browser. +In development mode the app will autoload changes you make to the code. + +### With local backend + +To start the development mode with an actual HedgeDoc backend use `yarn run dev:with-local-backend` instead. +This task will automatically set `HD_EDITOR_BASE_URL` to `http://localhost:8080`. + +### Performance + +The development mode compiles everything on demand. So the first time you open a page in the browser it may take some +time. + +## Production mode + +Use `yarn build` to build the app in production mode and save it into the `.next` folder. The production build is +minimized +and optimized for best performance. Don't edit the generated files in the `.next` folder by hand! + +You can run the production build using the built-in server with `yarn start`. +You MUST provide the environment variable `HD_EDITOR_BASE_URL` with protocol, domain and (if needed) subdirectory path ( +e.g. `http://localhost:3001/`) so the app knows under which URL the frontend is available in the browser. + +### Production mock build + +It is also possible to create a production build that uses the emulated backend by using `yarn build:mock`. This is +usually not needed except for demonstration purposes like `https://hedgedoc.dev`. + +## Environment Variables + +The following environment variables are recognized by the frontend process. + +| Name | Possible Values | Description | +|--------------------------|----------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| HD_EDITOR_BASE_URL | Any URL with protocol, domain and optionally directory and port. Must end with a trailing slash. (e.g. `http://localhost:3001/`) | The URL under which the frontend is expected. Setting this is mandatory so the server side rendering can generate assets URLs. You only need to set this yourself if you use the production mode. | +| HD_RENDERER_BASE_URL | Same as `HD_EDITOR_BASE_URL` | You can provide this variable if the renderer should use another domain than the editor. This is recommended for security reasons but not mandatory. This variable is optional and will fallback to `HD_EDITOR_BASE_URL` | +| NEXT_PUBLIC_USE_MOCK_API | `true`, `false` | Will activate the mocked backend | +| NEXT_PUBLIC_TEST_MODE | `true`, `false` | Will activate additional HTML attributes that are used to identify elements for test suits. | + +Variables that start with `NEXT_PUBLIC_` will be compiled into the build. You can't change them at after compilation. +You shouldn't need to set them yourself. Use the designated npm tasks instead. + +## UI Test + +Curious about the new look and feel? We provide a demo of the new UI on [hedgedoc.dev](https://hedgedoc.dev). This +version uses mocked data and has no data persistence. + +The UI test is hosted by [netlify](https://netlify.com). Please check +their [privacy policy](https://netlify.com/privacy) as well as [ours](https://hedgedoc.org/privacy-policy). + +## Running Tests + +### Unit + +Unit testing is done via jest. + +1. Run `yarn test` + +### End2End + +We use [cypress](https://cypress.io) for e2e tests. + +1. Start the frontend with `yarn dev:test` (or use a test build using `yarn build:test` which you can start + using `yarn start`). The usage of `:test` is mandatory! +2. Run `yarn cy:open` to open the cypress test loader +3. Choose your browser and start a test suite + +To run all tests in a headless browser use `yarn cy:run:chrome` or `yarn cy:run:firefox` + +### Bundle analysis + +You can inspect the generated production-bundle files to look for optimization issues. + +1. run `yarn analyze`. This will overwrite any existing builds! +2. Open the generated `.next/server/analyze/server.html` in your favourite browser diff --git a/frontend/README.md b/frontend/README.md deleted file mode 100644 index 8e3060dab..000000000 --- a/frontend/README.md +++ /dev/null @@ -1,94 +0,0 @@ - - -# HedgeDoc - React Client - -![test, build](https://github.com/hedgedoc/react-client/workflows/test,%20build/badge.svg) -![e2e](https://github.com/hedgedoc/react-client/workflows/e2e/badge.svg) -![lint](https://github.com/hedgedoc/react-client/workflows/lint/badge.svg) -[![Language grade: JavaScript](https://img.shields.io/lgtm/grade/javascript/g/hedgedoc/react-client.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/hedgedoc/react-client/context:javascript) -[![Total alerts](https://img.shields.io/lgtm/alerts/g/hedgedoc/react-client.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/hedgedoc/react-client/alerts/) - -This is the new, improved and better looking frontend for HedgeDoc 2.0. -Our goal is to recreate the current frontend in react and to improve it. - -## UI Test - -Curious about the new look and feel? We provide a demo of the new UI on [hedgedoc.dev](https://hedgedoc.dev). This -version uses mocked data and has no data persistence. - -The UI test is hosted by [netlify](https://netlify.com). Please check -their [privacy policy](https://netlify.com/privacy) as well as [ours](https://hedgedoc.org/privacy-policy). - -## Preparation - -You need at least Node 14 (we recommend Node 18) and [yarn](https://yarnpkg.com/). -You MUST use yarn! There is no support for npm. - -1. Clone this repo (e.g. `git clone https://github.com/hedgedoc/react-client.git hedgedoc-react-client`) -2. Go inside the repo (e.g. `cd hedgedoc-react-client`) -3. Run `yarn install` - -## Development mode - -To start the development mode run `yarn run dev`. If not configured otherwise the development mode will run in mock-mode which -emulates a hedgedoc backend. -If you want to use the development with a real hedgedoc backend then run `yarn run dev:for-real-backend` instead. -The app should run now and be available under [http://localhost:3001](http://localhost:3001) in your browser. -In development mode the app will autoload changes you make to the code. - -## Production mode - -Use `yarn build` to build the app in production mode and save it into the `.next` folder. The production build is minimized -and optimized for best performance. Don't edit them by hand! - -You can run the production build using the built-in server with `yarn start`. -You MUST provide the environment variable `HD_EDITOR_BASE_URL` with protocol, domain and (if needed) path ( -e.g. `http://127.0.0.1:3001/`) so the app knows under which URL it is available in the browser. -Optionally you can also provide `HD_RENDERER_BASE_URL` if the renderer should use another domain than the editor. This is -recommended for security reasons but not mandatory. - -### Production mock build - -It is also possible to create a production build that uses the emulated backend by using `yarn build:mock`. - -## Using to backend and frontend together - -To use backend and frontend together you'll need a reverse proxy that combines both services under one URL origin. -We provide a configuration for [caddy](https://caddyserver.com/) in the directory `dev-reverse-proxy`. - -1. Make sure that the backend is running on port `3000` (which is the default), and that `HD_DOMAIN` is set - to `http://localhost:8080`. -2. Start the frontend by using either running `yarn dev:for-real-backend` or by running a production build - with `HD_EDITOR_BASE_URL` set to `http://localhost:8080/`. -3. Start the reverse proxy. You can use the script `run-caddy.sh` in the `dev-reverse-proxy` directory or download a - caddy binary from [caddy](https://caddyserver.com/) and start it using `caddy run`. - -## Running Tests - -### Unit - -Unit testing is done via jest. - -1. Run `yarn test` - -### End2End - -We use [cypress](https://cypress.io) for e2e tests. - -1. Start the frontend with `yarn dev:test` (or use a test build using `yarn build:test` which you can start - using `yarn start`). The usage of `:test` is mandatory! -2. Run `yarn cy:open` to open the cypress test loader -3. Choose your browser and start a test suite - -To run all tests in a headless browser use `yarn cy:run:chrome` or `yarn cy:run:firefox` - -### Bundle analysis - -You can inspect the generated production-bundle files to look for optimization issues. - -1. run `yarn analyze`. This will overwrite any existing builds! -2. Open the generated `.next/server/analyze/server.html` in your favourite browser diff --git a/frontend/dev-reverse-proxy/run-caddy.sh b/frontend/dev-reverse-proxy/run-caddy.sh deleted file mode 100644 index a807285c7..000000000 --- a/frontend/dev-reverse-proxy/run-caddy.sh +++ /dev/null @@ -1,16 +0,0 @@ -#!/bin/bash -# -# SPDX-FileCopyrightText: 2022 The HedgeDoc developers (see AUTHORS file) -# -# SPDX-License-Identifier: AGPL-3.0-only -# - -set -e - -if [ ! -f caddy ] -then -curl -o caddy "https://caddyserver.com/api/download" -chmod +x ./caddy -fi - -exec ./caddy run