mirrors/hedgedoc
1
0
Fork 0
mirror of https://github.com/hedgedoc/hedgedoc.git synced 2024-09-18 15:08:47 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 9

fix(docs): adjust frontend and reverse proxy docs

Browse source 
Signed-off-by: Tilman Vatteroth <git@tilmanvatteroth.de>
This commit is contained in:
Tilman Vatteroth 2022-11-11 11:27:05 +01:00
parent 5275007a98
commit d5dfbb575a
No known key found for this signature in database
GPG key ID: B97799103358209B
8 changed files with 148 additions and 127 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
README.md
View file

@ -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

0
frontend/dev-reverse-proxy/.gitignore → dev-reverse-proxy/.gitignore vendored
View file

0
frontend/dev-reverse-proxy/Caddyfile → dev-reverse-proxy/Caddyfile
View file

37
docs/content/dev/getting-started.md
View file

@ -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

19
docs/content/dev/setup/backend.md Normal file
View file

@ -0,0 +1,19 @@
<!--
SPDX-FileCopyrightText: 2021 The HedgeDoc developers (see AUTHORS file)
SPDX-License-Identifier: CC-BY-SA-4.0
-->
## 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.

97
docs/content/dev/setup/frontend.md Normal file
View file

@ -0,0 +1,97 @@
<!--
SPDX-FileCopyrightText: 2021 The HedgeDoc developers (see AUTHORS file)
SPDX-License-Identifier: CC-BY-SA-4.0
-->
# 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

94
frontend/README.md
View file

@ -1,94 +0,0 @@
<!--
SPDX-FileCopyrightText: 2021 The HedgeDoc developers (see AUTHORS file)
SPDX-License-Identifier: CC-BY-SA-4.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

16
frontend/dev-reverse-proxy/run-caddy.sh
View file

@ -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