diff --git a/docs/content/dev/authentication.md b/docs/content/dev/authentication.md index 1b218f8cf..f2354e99b 100644 --- a/docs/content/dev/authentication.md +++ b/docs/content/dev/authentication.md @@ -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 diff --git a/docs/content/dev/getting-started.md b/docs/content/dev/getting-started.md index 977e12d8b..edf8920f2 100644 --- a/docs/content/dev/getting-started.md +++ b/docs/content/dev/getting-started.md @@ -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 + +## 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 diff --git a/docs/content/dev/setup/frontend.md b/docs/content/dev/setup/frontend.md index 57fa26cf1..783a41545 100644 --- a/docs/content/dev/setup/frontend.md +++ b/docs/content/dev/setup/frontend.md @@ -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