[GH-ISSUE #92] Create informational files for the server repo #47

Closed
opened 2026-09-04 00:21:47 +02:00 by Stone_Red · 10 comments
Owner

Originally created by @stephan418 on GitHub (Jul 30, 2022).
Original GitHub issue: https://github.com/detleph/server/issues/92

Originally assigned to: @Stefan-5422 on GitHub.

The server shoud have information for people who (somehow) happen to find the repo

Furhter info: https://dev.to/github/how-to-create-the-perfect-readme-for-your-open-source-project-1k69

As always, this should stay rather PII-free (so no constributors or production link or anything)

Files:

  • CONTRIBUTING.md (short and simple)
  • README.md (General stuff like installation guidance, description, maybe stack)
    • This should also contain information about Docker and other things that might be a hassle to set up (depending on the machine) -> Especially what email protocols will be used when deploying, ...
Originally created by @stephan418 on GitHub (Jul 30, 2022). Original GitHub issue: https://github.com/detleph/server/issues/92 Originally assigned to: @Stefan-5422 on GitHub. _The server shoud have information for people who (somehow) happen to find the repo_ Furhter info: https://dev.to/github/how-to-create-the-perfect-readme-for-your-open-source-project-1k69 As always, this should stay rather PII-free (so no constributors or production link or anything) Files: - [ ] CONTRIBUTING.md (short and simple) - [ ] README.md (General stuff like installation guidance, description, maybe stack) - This should also contain information about Docker and other things that might be a hassle to set up (depending on the machine) -> Especially what email protocols will be used when deploying, ...
Stone_Red added the documentationenhancement labels 2026-09-04 00:21:47 +02:00
Author
Owner

@stephan418 commented on GitHub (Jul 30, 2022):

Other assignees: @Flexla54

<!-- gh-comment-id:1200153812 --> @stephan418 commented on GitHub (Jul 30, 2022): Other assignees: @Flexla54
Author
Owner

@Stefan-5422 commented on GitHub (Aug 1, 2022):

I'm not good at writing readme files as I myself do not know what I want out of them.

Maybe move this to Flexla54

<!-- gh-comment-id:1200844250 --> @Stefan-5422 commented on GitHub (Aug 1, 2022): I'm not good at writing readme files as I myself do not know what I want out of them. Maybe move this to Flexla54
Author
Owner

@stephan418 commented on GitHub (Aug 15, 2022):

Detleph / Server

Warning

Uncharted territories ahead
This repostiory is part of the 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.

About 📑

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).

Technology ⚙

The server is build as a monolithic app with cutting-edge technologies, using Node.js:

Tech Description
NodeJS Fast JavaScript runtime
Express.js Simple, extensible web framework
TypeScript JavaScript with syntax for types
Prisma Fully type-safe ORM
Postgres Relational database management system (main database)
Redis Fast in-memory database (side database for OTPs, ...)
Docker Docker for fast and reproducible deployments
GitHub For code hosting, collaboration, project planning and CI/CD
REST 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.

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 (Please make sure to install version 2)
  • Docker: Official website
  • Git: Official website (For Windows, please make sure to install Git in the WSL distro)

Set up

Clone the repository:

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. <password>) with your own values (eg. good?password)

DATABASE_PASSWORD="<strong database password>"
PORT="3000"
DOMAIN="<server domain name>"
MAILPASSWORD="<strong mail server password>"
ALLOW_ORIGIN="*"
FRONTEND_MAIL_ENDPOINT="<link to be in verification email>"

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 🌐

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 DEVELOPMENT.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

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 community and site helped massively with their answers 🥇
<!-- gh-comment-id:1214791858 --> @stephan418 commented on GitHub (Aug 15, 2022): # Detleph / Server > **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). ## About 📑 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). ### 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. `<password>`) with your own values (eg. `good?password`) ``` DATABASE_PASSWORD="<strong database password>" PORT="3000" DOMAIN="<server domain name>" MAILPASSWORD="<strong mail server password>" ALLOW_ORIGIN="*" FRONTEND_MAIL_ENDPOINT="<link to be in verification email>" ``` 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 DEVELOPMENT.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 🥇
Author
Owner

@stephan418 commented on GitHub (Aug 15, 2022):

@Stefan-5422

I'm not good at writing readme files as I myself do not know what I want out of them.

Maybe move this to Flexla54

Could you please add some paragraph on the email settings (and DNS records and so on)? or at least a link to a guide

<!-- gh-comment-id:1214881615 --> @stephan418 commented on GitHub (Aug 15, 2022): @Stefan-5422 > I'm not good at writing readme files as I myself do not know what I want out of them. > > Maybe move this to Flexla54 Could you please add some paragraph on the email settings (and DNS records and so on)? or at least a link to a guide
Author
Owner

@stephan418 commented on GitHub (Aug 17, 2022):

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.

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: 🔥

./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
<!-- gh-comment-id:1218101570 --> @stephan418 commented on GitHub (Aug 17, 2022): # 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
Author
Owner

@stephan418 commented on GitHub (Sep 17, 2022):

@Stefan-5422 Please have a look at this and move to Review after: https://github.com/detleph/server/issues/92#issuecomment-1214881615

<!-- gh-comment-id:1250025139 --> @stephan418 commented on GitHub (Sep 17, 2022): @Stefan-5422 Please have a look at this and move to Review after: https://github.com/detleph/server/issues/92#issuecomment-1214881615
Author
Owner

@stephan418 commented on GitHub (Sep 17, 2022):

Contributing (to any Detleph repository)

Firstly, thank you a lot for engaging with the project and possibly even contributing. Please read through this file thoroughly before submitting code so that you are clear about what happens with your code after submitting.

Code guidlines

As most projects, the Detleph team decided on some general guidelines to ensure code quality and readability.

Formatting

Each change should conform to our styling guidlines (enforced through Prettier based on the configuration file .prettierrc located at the top-level of each repo (eg. this one)

If you do not have Prettier installed, you can easility insteall an extension for your code editor (The extension should automatically recognize our style guide). Alternatively, you can also run the "Format files using Prettier" workflow on your branch or just submit a Pull request and ask our team to format

Clean code

Please keep general clean code principles in mind (such as DRY and YAGNI, expaling in this guide

Security

Please also think about the security aspects of your changes: Does it disable or interfere with any of the security systems in place?, Does it ignore authorization?, ...

Also, importantly note that we of course review the code before merging, so if you do not wholly understand the code of others and its interactions with yours, that's not a problem at all.

Note


As we are a fairly small team, all of these guidlines are rather "lax" and will of course be checked and possibly implemented by us when you open a pull requests so that the released version is rock solid ⛰

Workflow

We organize all of our tasks in GitHub Project boards and issues. You can always take any issue or card that is not currently assigned to anyone. If you wish to be listed as the assignee, please just leave a comment on the issue. You can of course also always submit unsolicited changes!

1: Fork the repository

In order to be able to edit the code in our projects, you will need to fork them. Please click on the "Fork" button in the repository in question and then clone and edit this one on your local machine. (Described in detail here)

2: Write code

Firstly, you of course have to write code (based on the projects above or your own idea).

3: Commit

Please commit regularly,. Small commits are much easier to handle than big commits.
Also, please keep your commit message concise and, for bigger changes, list the changes and intentions behind them in the description (with 1 blank line between message and description, as stated in the first paragraph here

4: Open a pull request

Warning


If you contribute your code to our repository (which will be done by opening a pull request), you agree to publish your code under the terms of the MIT license. This is describe further in the Licensing section of this document.

If you have finished your contributions, please open a pull request to our repository.

5: Be patient

Once we see a new contribution, we will have it go through the usual checks and, if everything goes to plan, merge it!

Licensing

The projects in the Detleph organization are all licensed under the MIT license or a compatible license. Thereafter, "contribution" refers to source code or any other type of content submitted to us (the Detleph project team) by the means described below.
By opening a pull request containing your contribution, pushing your contribution to our repositories or otherwise contributing to the projects, you confirm that you are the author of the contribution and agree to the publication of your contribution under the terms of the MIT license, as found in our repositories in the LICENSE file or under https://spdx.org/licenses/MIT.html.

<!-- gh-comment-id:1250032124 --> @stephan418 commented on GitHub (Sep 17, 2022): # Contributing (to any Detleph repository) Firstly, thank you a lot for engaging with the project and possibly even contributing. Please read through this file _thoroughly_ before submitting code so that you are clear about what happens with your code after submitting. ## Code guidlines As most projects, the Detleph team decided on some general guidelines to ensure code quality and readability. ### Formatting Each change should conform to our styling guidlines (enforced through [Prettier](https://prettier.io/) based on the configuration file _.prettierrc_ located at the top-level of each repo (eg. [this one](https://github.com/detleph/server/blob/main/.prettierrc)) If you do not have Prettier installed, you can easility insteall an extension for your code editor (The extension should automatically recognize our style guide). Alternatively, you can also run the "Format files using Prettier" workflow on your branch or just submit a Pull request and ask our team to format ### Clean code Please keep general clean code principles in mind (such as DRY and YAGNI, expaling in [this guide](https://x-team.com/blog/principles-clean-code/) ### Security Please also think about the security aspects of your changes: Does it disable or interfere with any of the security systems in place?, Does it ignore authorization?, ... Also, **importantly** note that we of course review the code before merging, so if you do not wholly understand the code of others and its interactions with yours, that's not a problem at all. > **Note** > As we are a fairly small team, all of these guidlines are rather "lax" and will of course be checked and possibly implemented by us when you open a pull requests so that the released version is rock solid ⛰ ## Workflow We organize all of our tasks in GitHub Project boards and issues. You can always take any issue or card that is not currently assigned to anyone. If you wish to be listed as the assignee, please just leave a comment on the issue. You can of course also always submit unsolicited changes! ### 1: Fork the repository In order to be able to edit the code in our projects, you will need to fork them. Please click on the "Fork" button in the repository in question and then clone and edit this one on your local machine. (Described in detail [here](https://docs.github.com/en/get-started/quickstart/fork-a-repo)) ### 2: Write code Firstly, you of course have to write code (based on the projects above or your own idea). ### 3: Commit Please commit regularly,. Small commits are much easier to handle than big commits. Also, please keep your commit message concise and, for bigger changes, list the changes and intentions behind them in the description (with 1 blank line between message and description, as stated in the first paragraph [here](https://git-scm.com/docs/git-commit#_discussion) ### 4: Open a pull request > **Warning** > If you contribute your code to our repository (which will be done by opening a pull request), you agree to publish your code under the terms of the [MIT license](https://spdx.org/licenses/MIT.html). This is describe further in the [Licensing](#Licensing) section of this document. If you have finished your contributions, please [open a pull request](https://docs.github.com/en/get-started/quickstart/fork-a-repo) to our repository. ### 5: Be patient Once we see a new contribution, we will have it go through the usual checks and, if everything goes to plan, merge it! ## Licensing The projects in the Detleph organization are all licensed under the MIT license or a compatible license. Thereafter, "contribution" refers to source code or any other type of content submitted to us (the Detleph project team) by the means described below. By opening a pull request containing your contribution, pushing your contribution to our repositories or otherwise contributing to the projects, you confirm that you are the author of the contribution and agree to the publication of your contribution under the terms of the MIT license, as found in our repositories in the `LICENSE` file or under https://spdx.org/licenses/MIT.html.
Author
Owner

@Stefan-5422 commented on GitHub (Sep 17, 2022):


In the first comment the description for the Server Repo includes reference to AGPL instead of MIT.

Moving this to Review. Will add the part for configuring the DNS after taking another look at the proxying and other stuff so that I do not need to rewrite that part later.

<!-- gh-comment-id:1250066221 --> @Stefan-5422 commented on GitHub (Sep 17, 2022): --- In the first comment the description for the Server Repo includes reference to AGPL instead of MIT. --- Moving this to Review. Will add the part for configuring the DNS after taking another look at the proxying and other stuff so that I do not need to rewrite that part later.
Author
Owner

@stephan418 commented on GitHub (Sep 17, 2022):

Perfect, thx 👌

<!-- gh-comment-id:1250067773 --> @stephan418 commented on GitHub (Sep 17, 2022): Perfect, thx 👌
Author
Owner

@Flexla54 commented on GitHub (Oct 6, 2022):

This Part is taken out of the readme because the insomnia config file contains sensitive data!

Set up a Insomnia REST Client for testing the API (Optional)

Install Insomnia

Please follow the instructions on the Insomnia Website and install the client.

Clone the Insomnia config for the Detleph Server

git clone https://github.com/detleph/insomnia-config.git detleph-server-insomnia

Import the Insomnia Config

https://docs.insomnia.rest/insomnia/import-export-data
Open the File and select from Design | Debug | Test the Debug Tab in order to see the requests.

<!-- gh-comment-id:1269624024 --> @Flexla54 commented on GitHub (Oct 6, 2022): ## This Part is taken out of the readme because the insomnia config file contains sensitive data! ### Set up a Insomnia REST Client for testing the API (Optional) #### Install Insomnia Please follow the instructions on the [Insomnia Website](https://insomnia.rest/download) and install the client. #### Clone the Insomnia config for the Detleph Server ```sh git clone https://github.com/detleph/insomnia-config.git detleph-server-insomnia ``` #### Import the Insomnia Config https://docs.insomnia.rest/insomnia/import-export-data Open the File and select from `Design | Debug | Test` the Debug Tab in order to see the requests.
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: detleph/server#47