Created docs

CHANGELOG.md

@@ -7,10 +7,14 @@ frontend TypeScript client, `nextjs-frontend`.
     The backend and the frontend are versioned together, that is, they have the same version number.
     When you update the backend, you should also update the frontend to the same version.
 
+## 0.0.3 <small>April 23, 2025</small> {id="0.0.3"}
+
+- Created docs
+
 ## 0.0.2 <small>March 12, 2025</small> {id="0.0.2"}
 
 - Generate release draft using github actions
 
 ## 0.0.1 <small>March 12, 2025</small> {id="0.0.1"}
 
-- Initial release
+- Initial release

docs/CHANGELOG.md

@@ -0,0 +1 @@
+../CHANGELOG.md

docs/README.md

@@ -0,0 +1 @@
+../README.md

docs/additional-settings.md

@@ -0,0 +1,127 @@
+### Production-Ready Authentication & Dashboard features
+This template comes with a pre-configured authentication system and a simple dashboard interface, allowing you to start building your application with user management features immediately.
+
+### Hot Reload on development
+The project includes two hot reloads running the application, one for the backend and one for the frontend. These automatically restart local servers when they detect changes, ensuring that the application is always up to date without needing manual restarts.
+
+- The **backend hot reload** monitors changes to the backend code.
+- The **frontend hot reload** monitors changes to the frontend code and the `openapi.json` schema generated by the backend.
+
+### Manual Execution of Hot Reload Commands
+You can manually execute the same commands that the hot reloads call when they detect a change:
+
+1. To export the `openapi.json` schema:
+   ```bash
+   cd fastapi_backend && uv run python -m commands.generate_openapi_schema
+   ```
+   or using Docker:
+   ```bash
+   docker compose run --rm --no-deps -T backend uv run python -m commands.generate_openapi_schema
+   ```
+
+2. To generate the frontend client:
+   ```bash
+   cd nextjs-frontend && npm run generate-client
+   ```
+   or using Docker:
+   ```bash
+   docker compose run --rm --no-deps -T frontend npm run generate-client
+   ```
+
+### Testing
+To run the tests, you need to run the test database container:
+   ```bash
+   make docker-up-test-db
+   ```
+
+Then run the tests locally:
+   ```bash
+   make test-backend
+   make test-frontend
+   ```
+
+Or using Docker:
+   ```bash
+   make docker-test-backend
+   make docker-test-frontend
+   ```
+### Pre-Commit Setup
+To maintain code quality and consistency, the project includes two separate pre-commit configuration files:
+- `.pre-commit-config.yaml` is used to run pre-commit checks locally.
+- `.pre-commit-config.docker.yaml` is used to run pre-commit checks within Docker.
+
+### Installing and Activating Pre-Commit Hooks
+To activate pre-commit hooks, run the following commands for each configuration file:
+
+- **For the local configuration file**:
+  ```bash
+  pre-commit install -c .pre-commit-config.yaml
+  ```
+
+- **For the Docker configuration file**:
+  ```bash
+  pre-commit install -c .pre-commit-config.docker.yaml
+  ```
+
+### Localhost Email Server Setup
+
+To set up the email server locally, you need to start [MailHog](https://github.com/mailhog/MailHog) by running the following command:
+   ```bash
+   make docker-up-mailhog
+   ```
+
+- **Email client**: Access the email at `http://localhost:8025`.
+
+### Running Pre-Commit Checks
+To manually run the pre-commit checks on all files, use:
+
+```bash
+pre-commit run --all-files -c .pre-commit-config.yaml
+```
+
+or
+
+```bash
+pre-commit run --all-files -c .pre-commit-config.docker.yaml
+```
+
+### Updating Pre-Commit Hooks
+To update the hooks to their latest versions, run:
+
+```bash
+pre-commit autoupdate
+```
+### Alembic Database Migrations
+If you need to create a new Database Migration:
+   ```bash
+   make docker-db-schema migration_name="add users"
+   ```
+then apply the migration to the database:
+   ```bash
+   make docker-migrate-db
+   ```
+
+### GitHub Actions
+This project has a pre-configured GitHub Actions setup to enable CI/CD. The workflow configuration files are inside the .github/workflows directory. You can customize these workflows to suit your project's needs better.
+
+### Secrets Configuration
+For the workflows to function correctly, add the secret keys to your GitHub repository's settings. Navigate to Settings > Secrets and variables > Actions and add the following keys:
+```
+DATABASE_URL: The connection string for your primary database.
+TEST_DATABASE_URL: The connection string for your test database.
+ACCESS_SECRET_KEY: The secret key for access token generation.
+RESET_PASSWORD_SECRET_KEY: The secret key for reset password functionality.
+VERIFICATION_SECRET_KEY: The secret key for email or user verification.
+```
+
+## Makefile
+
+This project includes a `Makefile` that provides a set of commands to simplify everyday tasks such as starting the backend and frontend servers, running tests, building Docker containers, and more.
+
+### Available Commands
+
+You can see all available commands and their descriptions by running the following command in your terminal:
+
+```bash
+make help
+```

docs/contributing.md

@@ -0,0 +1,57 @@
+# Contributing
+
+We can always use your help to improve Next.js FastAPI Template! Please feel free to tackle existing [issues](https://github.com/vintasoftware/nextjs-fastapi-template/issues). If you have a new idea, please create a thread on [Discussions](https://github.com/vintasoftware/django-ai-assistant/discussions).
+
+Please follow this guide to learn more about how to develop and test the project locally, before opening a pull request.
+
+## Local Dev Setup
+
+### Clone the repo
+
+```bash
+git clone [email protected]:vintasoftware/nextjs-fastapi-template.git
+```
+
+Check the [Get Started](get-started.md#setup) page to complete the setup.
+
+
+## Install pre-commit hooks
+
+Check the [Additional Settings - Install pre-commit hooks](additional-settings.md#pre-commit-setup) section to complete the setup.
+
+
+It's critical to run the pre-commit hooks before pushing your code to follow the project's code style, and avoid linting errors.
+
+## Updating the OpenAPI schema
+
+It's critical to update the OpenAPI schema when you make changes to the FastAPI routes or related files:
+
+Check the [Additional Settings - Manual execution of hot reload commands](additional-settings.md#manual-execution-of-hot-reload-commands) section to run the command.
+
+## Tests
+
+Check the [Additional Settings - Testing](additional-settings.md#testing) section to run the tests.
+
+## Documentation
+
+We use [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) to generate the documentation from markdown files.
+Check the files in the `docs` directory.
+
+To run the documentation locally, you need to run:
+
+```bash
+uv run mkdocs serve
+```
+
+## Release
+
+!!! info
+    The backend and the frontend are versioned together, that is, they should have the same version number.
+
+To release and publish a new version, follow these steps:
+
+1. Update the version in `fastapi_backend/pyproject.toml`, `nextjs-frontend/package.json`.
+2. Update the changelog in `CHANGELOG.md`.
+3. Open a PR with the changes.
+4. Once the PR is merged, run the [Release GitHub Action](https://github.com/vintasoftware/nextjs-fastapi-template/actions/workflows/release.yml) to create a draft release.
+5. Review the draft release, ensure the description has at least the associated changelog entry, and publish it.

docs/deployment.md

@@ -0,0 +1,144 @@
+### Overview
+
+ Deploying to **Vercel** is supported, with dedicated buttons for the **Frontend** and **Backend** applications. Both require specific configurations during and after deployment to ensure proper functionality.
+
+---
+
+### Frontend Deployment
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvintasoftware%2Fnextjs-fastapi-template%2Ftree%2Fmain%2Fnextjs-frontend&env=API_BASE_URL&envDescription=The%20API_BASE_URL%20is%20the%20backend%20URL%20where%20the%20frontend%20sends%20requests.)
+
+- Click the **Frontend** button above to start the deployment process.  
+- During deployment, you will be prompted to set the `API_BASE_URL`. Use a placeholder value (e.g., `https://`) for now, as this will be updated with the backend URL later.  
+- Complete the deployment process [here](#post-deployment-configuration).
+
+### Backend Deployment
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvintasoftware%2Fnextjs-fastapi-template%2Ftree%2Fmain%2Ffastapi_backend&env=CORS_ORIGINS,ACCESS_SECRET_KEY,RESET_PASSWORD_SECRET_KEY,VERIFICATION_SECRET_KEY&stores=%5B%7B%22type%22%3A%22postgres%22%7D%5D)
+
+- Click the **Backend** button above to begin deployment.
+- First, set up the database. The connection is automatically configured, so follow the steps, and it should work by default.
+- During the deployment process, you will be prompted to configure the following environment variables:
+
+  - **CORS_ORIGINS**  
+    - Set this to `["*"]` initially to allow all origins. Later, you can update this with the frontend URL.
+
+  - **ACCESS_SECRET_KEY**, **RESET_PASSWORD_SECRET_KEY**, **VERIFICATION_SECRET_KEY**  
+    - During deployment, you can temporarily set these secret keys as plain strings (e.g., `examplekey`). However, you should generate secure keys and update them after the deployment in the **Post-Deployment Configuration** section.
+
+- Complete the deployment process [here](#post-deployment-configuration).
+
+
+## CI (GitHub Actions) Setup for Production Deployment
+
+We provide the **prod-backend-deploy.yml** and **prod-frontend-deploy.yml** files to enable continuous integration through Github Actions. To connect them to GitHub, simply move them to the .github/workflows/ directory.
+
+You can do it with the following commands:
+   ```bash
+    mv prod-backend-deploy.yml .github/workflows/prod-backend-deploy.yml
+    mv prod-frontend-deploy.yml .github/workflows/prod-frontend-deploy.yml
+   ```
+
+### Prerequisites
+1. **Create a Vercel Token**:  
+   - Generate your [Vercel Access Token](https://vercel.com/account/tokens).  
+   - Save the token as `VERCEL_TOKEN` in your GitHub secrets.
+
+2. **Install Vercel CLI**:  
+   ```bash
+   pnpm i -g vercel@latest
+   ```
+3. Authenticate your account.
+    ```bash
+   vercel login
+   ```
+### Database Creation (Required)
+
+   1. **Choosing a Database**
+      - You can use your database hosted on a different service or opt for the [Neon](https://neon.tech/docs/introduction) database, which integrates seamlessly with Vercel.
+
+   2. **Setting Up a Neon Database via Vercel**
+      - In the **Projects dashboard** page on Vercel, navigate to the **Storage** section.  
+      - Select the option to **Create a Database** to provision a Neon database.
+
+   3. **Configuring the Database URL**
+      - After creating the database, retrieve the **Database URL** provided by Neon.  
+      - Include this URL in your **Environment Variables** under `DATABASE_URL`.  
+
+   4. **Migrating the Database**
+      - The database migration will happen automatically during the GitHub action deployment, setting up the necessary tables and schema.
+### Frontend Setup
+
+1. Link the nextjs-frontend Project
+
+2. Navigate to the nextjs-frontend directory and run:
+   ```bash
+   cd nextjs-frontend
+   vercel link
+   ```
+3. Follow the prompts:
+   - Link to existing project? No
+   - Modify settings? No
+
+4. Save Project IDs and Add GitHub Secrets:
+  - Open `nextjs-frontend/.vercel/project.json` and add the following to your GitHub repository secrets:
+    - `projectId` → `VERCEL_PROJECT_ID_FRONTEND`
+    - `orgId` → `VERCEL_ORG_ID`
+
+### Backend Setup
+
+1. Link the fastapi_backend Project
+
+2. Navigate to the fastapi_backend directory and run:
+   ```bash
+   cd fastapi_backend
+   vercel link --local-config=vercel.prod.json
+   ```
+   - We use a specific configuration file to set the --local-config value.
+3. Follow the prompts:
+   - Link to existing project? No
+   - Modify settings? No
+
+4. Save Project IDs and Add GitHub Secrets:
+  - Open `fastapi_backend/.vercel/project.json` and add the following to your GitHub repository secrets:
+    - `projectId` → `VERCEL_PROJECT_ID_BACKEND`
+    - `orgId` → `VERCEL_ORG_ID` (Only in case you haven't added that before)
+
+### Notes
+- Once everything is set up, run `git push`, and the deployment will automatically occur.
+- Please ensure you complete the setup for both the frontend and backend separately.
+- Refer to the [Vercel CLI Documentation](https://vercel.com/docs/cli) for more details.
+- You can find the project_id into the vercel web project settings.
+- You can find the organization_id into the vercel web organization settings.
+
+## Post-Deployment Configuration
+
+### Frontend
+   - Navigate to the **Settings** page of the deployed frontend project.  
+   - Access the **Environment Variables** section.  
+   - Update the `API_BASE_URL` variable with the backend URL once the backend deployment is complete.
+
+### Backend
+   - Access the **Settings** page of the deployed backend project.  
+   - Navigate to the **Environment Variables** section and update the following variables with secure values:
+
+     - **CORS_ORIGINS**  
+       - Once the frontend is deployed, replace `["*"]` with the actual frontend URL.
+
+     - **ACCESS_SECRET_KEY**  
+       - Generate a secure key for API access and set it here.  
+
+     - **RESET_PASSWORD_SECRET_KEY**
+       - Generate a secure key for password reset functionality and set it.
+
+     - **VERIFICATION_SECRET_KEY**  
+       - Generate a secure key for user verification and configure it.
+
+   - For detailed instructions on setting these secret keys, please look at the section on [Setting up Environment Variables](get-started.md#setting-up-environment-variables).
+
+### Fluid serverless activation
+[Fluid](https://vercel.com/docs/functions/fluid-compute) is Vercel's new concurrency model for serverless functions, allowing them to handle multiple 
+requests per execution instead of spinning up a new instance for each request. This improves performance, 
+reduces cold starts, and optimizes resource usage, making serverless workloads more efficient.
+
+Follow this [guide](https://vercel.com/docs/functions/fluid-compute#how-to-enable-fluid-compute) to activate Fluid.