From 1d17f7329ef895ea53a2f4736e2b8025408355f5 Mon Sep 17 00:00:00 2001 From: Dominik Stahl Date: Mon, 30 Jun 2025 09:49:10 +0200 Subject: [PATCH] chore: update readme with up to date infos --- README.md | 219 +++++++++++++++++++++++++++++------------------------- 1 file changed, 117 insertions(+), 102 deletions(-) diff --git a/README.md b/README.md index 56fa41d..24990d2 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,19 @@ # MeetUP +## Table of contents + +- [Description](#description) +- [Project Status](#project-status) +- [Features](#features) + - [Implemented Features](#implemented-features) + - [Planned Features](#planned-features-roadmap) +- [Technologies Used](#technologies-used) +- [Development environment setup](#development-environment-setup) + - [Without Docker](#without-docker) + - [With Docker](#with-docker) +- [Production Deployment using Docker](#production-deployment-using-docker) +- [Contributing](#contributing) + ## Description MeetUP is a social calendar application designed to make coordinating schedules with friends seamless and intuitive. It was created because it can be a hassle coordinating meetings between multiple friends and across different friend groups. MeetUP aims to simplify the process of finding mutual availability without endless back-and-forth messaging. @@ -12,52 +26,54 @@ MeetUP is a social calendar application designed to make coordinating schedules ### Implemented Features -- Core infrastructure setup in progress. No user-facing features are implemented yet. +- Event creation, deletion, and editing +- SSO and credentials login and signup +- Participant invitation and status +- Calendar of your own events +- Calendar of other users' availability (only in event creation form) ### Planned Features (Roadmap) -- **Friendships:** Connect with friends to share calendars. -- **Group Calendars:** Create and manage shared calendars for groups. -- **iCal Import:** Import existing calendars from iCalendar (.ics) files. -- **iCal Export:** Export personal or shared calendars in iCalendar (.ics) format. -- **Email Notifications:** Receive email alerts for event bookings, reminders, and updates. -- **View Blocked Slots:** See when friends are busy without revealing event details. -- **Book Timeslots:** Request and confirm meeting times in friends' available slots. -- **SSO Compatibility:** Planning for Single Sign-On integration. +- Friendships +- Group calendars +- iCal import and export +- Notifications (in-app and external/mail) ## Technologies Used This project is built with a modern tech stack: - **Package Manager:** [Yarn](https://yarnpkg.com/) -- **Framework:** [Next.js](https://nextjs.org/) - React framework for server-side rendering and static site generation. -- **Language:** [TypeScript](https://www.typescriptlang.org/) - Superset of JavaScript that adds static typing. -- **ORM:** [Prisma](https://www.prisma.io/) - Next-generation ORM for Node.js and TypeScript. -- **Authentication:** [Auth.js](https://authjs.dev/) (formerly NextAuth.js) - Authentication for Next.js. -- **Styling:** [Tailwind CSS](https://tailwindcss.com/) - A utility-first CSS framework. -- **UI Components:** [shadcn/ui](https://ui.shadcn.com/) - Re-usable components built using Radix UI and Tailwind CSS. -- **Containerization:** [Docker](https://www.docker.com/) (for planned self-hosting option) -- _(You can also list related tools here, e.g., ESLint, Prettier, testing libraries if you plan to use them)_ +- **Framework:** [Next.js](https://nextjs.org/) +- **Language:** [TypeScript](https://www.typescriptlang.org/) +- **ORM:** [Prisma](https://www.prisma.io/) +- **Authentication:** [Auth.js](https://authjs.dev/) +- **Styling:** [Tailwind CSS](https://tailwindcss.com/) +- **UI Components:** [shadcn/ui](https://ui.shadcn.com/) +- **Containerization:** [Docker](https://www.docker.com/) +- **API Docs:** [Swagger](https://swagger.io/) +- **React hook API client:** [orval](https://orval.dev/) -## Getting Started +## Development environment setup + +### Without Docker **Prerequisites:** -- Node.js: Version is continually upgraded. It's recommended to use the latest LTS or a recent stable version. (Check `.nvmrc` if available). -- Yarn: Version is continually upgraded. (Check `package.json` engines field if specified). -- A database supported by Prisma (e.g., PostgreSQL, MySQL, SQLite). Ensure your database server is running. +- **Node.js**: version 22+ +- **corepack**: enable using `corepack enable` -**Installation & Running Locally:** +**Installation & Running:** 1. **Clone the repository:** - - Using SSH: + - Using HTTPS: + ```bash + git clone https://git.dominikstahl.dev/DHBW-WE/MeetUp.git + ``` + - Or using SSH: ```bash git clone ssh://git@git.dominikstahl.dev/DHBW-WE/MeetUp.git ``` - - Or using HTTPS (recommended for most users): - ```bash - git clone [https://git.dominikstahl.dev/DHBW-WE/MeetUp.git](https://git.dominikstahl.dev/DHBW-WE/MeetUp.git) - ``` ```bash cd MeetUp ``` @@ -66,53 +82,44 @@ This project is built with a modern tech stack: yarn install ``` 3. **Set up environment variables:** - - You will need to create an `AUTH_SECRET`. You can generate one using the following command: - ```bash - npx auth secret - ``` - - Copy the `.env.example` file (if it exists) to `.env.local`. If not, create `.env.local`. - ```bash - # If .env.example exists: - cp .env.example .env.local - # Otherwise, create .env.local and add the following: - ``` - - Ensure the following environment variables are set in your `.env.local` file. Adjust `DATABASE_URL` for your specific database provider and credentials. + You will need to create an `AUTH_SECRET`. You can generate one using the following command: - ```env - # Database Connection String (Prisma) - # Example for PostgreSQL: DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=public" - DATABASE_URL="your_database_connection_string" + ```bash + npx auth secret + ``` - # Generated with npx auth secret - AUTH_SECRET="your_generated_auth_secret" + Add any additional needed environment variables into the generated `.env.local` file. + Example variables can be found in the `.env.example` file. The following variables are required: - # Authentik SSO Variables (if you are using this provider) - AUTH_AUTHENTIK_ID= - AUTH_AUTHENTIK_SECRET= - AUTH_AUTHENTIK_ISSUER= + ```env + # Generated with npx auth secret + AUTH_SECRET="your_generated_auth_secret" - # Base URL of your application - NEXT_PUBLIC_APP_URL="http://localhost:3000" - ``` + DATABASE_URL="file:./dev.db" + ``` 4. **Apply database migrations (Prisma):** - - Ensure your Prisma schema (`prisma/schema.prisma`) is defined. - - Setup/update the database with these commands: - ```bash - yarn prisma:generate - ``` - ```bash - yarn prisma:db:push - ``` - - Run the following command to apply migrations and generate Prisma Client: - ```bash - npx prisma migrate dev - # You might be prompted to name your first migration. - ``` + Set up/update the database with these commands: - Tipp: You can open the prisma database UI with `yarn prisma:studio` + ```bash + yarn prisma:generate + ``` -5. **Run the development server:** + ```bash + yarn prisma:db:push + ``` + + Tip: You can open the Prisma database UI with `yarn prisma:studio` + +5. **Generate needed TypeScript files:** + Generate the `swagger.json` file and the API client using: + + ```bash + yarn swagger:generate + yarn orval:generate + ``` + +6. **Run the development server:** ```bash yarn dev @@ -120,56 +127,64 @@ This project is built with a modern tech stack: Open [http://localhost:3000](http://localhost:3000) in your browser to see the application. - The test user for the application is: +### With Docker - ```bash - email: test@example.com - password: password - ``` +**Prerequisites:** -**Docker Development Environment:** +- **Docker** +- **Docker Compose** -- The docker development environment can be started with the following command: +**Running:** ```bash yarn dev_container ``` -**Self-Hosting with Docker (Planned):** +## Production Deployment using Docker -- A Docker image and `docker-compose.yml` file will be provided in the future to allow for easy self-hosting of the MeetUP application. This setup will also include database services. Instructions will be updated here once available. +The application can be hosted using the [Docker container](https://git.dominikstahl.dev/DHBW-WE/-/packages/container/meetup/main). + +There is an example Docker Compose file provided [here](https://git.dominikstahl.dev/DHBW-WE/MeetUp/src/branch/main/docker-compose.yml). ## Contributing -Contributions are welcome! If you'd like to contribute, please: +Contributions are welcome! If you'd like to contribute, please follow these steps: 1. Fork the repository. -2. Create a new branch (`git checkout -b /-action_name`). +2. Create a new branch: + + ```bash + git checkout -b /- + ``` + + - Example: `feat/42-add_login_form` + 3. Make your changes. -4. Commit your changes (`git commit -m ': add some feature'`). -5. Push to the branch (`git push origin /-action_name`). +4. Commit your changes using [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/): + - The commit message should be structured as follows: + + ``` + (optional scope): + ``` + + - Example: `feat(auth): add login form` + - Example: `fix(events): correct event time calculation` + - Example: `docs: update README with setup instructions` + + - Used types: + - `feat`: Feature added + - `fix`: Bug fix + - `test`: Add or modify tests + - `docs`: Documentation changes + - `chore`: Changes to non-code files (workflows, lock files, etc.) + - `refactor`: Code refactoring without changing functionality + - `style`: Code style changes (formatting, etc.) + - `revert`: Revert a previous commit + +5. Push to your branch: + ```bash + git push origin /- + ``` 6. Open a Pull Request against the `main` branch. -Possible actions are: - - *feat* -> Feature added - *fix* -> Fixed a bug - *test* -> Modified or added tests - *docs* -> Modified documentation - *chore* -> changes to non code files (workflows, lock files, ...) - *refactor* -> rewritten code without changing functionality - *style* -> code style (yarn format) - *revert* -> reverts a previous commit - -Please ensure your code adheres to the project's coding standards (e.g., run linters/formatters if configured) and that any database schema changes are accompanied by a Prisma migration. - ---- - -**(Optional Sections You Might Want to Add Later):** - -- **Screenshots/Demo:** (Once you have UI to show) -- **API Reference:** (If you plan to expose an API) -- **Detailed Deployment Guides:** (For various platforms beyond Docker) -- **License:** (e.g., MIT, GPL - Important for open source projects) -- **Contact:** (How to get in touch with the maintainers) -- **Acknowledgements:** (Credit to any libraries, inspirations, or contributors) +Please ensure your code adheres to the project's coding standards (run `yarn format`) and that any database schema changes are accompanied by a Prisma migration.