diff --git a/README.md b/README.md index afe124f3f..1adf27282 100644 --- a/README.md +++ b/README.md @@ -1,239 +1,100 @@ -# Full Stack FastAPI Template +# Tech4Dev AI Platform -Test -Coverage +## Getting Started -## Technology Stack and Features +### Prerequisite Services -- โšก [**FastAPI**](https://fastapi.tiangolo.com) for the Python backend API. - - ๐Ÿงฐ [SQLModel](https://sqlmodel.tiangolo.com) for the Python SQL database interactions (ORM). - - ๐Ÿ” [Pydantic](https://docs.pydantic.dev), used by FastAPI, for the data validation and settings management. - - ๐Ÿ’พ [PostgreSQL](https://www.postgresql.org) as the SQL database. -- ๐Ÿš€ [React](https://react.dev) for the frontend. - - ๐Ÿ’ƒ Using TypeScript, hooks, Vite, and other parts of a modern frontend stack. - - ๐ŸŽจ [Chakra UI](https://chakra-ui.com) for the frontend components. - - ๐Ÿค– An automatically generated frontend client. - - ๐Ÿงช [Playwright](https://playwright.dev) for End-to-End testing. - - ๐Ÿฆ‡ Dark mode support. -- ๐Ÿ‹ [Docker Compose](https://www.docker.com) for development and production. -- ๐Ÿ”’ Secure password hashing by default. -- ๐Ÿ”‘ JWT (JSON Web Token) authentication. -- ๐Ÿ“ซ Email based password recovery. -- โœ… Tests with [Pytest](https://pytest.org). -- ๐Ÿ“ž [Traefik](https://traefik.io) as a reverse proxy / load balancer. -- ๐Ÿšข Deployment instructions using Docker Compose, including how to set up a frontend Traefik proxy to handle automatic HTTPS certificates. -- ๐Ÿญ CI (continuous integration) and CD (continuous deployment) based on GitHub Actions. +Ensure PostgreSQL is installed and running on your machine. This guide assumes it is accessible on `localhost` via its default port. +Additionally, install either uv or poetry to manage dependencies. -### Dashboard Login +### Platform Setup -[![API docs](img/login.png)](https://github.com/fastapi/full-stack-fastapi-template) - -### Dashboard - Admin - -[![API docs](img/dashboard.png)](https://github.com/fastapi/full-stack-fastapi-template) - -### Dashboard - Create User - -[![API docs](img/dashboard-create.png)](https://github.com/fastapi/full-stack-fastapi-template) - -### Dashboard - Items - -[![API docs](img/dashboard-items.png)](https://github.com/fastapi/full-stack-fastapi-template) - -### Dashboard - User Settings - -[![API docs](img/dashboard-user-settings.png)](https://github.com/fastapi/full-stack-fastapi-template) - -### Dashboard - Dark Mode - -[![API docs](img/dashboard-dark.png)](https://github.com/fastapi/full-stack-fastapi-template) - -### Interactive API Documentation - -[![API docs](img/docs.png)](https://github.com/fastapi/full-stack-fastapi-template) - -## How To Use It - -You can **just fork or clone** this repository and use it as is. - -โœจ It just works. โœจ - -### How to Use a Private Repository - -If you want to have a private repository, GitHub won't allow you to simply fork it as it doesn't allow changing the visibility of forks. - -But you can do the following: - -- Create a new GitHub repo, for example `my-full-stack`. -- Clone this repository manually, set the name with the name of the project you want to use, for example `my-full-stack`: - -```bash -git clone git@github.com:fastapi/full-stack-fastapi-template.git my-full-stack -``` - -- Enter into the new directory: +Clone the repository: ```bash -cd my-full-stack +git clone https://github.com/ProjectTech4DevAI/ai-platform.git ``` -- Set the new origin to your new repository, copy it from the GitHub interface, for example: +### Environment Variables -```bash -git remote set-url origin git@github.com:octocat/my-full-stack.git -``` +Create a `.env` file in the root folder with the following content: -- Add this repo as another "remote" to allow you to get updates later: +```ini +PROJECT_NAME=ai-platform -```bash -git remote add upstream git@github.com:fastapi/full-stack-fastapi-template.git -``` +# Database Configuration +POSTGRES_USER=postgres_user +POSTGRES_PASSWORD=postgres_password +POSTGRES_DB=ai_database +POSTGRES_PORT=5432 +POSTGRES_SERVER=localhost -- Push the code to your new repository: +# API Keys +OPENAI_API_KEY="change if needed" -```bash -git push -u origin master +# Security & Auth +ENVIRONMENT=local +SECRET_KEY=$(openssl rand -hex 32) +FIRST_SUPERUSER=admin@example.com +FIRST_SUPERUSER_PASSWORD=admin@12345 ``` -### Update From the Original Template - -After cloning the repository, and after doing changes, you might want to get the latest changes from this original template. - -- Make sure you added the original repository as a remote, you can check it with: +To generate a secure `SECRET_KEY`, run: ```bash -git remote -v - -origin git@github.com:octocat/my-full-stack.git (fetch) -origin git@github.com:octocat/my-full-stack.git (push) -upstream git@github.com:fastapi/full-stack-fastapi-template.git (fetch) -upstream git@github.com:fastapi/full-stack-fastapi-template.git (push) +openssl rand -hex 32 ``` -- Pull the latest changes without merging: +### Virtual Environment Setup +Enter the backend directory ```bash -git pull --no-commit upstream master +cd ai-platform/backend ``` -This will download the latest changes from this template without committing them, that way you can check everything is right before committing. - -- If there are conflicts, solve them in your editor. - -- Once you are done, commit the changes: +Ensure you are using Python 3.13.2 or higher. Set up a virtual environment and install dependencies: ```bash -git merge --continue -``` - -### Configure - -You can then update configs in the `.env` files to customize your configurations. - -Before deploying it, make sure you change at least the values for: - -- `SECRET_KEY` -- `FIRST_SUPERUSER_PASSWORD` -- `POSTGRES_PASSWORD` - -You can (and should) pass these as environment variables from secrets. - -Read the [deployment.md](./deployment.md) docs for more details. - -### Generate Secret Keys - -Some environment variables in the `.env` file have a default value of `changethis`. +uv sync # If using uv +# OR +poetry install # If using Poetry -You have to change them with a secret key, to generate secret keys you can run the following command: - -```bash -python -c "import secrets; print(secrets.token_urlsafe(32))" +source .venv/bin/activate # Activate the .venv ``` -Copy the content and use that as password / secret key. And run that again to generate another secure key. - -## How To Use It - Alternative With Copier - -This repository also supports generating a new project using [Copier](https://copier.readthedocs.io). +### Database Migrations -It will copy all the files, ask you configuration questions, and update the `.env` files with your answers. +For database migrations, refer to the [backend migration guide](https://github.com/ProjectTech4DevAI/ai-platform/blob/main/backend/README.md#migrations). -### Install Copier +If you don't want to use migrations at all, uncomment the lines in the file at `./backend/app/core/db.py` that end in: -You can install Copier with: - -```bash -pip install copier +```python +from sqlmodel import SQLModel +SQLModel.metadata.create_all(engine) ``` -Or better, if you have [`pipx`](https://pipx.pypa.io/), you can run it with: +Then run: ```bash -pipx install copier +python app/initial_data.py ``` -**Note**: If you have `pipx`, installing copier is optional, you could run it directly. - -### Generate a Project With Copier - -Decide a name for your new project's directory, you will use it below. For example, `my-awesome-project`. +### Running the Backend -Go to the directory that will be the parent of your project, and run the command with your project's name: +Start the backend server using Uvicorn: ```bash -copier copy https://github.com/fastapi/full-stack-fastapi-template my-awesome-project --trust +uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload ``` -If you have `pipx` and you didn't install `copier`, you can run it directly: +Once running, you can access the API documentation: ```bash -pipx run copier copy https://github.com/fastapi/full-stack-fastapi-template my-awesome-project --trust +http://localhost:8000/docs ``` -**Note** the `--trust` option is necessary to be able to execute a [post-creation script](https://github.com/fastapi/full-stack-fastapi-template/blob/master/.copier/update_dotenv.py) that updates your `.env` files. - -### Input Variables - -Copier will ask you for some data, you might want to have at hand before generating the project. - -But don't worry, you can just update any of that in the `.env` files afterwards. - -The input variables, with their default values (some auto generated) are: - -- `project_name`: (default: `"FastAPI Project"`) The name of the project, shown to API users (in .env). -- `stack_name`: (default: `"fastapi-project"`) The name of the stack used for Docker Compose labels and project name (no spaces, no periods) (in .env). -- `secret_key`: (default: `"changethis"`) The secret key for the project, used for security, stored in .env, you can generate one with the method above. -- `first_superuser`: (default: `"admin@example.com"`) The email of the first superuser (in .env). -- `first_superuser_password`: (default: `"changethis"`) The password of the first superuser (in .env). -- `smtp_host`: (default: "") The SMTP server host to send emails, you can set it later in .env. -- `smtp_user`: (default: "") The SMTP server user to send emails, you can set it later in .env. -- `smtp_password`: (default: "") The SMTP server password to send emails, you can set it later in .env. -- `emails_from_email`: (default: `"info@example.com"`) The email account to send emails from, you can set it later in .env. -- `postgres_password`: (default: `"changethis"`) The password for the PostgreSQL database, stored in .env, you can generate one with the method above. -- `sentry_dsn`: (default: "") The DSN for Sentry, if you are using it, you can set it later in .env. - -## Backend Development - -Backend docs: [backend/README.md](./backend/README.md). - -## Frontend Development - -Frontend docs: [frontend/README.md](./frontend/README.md). - -## Deployment - -Deployment docs: [deployment.md](./deployment.md). - -## Development - -General development docs: [development.md](./development.md). - -This includes using Docker Compose, custom local domains, `.env` configurations, etc. - -## Release Notes - -Check the file [release-notes.md](./release-notes.md). +## Further Documentation -## License +Refer to the backend documentation for detailed setup and usage instructions: +[Backend README](https://github.com/ProjectTech4DevAI/ai-platform/blob/main/backend/README.md) -The Full Stack FastAPI Template is licensed under the terms of the MIT license.