mirror of
https://github.com/hedgedoc/hedgedoc.git
synced 2024-11-25 03:06:31 -05:00
docs: Restructure getting-started.md and add quick start for development
Signed-off-by: Yannick Bungers <git@innay.de> Signed-off-by: Philip Molares <philip.molares@udo.edu>
This commit is contained in:
Yannick Bungers
Philip Molares
parent
9f34b5ec24
commit
61e4e846b0
3 changed files with 103 additions and 68 deletions
|
|
@ -50,7 +50,7 @@ Google account and use it to login afterwards.
|
|||
HedgeDoc is configured with two auth providers.
|
||||
|
||||
- A user logs in using auth provider A.
|
||||
- The backend recieves the profile information from provider A and notices that the username in the profile
|
||||
- The backend receives the profile information from provider A and notices that the username in the profile
|
||||
already exists in the database, but no identity for this provider-username combination exists.
|
||||
- The backend creates a new user with another username to solve the username conflict.
|
||||
- The frontend warns the user that the username provided by the auth provider is already taken and that another
|
||||
|
|
|
|||
|
|
@ -1,60 +1,133 @@
|
|||
# Getting started
|
||||
|
||||
This document will help you with setting up the development environment for HedgeDoc 2.
|
||||
To run HedgeDoc 2.0 you need three components: the backend, the frontend and the reverse proxy.
|
||||
|
||||
## Preparation
|
||||
Backend and Frontend are included in the [HedgeDoc repo](https://github.com/hedgedoc/hedgedoc). The reverse proxy can be chosen by preference. For development, we
|
||||
recommend caddy and the provided configuration.
|
||||
|
||||
### Preparing the directory
|
||||
## Quick guide for development setup
|
||||
|
||||
This describes the easiest way to start a local development environment. For other deployments follow the description
|
||||
below.
|
||||
To run HedgeDoc 2.0 you need three components: the backend, the frontend and the reverse proxy.
|
||||
|
||||
Backend and Frontend are included in the [HegdeDoc repo](https://github.com/hedgedoc/hedgedoc). The reverse proxy can be chosen by preference. For development, we
|
||||
recommend caddy and the provided configuration.
|
||||
|
||||
1. Install Node.js (at least Node 14, we recommend Node 18) and [Yarn](https://yarnpkg.com/getting-started/install)
|
||||
2. Install Caddy (select one of the two options)
|
||||
- [Download](https://caddyserver.com/) and place the `caddy` binary in `hedgedoc/dev-reverse-proxy`. Ensure it is executable with `chmod +x caddy`. Users of macOS may need to run `xattr -d com.apple.quarantine ./caddy` to lift the quarantine for executables from the internet.
|
||||
- Install Caddy using your package manager
|
||||
3. Clone [our repository](https://github.com/hedgedoc/hedgedoc.git) and go into its directory
|
||||
```shell
|
||||
git clone https://github.com/hedgedoc/hedgedoc.git
|
||||
cd hedgedoc
|
||||
```
|
||||
4. Install the dependencies in repo root directory with `yarn install`
|
||||
5. Go to `hedgedoc/commons` directory with `cd ../commons`
|
||||
6. Build the commons package with `yarn build`
|
||||
7. Goto `hedgedoc/backend` directory with `cd ../backend`
|
||||
8. Create the `.env` config file by copying the example: `cp .env.example .env`
|
||||
9. Add a value to `HD_SESSION_SECRET` in the .env file. This can be any string, which has to be a secure password for production but can be set to simple string for debug purpose.
|
||||
10. Execute the following lines
|
||||
```shell
|
||||
echo "HD_AUTH_LOCAL_ENABLE_LOGIN=true" >> .env
|
||||
echo "HD_AUTH_LOCAL_ENABLE_REGISTER=true" >> .env
|
||||
```
|
||||
11. Start the backend using `yarn start:dev`
|
||||
12. Go to `hedgedoc/frontend` directory with `cd ../frontend`
|
||||
13. Start the frontend using `yarn run dev:with-local-backend`
|
||||
14. Go to `hedgedoc/dev-reverse-proxy` with `cd ../dev-reverse-proxy`
|
||||
15. Start Caddy using `./caddy run` (if you've downloaded the binary manually) or `caddy run` (if you've installed Caddy using a package manager)
|
||||
16. Use your browser to go to <http://localhost:8080>
|
||||
|
||||
## Preconditions
|
||||
|
||||
If you want to run HedgeDoc in dev mode some preconditions have to be met.
|
||||
|
||||
1. Make sure that NodeJS is installed. You need at least Node 14 (we recommend Node 18).
|
||||
2. Make sure that [yarn](https://yarnpkg.com/) is installed.
|
||||
2. Make sure that [Yarn](https://yarnpkg.com/) is installed.
|
||||
3. Clone this repo (e.g. `git clone https://github.com/hedgedoc/hedgedoc.git hedgedoc`)
|
||||
4. Go into the cloned directory
|
||||
|
||||
### Installing the dependencies
|
||||
## Installing the dependencies
|
||||
|
||||
Because we use yarn workspaces, yarn collects the dependencies of all packages automatically in one central top-level node_modules folder.
|
||||
Because we use Yarn workspaces, Yarn collects the dependencies of all packages automatically in one central top-level
|
||||
`node_modules` folder.
|
||||
To install the dependencies execute `yarn install` at the top level of the cloned repository.
|
||||
Execute this command ONLY there. There is no need to execute the install-command for every package.
|
||||
It's important to use [yarn](https://yarnpkg.com/). We don't support npm or any other package manager and using anything else than yarn won't work.
|
||||
It's important to use [Yarn](https://yarnpkg.com/). We don't support `npm` or any other package manager and using anything
|
||||
else than Yarn won't work.
|
||||
|
||||
### Compile the commons package
|
||||
Some code is shared by backend and frontend. This code lives in the "common" package and needs to be compiled so frontend and backend can import it.
|
||||
## Build the `commons` package
|
||||
|
||||
Some code is shared by backend and frontend. This code lives in the `commons package and needs to be built so
|
||||
frontend and backend can import it.
|
||||
This only needs to be done once, except if you've changed code in the commons package.
|
||||
|
||||
1. Go into the `commons` directory.
|
||||
2. Execute `yarn build` to build the commons package.
|
||||
|
||||
## Setting up the backend
|
||||
## Setting up the Backend
|
||||
|
||||
**Note:** The backend can be mocked instead of starting it for real. This is useful, if you just want to work on the frontend. See the "Mocked backend" section below.
|
||||
|
||||
1. Go into the `backend` directory.
|
||||
2. 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).
|
||||
3. Make sure that you've set `HD_SESSION_SECRET` in your `.env` file. Otherwise, the backend won't start.
|
||||
> In dev mode you don't need a secure secret. So use any value. If you want to generate a secure session secret you can generate one using e.g. `openssl rand -hex 16 | sed -E 's/(.*)/HD_SESSION_SECRET=\1/' >> .env`.
|
||||
3. Make sure that you've set `HD_SESSION_SECRET` in your `.env` file. Otherwise, the backend won't start.
|
||||
> In dev mode you don't need a secure secret. So use any value. If you want to generate a secure session secret you
|
||||
can use e.g. `openssl rand -hex 16 | sed -E 's/(.*)/HD_SESSION_SECRET=\1/' >> .env`.
|
||||
4. Make sure that `HD_DOMAIN` in `.env` is set to the domain where Hedgedoc should be available. In local dev
|
||||
environment this is most likely `http://localhost:8080`.
|
||||
5. Start the backend by running `yarn start:dev` for dev mode or `yarn start` for production.
|
||||
|
||||
## Setting up the frontend
|
||||
|
||||
The instructions for the frontend can be found [here](./setup/frontend.md).
|
||||
The frontend can be run in four different ways. The development mode compiles everything on demand. So the first time
|
||||
you open a page in the browser it may take some time.
|
||||
See [here](setup/frontend.md) for a more detailed description of the environment variables for the frontend.
|
||||
|
||||
### Mocked backend
|
||||
|
||||
To start the development mode, run `yarn run dev`.
|
||||
By default, this will run in mock-mode, meaning instead of running a real backend the frontend mocks the backend.
|
||||
This way you can work on frontend functionality without starting up the full development environment.
|
||||
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`.
|
||||
|
||||
### 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 in any way!
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
### 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`.
|
||||
|
||||
## Running backend and frontend together
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
### 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`.
|
||||
1. Download the latest version of Caddy from [the Caddy website](https://caddyserver.com/) or alternatively install it
|
||||
using your package manager. 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`. Users of macOS may need to run `xattr -d com.apple.quarantine ./caddy` to lift the quarantine for executables from the internet.
|
||||
2. Start Caddy using `./caddy run` (if you downloaded the binary manually) or `caddy run` (if you installed Caddy via a package manager).
|
||||
3. Open your browser on http://localhost:8080
|
||||
|
|
|
|||
|
|
@ -4,44 +4,6 @@ SPDX-FileCopyrightText: 2021 The HedgeDoc developers (see AUTHORS file)
|
|||
SPDX-License-Identifier: CC-BY-SA-4.0
|
||||
-->
|
||||
|
||||
# Setting up the frontend
|
||||
|
||||
Follow the preparation instructions in [getting started](../getting-started.md)
|
||||
|
||||
## 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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue