From 6d5427c399d26c7dcb9531acb7cbfe29f8e39703 Mon Sep 17 00:00:00 2001 From: Laurin <60652077+Flexla54@users.noreply.github.com> Date: Thu, 13 Oct 2022 15:03:42 +0200 Subject: [PATCH] Updated the README and CONTRIBUTING.md --- CONTRIBUTING.md | 41 ++++++++++++++++++ README.md | 109 +++++++++++++++++++++++++++++++++++++++++------- 2 files changed, 135 insertions(+), 15 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..7cda338 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,41 @@ +# Developing for the Detleph Server 👷‍♂️ + +The Detleph Server comes with configuration and scripts for easy local development and hot reloading. This files describes how to set up your local system to get the best experience when developing. + +> **Warning** +> The development script starts the server in a very insecure mode, exposes sensitive information stored in the database and disables a bunch of security features (such as **password requirements** for the databases), so it should **never** be used in any live environment accessible by untrusted actors. + +## Setup + +### Dependencies + +Make sure you have all the prerequisites listed under the Dependencies section of the REAMDE.md file installed locally. + +### Clone the server repository and its submodules + +> **Note** +> This step assumes that you just want to experiment with the server locally (without merging the changes into the upstream branch). If you want to submit a contribution, please create a fork as described in the CONTRIBUTING.md file under "Create a fork" and then proceed to the next step here. + +```sh +git clone --recursive https://github.com/detleph/server.git +``` + +### Start the server + +The server comes with a simple development script which sets up the docker environment for hot reloading: 🔥 + +```sh +./dev.sh +``` + +This should set up the local environment and restart the server when changes are detected. + +## Development script - Usage + +### Container recreation prompts + +If you start the `./dev.sh` script again after the server already has initialized once, it will ask you if you would like to recreate the server again. Genererally, you do not have to do this if the current configuration is working. If you, however, update the database schema or something similar, you will need to recreate both the server container _and_ the other services if prompted. + +### CLI options + +- `-s`: Remove all prompts and start the server with the default settings (eg. without recreating the containers diff --git a/README.md b/README.md index 8afa06d..cb9a215 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,98 @@ -# server +# Detleph / Server -## SETUP +> **Warning** **Uncharted territories ahead ⛵** +> This repostiory is part of the [Detleph](https://github.com/detleph) event management sytsem. If you want to deal with the server in isolation, this is the place for you. Otherwise, for **installation instructions, guides and other general information**, please visit the [parent repository](https://github.com/detleph/detleph). -Before Runningthis on you local machine some things have to be setup +## About 📑 -1. Run npm install -2. Add .env file with following variables: +Detleph is a modern event management system built with extensibility, scalability and ease-of-use in mind. This repository contains _all_ of the backend code, collectively called the _Detleph server_. It is the backbone of the system for storing, providing and managing all data related to your upcoming event(s). - ``` - DATABASE_URL: ADDRESS TO YOUR DATABASE - DATABASE_PASSWORD: PASSOWRD OF THE DATABASE - PORT: PORT WHERE THE API SHOULD RUN - DOMAIN: THE DOMAIN NAME OF THE SERVER - MAILPASSWORD: THE PASSWORD FOR THE MAIL ACCOUNT - DEV: SWITCH FOR DEV MODE AFFECTS EMAIL SERVER - ALLOW_ORIGIN: ORIGIN OF THE PRODUCTION CLIENT (FOR CORS) - FRONTEND_MAIL_ENDPOINT: THE ENDPOINT THE FRONTEND DOES EMAIL-VERIFICATION - ``` +### Technology ⚙ + +The server is build as a monolithic app with cutting-edge technologies, using Node.js: +Tech | Description +------------------- | -------- +[![NodeJS](https://img.shields.io/badge/Node.js-6DA55F?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org/en/about/) | Fast JavaScript runtime +[![Express.js](https://img.shields.io/badge/express.js-%23404d59.svg?style=for-the-badge&logo=express&logoColor=%2361DAFB)](https://expressjs.com/) | Simple, extensible web framework +[![TypeScript](https://img.shields.io/badge/typescript-%23007ACC.svg?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/) | JavaScript with syntax for types +[![Prisma](https://img.shields.io/badge/Prisma-3982CE?style=for-the-badge&logo=Prisma&logoColor=white)](https://www.prisma.io/) | Fully type-safe ORM +[![Postgres](https://img.shields.io/badge/postgres-%23316192.svg?style=for-the-badge&logo=postgresql&logoColor=white)](https://www.postgresql.org/) | Relational database management system (main database) +[![Redis](https://img.shields.io/badge/redis-%23DD0031.svg?style=for-the-badge&logo=redis&logoColor=white)](https://redis.io/) | Fast in-memory database (side database for OTPs, ...) +[![Docker](https://img.shields.io/badge/docker-%230db7ed.svg?style=for-the-badge&logo=docker&logoColor=white)](https://www.docker.com/) | Docker for fast and reproducible deployments +[![GitHub](https://img.shields.io/badge/github-%23121011.svg?style=for-the-badge&logo=github&logoColor=white)](https://github.com/features) | For code hosting, collaboration, project planning and CI/CD +[REST](https://www.ibm.com/cloud/learn/rest-apis) | The whole API is designed around the REST principles + +## Getting started 🆕 + +> **Note** +> As this repository only contains the server, this guide is only concerned with setting up the server and the API (which cannot, or rather should not, be used by _normal_ users) + +> For instrcutions on how to set up a fully working system, see the [parent repository](https://github.com/detleph/detleph). + +### Dependencies + +Going furhter, we will assume that you have access to a UNIX-like OS and bash, Git and Docker. If you do not have access to any of these, please see: + +- Bash, for _windows_: [WSL](https://docs.microsoft.com/en-us/windows/wsl/install) (Please make sure to install version 2) +- Docker: [Official website](https://docs.docker.com/get-docker/) +- Git: [Official website](https://git-scm.com/) (For Windows, please make sure to install Git in the WSL distro) + +### Set up + +#### Clone the repository: + +```sh +git clone --recursive https://github.com/detleph/server.git +``` + +#### Create a file called `.env` with the following contents 📁 + +Please replace the text in angle braces (eg. ``) with your own values (eg. `good?password`) + +``` +DATABASE_PASSWORD="" +PORT="3000" +DOMAIN="" +MAILPASSWORD="" +ALLOW_ORIGIN="*" +FRONTEND_MAIL_ENDPOINT="" +``` + +For a detailed explanation of all these options (and some more), please visit the wiki (coming soon) 🧠 + +#### Start the databases, email server and detleph server 🌐 + +```sh +docker-compose up +``` + +#### Finished ✨ + +The server should now be running on port 3000 (`http://localhost:3000`) + +## Usage 🏃 + +For detailed API documentation and usage guides, please see the wiki (coming soon) + +## Development & Contributing 👩‍💻 + +Firstly, we are very excited to welcome any contributions to our projects and help prospective open-sourcerers! 👥 +To get started with developing for the server (along with references for all the tooling, configuration and development modes), please take a look at the [CONTRIBUTING.md](https://github.com/detleph/server/blob/main/CONTRIBUTING.md) file in the repository + +If you want to develop a feature and contribute it to the project, please check out our contributing guidelines and workflows in the CONTRIBUTING.md file + +If you have any questions or issues, do not refrain from reaching out to us by opening an issue or reaching out to one of us (@stephan418, @Stefan-5422 or @Flexla54) directly 📫 + +## Issues ⚠ + +If you have any issues, questions or impulses relating to the server, feel free to open an issue on this repository or by [clicking here](https://github.com/detleph/server/issues/new) + +## License 👩‍⚖️ + +The license for the server (most likely MIT) can be found in the `LICENSE` file + +## Acknowledgements + +We lots of amazing resources and projects graciously shared by the community in the development of this project: + +- The [StackOverflow](https://stackoverflow.com/) community and site helped massively with their answers 🥇