search

detleph / server

Server component of the Detleph event management system
MIT License
1 stars 0 forks source link

Create informational files for the server repo #92

Closed stephan418 closed 1 year ago

stephan418 commented 2 years ago

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:

stephan418 commented 2 years ago

Other assignees: @Flexla54

Stefan-5422 commented 2 years ago

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

stephan418 commented 2 years ago

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:

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:

stephan418 commented 2 years ago

@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

stephan418 commented 2 years ago

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

stephan418 commented 2 years ago

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

stephan418 commented 2 years ago

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.

Stefan-5422 commented 2 years ago

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.

stephan418 commented 2 years ago

Perfect, thx 👌

Flexla54 commented 1 year ago

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.