From 28c61a85484acbe96e163808263699b8255bb415 Mon Sep 17 00:00:00 2001 From: resist15 Date: Mon, 12 Aug 2024 13:07:08 +0530 Subject: [PATCH] SocialPulse: Add Initial README Change-Id: Iaed26984654f33616aa2fb39172c8c5be865f59d --- CONTRIBUTING.md | 54 +++++++++++++++++++++ README.md | 124 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 178 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..735bfff --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,54 @@ +# Contributing to SocialPulse + +First off, thank you for considering contributing to SocialPulse! Your help is essential for making this project better. + +## How to Contribute + +### 1. Fork the Repository + +Start by forking the repository on GitHub. This will create a copy of the repository in your account. + +### 2. Clone the Repository + +Clone the forked repository to your local machine: + +```bash +git clone https://github.com/your-username/SocialPulse.git +cd SocialPulse +``` +### 3. Create a Branch +Create a new branch for your feature or bug fix: +```bash +git checkout -b feature/your-feature-name + +``` +### 4. Make Changes +Make your changes to the codebase. Please ensure that your code follows the existing coding style. +### 5. Write Tests +If applicable, write tests for your new feature or bug fix. We use pytest for testing, and all tests are located in the tests/ directory. +Run tests locally to ensure everything works: + +```bash +pytest +``` +### 6. Commit Your Changes +Commit your changes with a meaningful commit message: +```bash +git add . +git commit -m "Add feature/your-feature-name" +``` +### 7. Push to GitHub +Push your changes to your forked repository: +```bash +git push origin feature/your-feature-name +``` +### 8. Submit a Pull Request +Go to the original repository and submit a pull request from your forked repository. +In your pull request description, please include the following information: + +- A brief explanation of your changes. +- Any related issue numbers (e.g., "Fixes #123"). +- How your changes were tested. +### 9. Code Review +Your pull request will be reviewed by the project maintainers. You may be asked to make additional changes before your pull request is merged. + diff --git a/README.md b/README.md new file mode 100644 index 0000000..1c169f4 --- /dev/null +++ b/README.md @@ -0,0 +1,124 @@ +# SocialPulse + +SocialPulse is a robust social media backend built with FastAPI, utilizing Docker and PostgreSQL for seamless deployment and database management. It provides essential features for user authentication, JWT-based security, and efficient post management. The project also includes automated testing with pytest, ensuring code reliability and quality. SocialPulse is a solid foundation for building social media applications, with easy setup and comprehensive features. + +## Table of Contents + +- [Features](#features) +- [Installation](#installation) +- [Usage](#usage) +- [API Endpoints](#api-endpoints) +- [Configuration](#configuration) +- [Contributing](#contributing) +- [License](#license) + +## Features + +- **User Authentication:** Secure user login with password hashing. +- **JWT Authentication:** Provides JWT token generation with expiration for secure API access. +- **Post Management:** Create, fetch single posts, update posts, delete posts, like posts, and fetch all posts. +- **Docker Support:** Easily set up and run the project using Docker Compose. +- **Environment Configuration:** Example environment files (`.env.example` and `.env.postgres.example`) to help you get started quickly. + +## Installation + +### Prerequisites + +- Docker +- Docker Compose + +### Steps + +1. Clone the repository: + + ```bash + git clone https://github.com/resist15/SocialPulse.git + cd SocialPulse + ``` + +2. Copy the example environment variable files and configure them as needed: + + ```bash + cp .env.example .env + cp .env.postgres.example .env.postgres + ``` + +3. Build and run the containers using Docker Compose: + + ```bash + docker-compose up --build + ``` + + This will start the FastAPI application along with any required services like the database. + +4. The application will be running at `http://127.0.0.1:8000`. + +## Usage + +### Access the API + +1. **Interactive API Documentation:** + + - Open your browser and navigate to `http://127.0.0.1:8000/docs` for the Swagger UI. + - Or go to `http://127.0.0.1:8000/redoc` for ReDoc. + +2. **Test the API Endpoints:** + + You can use the interactive documentation to test the endpoints directly from your browser. + +## API Endpoints + +- **Authentication:** + - `POST /auth/`: Authenticate a user and receive a JWT token. +- **User Management:** + - `POST /users/`: Create a new user. + - `GET /users/{id}/`: Fetch the current user's details. +- **Post Management:** + - `POST /posts/`: Create a new post. + - `GET /posts/{id}`: Fetch a single post by ID. + - `GET /posts/`: Fetch all posts. + - `PUT /posts/{id}`: Update post. + - `DEL /posts/{id}`: Delete post. + - `POST /like/`: Like a post. + +### Example Request: User Login + +```bash +curl -X 'POST' \ + 'http://127.0.0.1:8000/auth/' \ + -H 'Content-Type: application/json' \ + -d '{ + "username": "user1", + "password": "password123" +}' +``` +### Example Response: JWT Token + +``` +{ + "access_token": "your.jwt.token", + "token_type": "bearer" +} +``` +## Configuration + +The application uses environment variables for configuration. Example environment variable files have been provided: + +- **`.env.example`**: General environment variables for the application. +- **`.env.postgres.example`**: Environment variables specific to PostgreSQL configuration. + +To use them: + +1. Copy the example files to `.env` and `.env.postgres`. +2. Edit the files to include your specific configuration details, such as database credentials, JWT secret keys, etc. + +Docker Compose will automatically load these environment variables. + +## Contributing + +Contributions are welcome! Please read the [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute to this project. + +## License + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. +