diff --git a/README.md b/README.md index 6eb41e4a..db85a815 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,48 @@ # pass Culture Institutional -Welcome to the pass culture institutional project ! +[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=pass-culture_pass-culture-institutional&metric=code_smells)](https://sonarcloud.io/summary/overall?id=pass-culture_pass-culture-institutional) +[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=pass-culture_pass-culture-institutional&metric=coverage)](https://sonarcloud.io/summary/overall?id=pass-culture_pass-culture-institutional) +[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=pass-culture_pass-culture-institutional&metric=duplicated_lines_density)](https://sonarcloud.io/summary/overall?id=pass-culture_pass-culture-institutional) -This repo contains two important folders `public_website` (Next) and `content_management_system` (Strapi) for the institutional site. +Welcome to the **pass Culture Institutional** project! -This README contains general information that concerns the both folders. +This repository contains the following key components for the institutional site: -For more specific information: +- **`public_website`**: The frontend application built with **Next.js**. +- **`content_management_system`**: The backend powered by **Strapi**. -[Public website documentation](./public_website/README.md) +In addition, the project provides tools to streamline local development and testing by connecting to the **Strapi testing backend** behind Google Cloud IAP. -[Content management system documentation](./content_management_system/README.md) +This README provides general project information, scripts, and setup instructions. For detailed documentation on each part of the project: -[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=pass-culture_pass-culture-institutional&metric=code_smells)](https://sonarcloud.io/summary/overall?id=pass-culture_pass-culture-institutional) -[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=pass-culture_pass-culture-institutional&metric=coverage)](https://sonarcloud.io/summary/overall?id=pass-culture_pass-culture-institutional) -[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=pass-culture_pass-culture-institutional&metric=duplicated_lines_density)](https://sonarcloud.io/summary/overall?id=pass-culture_pass-culture-institutional) +- [Public Website Documentation](./public_website/README.md) +- [Content Management System Documentation](./content_management_system/README.md) +- [Strapi Testing Proxy Documentation](./nginx-strapi-testing-proxy/README.md) + +--- + +## Table of Contents + +- [pass Culture Institutional](#pass-culture-institutional) + - [Table of Contents](#table-of-contents) + - [Requirements](#requirements) + - [Start the project](#start-the-project) + - [Local Database](#local-database) + - [Access the Strapi Testing Backend](#access-the-strapi-testing-backend) + - [Key Features:](#key-features) + - [Quick Start:](#quick-start) + - [Project Scripts](#project-scripts) + - [Project Scripts](#project-scripts-1) + - [Project Scripts](#project-scripts-2) + - [Testing](#testing) + - [Public website](#public-website) + - [Content management system](#content-management-system) + - [Sharing types between the front \& back](#sharing-types-between-the-front--back) + - [Why aren't there any unit test on the CMS?](#why-arent-there-any-unit-test-on-the-cms) + - [PR title format 🤖](#pr-title-format-) + - [Why](#why) + - [About squashing the PR commits](#about-squashing-the-pr-commits) + - [Key points](#key-points) ## Requirements @@ -40,27 +68,57 @@ If you want to run the content_management_system locally, you need to install Po More information on how to setup here: [content_management_system documentation](./content_management_system/README.md) +## Access the Strapi Testing Backend + +To connect your local frontend to the Strapi testing backend (secured behind Google Cloud IAP) and transfer data to your local database, refer to the detailed documentation in the [Strapi Testing Proxy](./nginx-strapi-testing-proxy/README.md). + +### Key Features: + +1. **Proxy Setup**: Allows your local frontend to communicate with the Strapi testing server. +2. **Data Transfer**: Synchronize the testing environment data into your local database for seamless development and debugging. + +### Quick Start: + +1. Follow the setup instructions in the [Strapi Testing Proxy README](./nginx-strapi-testing-proxy/README.md). +2. Use the available scripts: + - `yarn proxy:testing`: Start the proxy server. + - `yarn proxy:transfer`: Transfer data from the Strapi testing backend to your local database. +3. Point your frontend (`public_website`) to the local proxy: + ```env + NEXT_PUBLIC_STRAPI_API_URL=http://localhost:8080 + ``` + +For detailed steps and troubleshooting, see the full [Strapi Testing Proxy documentation](./nginx-strapi-testing-proxy/README.md). + ## Project Scripts Before you can use the scripts, ensure you have `Yarn` installed on your system. The project includes several scripts to simplify development and setup: -- `yarn public_website`: Start the public_website development server. -- `yarn content_management_system`: Start the content_management_system development server. -- `yarn clear`: Remove temporary files and caches in the public_website directory. -- `yarn setup:public_website`: Install the public_website dependencies. -- `yarn setup:content_management_system`: Install the content_management_system dependencies. -- `yarn setup`: Install the public_website and content_management_system project dependencies. -- `yarn dev`: Run during development. It clears caches, and starts the public_website and content_management_system servers. -- `yarn audit:all`: Test all the vulnerabilities packages. -- `yarn test:deadcode`: Test both public_website and content_management_system dead code. -- `yarn test:deadcode:update`: Update the public_website and content_management_system dead code snapshots. -- `yarn test:lint`: Test both public_website and content_management_system linting. -- `yarn test:types`: Test both public_website and content_management_system typing. -- `yarn proxy:testing`: Launches the testing proxy server. This script navigates to the nginx-strapi-testing-proxy directory and runs the [launch-testing-proxy.sh](./nginx-strapi-testing-proxy/launch-testing-proxy.sh) script. -- `yarn proxy:testing:infinite`: Launches the testing proxy server in infinite mode. This script runs [launch-testing-proxy.sh](./nginx-strapi-testing-proxy/launch-testing-proxy-sh) with the -l true option to continuously monitor and regenerate tokens. -- `yarn proxy:testing:stop`: Stops the currently running testing proxy server by stopping the nginx-strapi-testing-proxy Docker container. -- `yarn proxy:transfer`: Executes the transfer script to sync data from the testing proxy. This script navigates to the nginx-strapi-testing-proxy directory and runs [transfer-from-testing.sh](./nginx-strapi-testing-proxy/transfer-from-testing.sh). +## Project Scripts + +The project includes several useful scripts for development, testing, and proxy setup: + +## Project Scripts + +| **Command** | **Description** | +| -------------------------------------- | ------------------------------------------------------------------------------- | +| `yarn setup` | Install dependencies for both `public_website` and `content_management_system`. | +| `yarn dev` | Start both the frontend and backend servers for development. | +| `yarn public_website` | Start the `public_website` development server. | +| `yarn content_management_system` | Start the `content_management_system` development server. | +| `yarn clear` | Remove temporary files and caches in the `public_website` directory. | +| `yarn setup:public_website` | Install dependencies for the `public_website` only. | +| `yarn setup:content_management_system` | Install dependencies for the `content_management_system` only. | +| `yarn audit:all` | Check for vulnerabilities in project dependencies. | +| `yarn test:deadcode` | Detect unused (dead) code in both projects. | +| `yarn test:deadcode:update` | Update snapshots for dead code detection. | +| `yarn test:lint` | Run linting for both frontend and backend. | +| `yarn test:types` | Verify TypeScript types across the project. | +| `yarn proxy:testing` | Start the testing proxy server to connect to the Strapi testing backend. | +| `yarn proxy:testing:infinite` | Run the proxy server in infinite mode with automatic JWT regeneration. | +| `yarn proxy:testing:stop` | Stop the currently running proxy server. | +| `yarn proxy:transfer` | Transfer data from the Strapi testing backend to your local database. | ## Testing diff --git a/nginx-strapi-testing-proxy/README.md b/nginx-strapi-testing-proxy/README.md index 52e9af15..961c84db 100644 --- a/nginx-strapi-testing-proxy/README.md +++ b/nginx-strapi-testing-proxy/README.md @@ -1,43 +1,189 @@ -# Strapi Testing Environment +# Strapi Testing Proxy -To connect the project to the Strapi testing environment, ensure the testing proxy is correctly set up and running. You can use the following commands: +This repository provides tools to facilitate local development by accessing the **Strapi testing backend**, which is secured behind Google Cloud IAP (Identity-Aware Proxy). -- Start the testing proxy server: +The purpose of this repository is twofold: -```bash -yarn proxy:testing -``` +1. **Proxy Access**: Use the provided tools to set up a proxy that allows your local frontend (e.g., `public_website`) to connect to the Strapi testing server available at [this address](https://siteinstit-cms.testing.passculture.team/). +2. **Data Transfer**: Synchronize data from the testing backend to your local database for development and testing purposes. -This launches the testing proxy server to connect to Strapi. +This setup ensures seamless access to the testing backend for development and allows you to replicate real data locally for debugging and validation. -- Run the proxy server in infinite mode: +--- -```bash -yarn proxy:testing:infinite -``` +## Table of Contents -This mode ensures the proxy regenerates the JWT token automatically every hour to avoid token expiration issues. +- [Strapi Testing Proxy](#strapi-testing-proxy) + - [Table of Contents](#table-of-contents) + - [Setup and Configuration](#setup-and-configuration) + - [Prerequisites](#prerequisites) + - [Proxy Configuration](#proxy-configuration) + - [Running the Proxy Server](#running-the-proxy-server) + - [Starting the Proxy](#starting-the-proxy) + - [Infinite Mode](#infinite-mode) + - [Stopping the Proxy](#stopping-the-proxy) + - [Transferring Data to Your Local Database](#transferring-data-to-your-local-database) + - [Prerequisites](#prerequisites-1) + - [Data Transfer Steps](#data-transfer-steps) + - [Launch Frontend with Testing Backend](#launch-frontend-with-testing-backend) + - [Available Commands](#available-commands) + - [Common Issues and Troubleshooting](#common-issues-and-troubleshooting) + - [1. Logs and Debugging](#1-logs-and-debugging) + - [2. Token Expiration](#2-token-expiration) + - [3. Proxy Not Starting](#3-proxy-not-starting) + - [Additional Notes](#additional-notes) -- Stop the testing proxy server: +--- -```bash -yarn proxy:testing:stop -``` +## Setup and Configuration -This stops the currently running proxy server. +Before running the proxy server, ensure your environment is properly configured: -### Common Issues and Considerations +### Prerequisites -- **Token Expiration**: JWT tokens for the Strapi testing environment expire after 1 hour. If you encounter access issues due to expired tokens, use the infinite mode to regenerate tokens automatically. +1. **Google Cloud SDK** -- **Data Consistency**: The testing environment may contain test-specific data that differs from the local database. Always validate the data before running tests or debugging features. + - Install the [Google Cloud SDK](https://cloud.google.com/sdk/docs/install) and configure it with your project: + ```bash + gcloud auth application-default login + gcloud config set project passculture-cls-metier-ehp + ``` -- **Data Transfer**: You can transfer data from the testing environment to your local setup (excluding files) using: +2. **iap-local-authentication** + - Clone the [iap-local-authentication](https://github.com/pass-culture/iap-local-authentication) repository at the same directory level as this project: + ```bash + git clone https://github.com/pass-culture/iap-local-authentication.git + ``` +3. **Python** + - Python3 is required to run iap-local-authentication -```bash -yarn proxy:transfer -``` +### Proxy Configuration -This ensures your local instance is synced with the testing environment. +1. Launch the testing proxy server: -By following these steps, you can easily point to the Strapi testing server, manage JWT token lifecycles, and handle potential data inconsistencies during development and testing. + ```bash + yarn proxy:testing + ``` + + - This will open a browser window to log in via Google Cloud IAP. + - Once logged in, a Docker container will start, and the proxy will run at `http://localhost:8080`. + +2. Optional: Run the proxy server in **infinite mode** (to avoid token expiration every hour): + ```bash + yarn proxy:testing:infinite + ``` + +--- + +## Running the Proxy Server + +### Starting the Proxy + +- Run the following command to start the proxy: + ```bash + yarn proxy:testing + ``` + - The proxy will authenticate via Google Cloud IAP and start at `http://localhost:8080`. + +### Infinite Mode + +- To automatically regenerate the JWT token every hour, run instead: + ```bash + yarn proxy:testing:infinite + ``` + +### Stopping the Proxy + +- Stop the proxy server: + ```bash + yarn proxy:testing:stop + ``` + +--- + +## Transferring Data to Your Local Database + +Follow these steps to transfer data from the Strapi testing environment to your local database: + +### Prerequisites + +1. **Ensure your local database is running** and accessible. Refer to the instructions in the [content management system README](../content_management_system/README.md). + +### Data Transfer Steps + +1. Go to the [Strapi admin panel](https://siteinstit-cms.testing.passculture.team/admin/auth/login) of the remote testing environment. +2. Navigate to **Settings > Transfer Tokens**. +3. Create a **new transfer token** (Pull mode only) and copy it for later. + +4. Run the transfer script: + + ```bash + yarn proxy:transfer + ``` + +5. Enter the transfer token when prompted. +6. The script will sync the data to your local database. + +--- + +## Launch Frontend with Testing Backend + +To connect your frontend project (e.g., `public_website`) to the Strapi testing backend: + +1. Ensure the proxy is running at `http://localhost:8080`. +2. Update the `.env` file in your frontend project with the following variable: + ```env + NEXT_PUBLIC_STRAPI_API_URL=http://localhost:8080 + ``` +3. Restart your frontend development server: + ```bash + yarn dev + ``` + +Your frontend should now point to the Strapi testing backend via the proxy. + +--- + +## Available Commands + +All commands are available in the `package.json` file at **the root** of the project. + +| **Command** | **Description** | +| ----------------------------- | ------------------------------------------------------------ | +| `yarn proxy:testing` | Starts the proxy server to connect to Strapi. | +| `yarn proxy:testing:infinite` | Starts the proxy server in infinite mode (auto-refresh JWT). | +| `yarn proxy:testing:stop` | Stops the currently running proxy server. | +| `yarn proxy:transfer` | Transfers data from the remote testing server to local DB. | + +--- + +## Common Issues and Troubleshooting + +### 1. Logs and Debugging + +- If issues arise, check the logs for errors: + ```bash + docker logs + ``` + +### 2. Token Expiration + +- JWT tokens expire after 1 hour. Use **infinite mode** to avoid manual regeneration: + ```bash + yarn proxy:testing:infinite + ``` + +### 3. Proxy Not Starting + +- Ensure Google Cloud SDK is installed and authenticated: + ```bash + gcloud auth application-default login + ``` +- Verify Docker is running and accessible. + +--- + +## Additional Notes + +- This proxy setup is specifically for Strapi testing environment. +- Ensure your environment variables and tokens are handled securely to avoid accidental leaks.