Skip to content

README.md

Latest commit

 

History

History
145 lines (104 loc) · 3.18 KB

README.md

File metadata and controls

145 lines (104 loc) · 3.18 KB

Shared Planner

A collaborative planning application with calendar integration and email notifications.

Features

  • User management with admin capabilities
  • Shop and reservation management
  • Email notifications and reminders
  • Calendar integration (ICS format)
  • Multi-language support (English and French)
  • Responsive web interface

Project Structure

  • shared_planner/ - Python backend

    • api/ - REST API endpoints
    • db/ - Database models and operations
    • ics.py - Calendar integration
    • mailer_daemon.py - Email notification system
    • week.py - Week management logic
    • templates/ - Email templates

  • web/ - Vue.js frontend application

    • Built with Vue 3 + TypeScript + Vite
    • PrimeVue component library

Requirements

  • Python 3.12+
  • Node.js 16+
  • SQLite3 database
  • SMTP server for emails (e.g. OVH)

Setup

Backend Setup

  1. Install uv (if not already installed):
curl -LsSf https://astral.sh/uv/install.sh | sh
  1. Install dependencies:
uv sync
  1. Set up environment variables:
cp .env.example .env  # If an example exists, otherwise create .env
nano .env

Frontend Setup

  1. Navigate to the web directory:
cd web
  1. Install dependencies:
npm install

Development

Using Docker (Recommended)

This project supports hot-reloading for both the UI and backend using Docker Compose.

  1. Start the services:

    docker compose up --build

  2. (Optional) Enable Docker Compose Watch for automatic sync:

    docker compose watch

The Backend will be available at http://localhost:8000 and the UI at http://localhost:5173.

Manual Running

Backend:

uv run python -m shared_planner

Frontend:

cd web
npm run dev

Production

Using Docker

The production setup bundles the UI and Backend into a single optimized container.

  1. Build and run: 
    docker compose -f docker-compose.prod.yml up --build -d

The application will be available at http://localhost:8000.

Manual Build

  1. Build the frontend:
cd web
npm run build
  1. Run the backend with a production server:
uv run gunicorn -w 4 -k uvicorn.workers.UvicornWorker shared_planner.api:app --bind 0.0.0.0:8000

Configuration

Required Settings

The following settings must be configured in the admin interface:

  • base_domain: The domain name of your server (e.g., https://example.com)
  • admin_mail: Email address for admin notifications
  • mail_from: Email address used as the sender for notifications

Optional Settings

  • block_all_emails: Disable all email notifications (useful for testing)
  • email_notification_before: Hours before a reservation to send a reminder
  • cleanup_reminders_days: Days to keep reminders before cleanup
  • cleanup_notifications_days: Days to keep notifications before cleanup
  • token_validity: Hours before login tokens expire

For a complete list of settings and their descriptions, head to the Admin > Server Settings page where you will be able to modify them and find a detailed description of each setting.

License

This project is licensed under the MIT License. See the LICENSE file for details.