AURA Catcher

Un site web pour trouver tous les panneaux "La Région aide..." autour de chez vous !!

Vous pouvez aussi y créer vos propres panneaux personnalisés !

Il s'agit encore d'une version brouillon, toute aide est la bienvenue pour contribuer au projet ! La prochaine version est en construction sur la branche dev.

Project Structure

The project is organized into two main components:

• Frontend (frontend/): A React application built with Vite, providing the user interface for the map and sign generator.
• Backend (backend/): A Node.js and Express server that handles API requests, database interactions (MariaDB), and file storage.

Key Files:

• backend/src/types.ts: Defines the shared data types used by both the frontend and backend, ensuring type safety across the application.
• nginx.conf and vite.config.ts: Handle routing and request proxying logic for production and development respectively.

Prerequisites

For Production (Docker)

• Docker
• Docker Compose

For Development (Manual)

• Node.js (LTS recommended)
• npm
• MariaDB

Development Setup

Follow these steps to set up the application locally:

1. Configuration

1. Navigate to the backend/ directory.
2. Copy the example environment file:

   cp .env.example .env

3. Edit .env and fill in your MariaDB database credentials.

2. Database Setup

Start your local MariaDB server and create the database. You can use the CLI:

mariadb -u root -p

CREATE DATABASE aura_catcher;

Note: Ensure the username and database name match what you defined in backend/.env.

3. Installation

Install dependencies for the root, frontend, and backend workspaces:

npm run install:all

4. Running the App

Start both the backend and frontend development servers concurrently:

npm run dev

• Frontend: http://localhost:5174
• Backend: http://localhost:3000

5. Linting

To check for code quality issues across the project:

npm run lint

Production Setup (Docker)

To deploy the entire stack (Frontend, Backend, and MariaDB) using Docker:

1. Build and Start: Run the following command from the project root:

docker compose --env-file ./backend/.env up --build

2. Access the Application:
   • Frontend: http://localhost:4657
   • Backend: Not directly exposed (accessible internally by the frontend via Nginx).

Data Management

Database Backups

The database is automatically backed up using the Ofelia job scheduler container. By default, backups are created every day at midnight and kept for 7 days.

Where to find backups: Backups are stored as .sql files on your host machine in the data/db_backups/ directory.

How to change periodicity and length (retention): You can configure the backup schedule and retention by editing the ofelia/config.ini file:

• schedule = @midnight: Change this to alter the frequency (e.g., @every 12h, or cron syntax 0 0 2 * * * for 2 AM).
• mtime +7: Change the +7 in the command line to alter how many days backups are kept before deletion.

How to restore a backup: To restore a specific backup, use the following command from the project root. Make sure to replace db_YYYY-MM-DD_HH-MM-SS.sql with the actual filename of your backup.

docker exec -i aura-catcher-mariadb sh -c 'mariadb -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' < data/db_backups/db_YYYY-MM-DD_HH-MM-SS.sql

Warning: Restoring will overwrite the current database data with the data from the backup.

Accessing Logs

To view the backend activity logs (panel creation events) when running with Docker:

View real-time logs (console):

docker compose logs -f aura-catcher-backend

View the persistent log file:

docker compose exec aura-catcher-backend cat logs/activity.log

Roadmap / TODO

• Generator: fix the small issue with the generator (responsive layout, text)
• Share sign: add a share button (https://developer.mozilla.org/en-US/docs/Web/API/Web_Share_API)
• Stats: Add a stats page to display the number of signs, photos, leaderboard.
• Authentication: Implement user accounts and granular permissions.
• Modify: Allow users to modify signs and photos
• Admin: Add an admin page to manage new signs and photos.
• Search: Add a search bar to search for signs by name, description, etc.
• Bulk Import/Export: Allow users to export data to CSV/JSON
• Closest sign: display the distance and direction of the closest sign
• Beautiful photos: nice pictures of signs or bus / camionette / etc