diff --git a/README.md b/README.md new file mode 100644 index 0000000..bb21855 --- /dev/null +++ b/README.md @@ -0,0 +1,325 @@ +# Compass NGO Management System + +[![GitHub release (latest by date including pre-releases)](https://img.shields.io/github/v/release/Merge-Labs/Compass?include_prereleases)](https://github.com/Merge-Labs/Compass/releases) +[![GitHub last commit](https://img.shields.io/github/last-commit/Merge-Labs/Compass)](https://github.com/Merge-Labs/Compass/commits) +[![GitHub issues](https://img.shields.io/github/issues-raw/Merge-Labs/Compass)](https://github.com/Merge-Labs/Compass/issues) +[![GitHub pull requests](https://img.shields.io/github/issues-pr/Merge-Labs/Compass)](https://github.com/Merge-Labs/Compass/pulls) +![GitHub commit activity](https://img.shields.io/github/commit-activity/m/Merge-Labs/Compass) + +> **Note:** This project is archived. Compass v2 is currently being built by the core team in a private repository. If you are interested in contributing or learning more about Compass v2, please contact [wahome@nisria.co](mailto:wahome@nisria.co). + +**Live Demo:** +- Frontend: [dira.manassehgitau.com](https://dira.manassehgitau.com) +- Backend API: [api-compass.manassehgitau.com/swagger](https://api-compass.manassehgitau.com/swagger) + +**Compass** is a comprehensive NGO Management System designed to streamline operations for non-profit organizations. Built with Django REST Framework for the backend and React with Tailwind CSS for the frontend, Compass provides role-based access control, grant management, document handling, and analytics for efficient NGO operations. + +The system supports multiple user roles including Super Admins, Admins, Management Leads, and Grant Officers, each with tailored dashboards and permissions to manage grants, documents, divisions, programs, and organizational workflows. + +# Quick Start Demo + +Compass provides an intuitive interface for managing your NGO's operations: + +- **Role-Based Dashboards**: Customized views for Super Admins, Admins, Management Leads, and Grant Officers +- **Grant Management**: Track grant applications, deadlines, and progress +- **Document Management**: Upload, organize, and access important documents +- **Division & Program Management**: Organize your NGO's structure and programs +- **Analytics**: Visualize key metrics and performance indicators +- **Task Management**: Assign and track tasks across your organization +- **Notifications**: Stay updated with email notifications for important events + +# Table of Contents + +- [Compass NGO Management System](#compass-ngo-management-system) +- [Quick Start Demo](#quick-start-demo) +- [Table of Contents](#table-of-contents) +- [Installation](#installation) + - [Prerequisites](#prerequisites) + - [Backend Setup (Django)](#backend-setup-django) + - [Frontend Setup (React)](#frontend-setup-react) +- [Usage](#usage) + - [User Roles](#user-roles) + - [Key Features](#key-features) +- [Development](#development) + - [Project Structure](#project-structure) + - [Running in Development Mode](#running-in-development-mode) + - [Running Tests](#running-tests) +- [Deployment](#deployment) +- [Contribute](#contribute) +- [License](#license) + +# Installation +[(Back to top)](#table-of-contents) + +## Prerequisites + +Before you begin, ensure you have the following installed: + +- **Python** 3.9 or higher +- **Node.js** 18 or higher +- **npm** or **yarn** +- **PostgreSQL** (recommended for production) or SQLite (for development) +- **Git** + +## Backend Setup (Django) + +1. Clone the repository: + +```shell +git clone https://github.com/Merge-Labs/Compass.git +cd Compass/nisria-backend +``` + +2. Create and activate a virtual environment: + +```shell +python -m venv venv +source venv/bin/activate # On Windows: venv\Scripts\activate +``` + +3. Install dependencies: + +```shell +pip install -r requirements.txt +``` + +4. Set up environment variables: + +```shell +cp env.example .env +# Edit .env with your configuration (database, secret key, etc.) +``` + +5. Run migrations: + +```shell +python manage.py migrate +``` + +6. Create a superuser: + +```shell +python manage.py createsuperuser +``` + +7. Start the development server: + +```shell +python manage.py runserver +``` + +The backend API will be available at `http://localhost:8000` + +## Frontend Setup (React) + +1. Navigate to the frontend directory: + +```shell +cd ../nisria-frontend +``` + +2. Install dependencies: + +```shell +npm install +``` + +3. Start the development server: + +```shell +npm run dev +``` + +The frontend application will be available at `http://localhost:5173` + +# Usage +[(Back to top)](#table-of-contents) + +## User Roles + +Compass supports four distinct user roles with different permissions: + +| Role | Description | +| --------------- | -------------------------------------------------------------------------------- | +| **Super Admin** | Full access. Can manage users, programs, grants, documents, and verify deletions | +| **Admin** | Can upload, view, and manage documents and programs | +| **Management Lead** | Oversees Compass operations and grants | +| **Grant Officer** | Sources and manages grants, updates deadlines | + +## Key Features + +### Grant Management +- Create, update, and track grants +- Set deadlines and milestones +- Monitor grant progress and status +- Automated deadline reminders + +### Document Management +- Upload and organize documents +- Categorize documents by type (budgets, reports, proposals) +- Secure document storage +- Role-based access to documents + +### Division & Program Management +- Manage organizational divisions (e.g., Nisria, Maisha) +- Create and oversee programs within divisions +- Track program metrics and outcomes + +### Analytics & Reporting +- Visual dashboards for key metrics +- Grant performance analytics +- Program success tracking +- Customizable reports + +### Task Management +- Create and assign tasks to team members +- Set priorities and deadlines +- Track task completion +- Email notifications for task updates + +# Development +[(Back to top)](#table-of-contents) + +## Project Structure + +``` +Compass/ +│ +├── nisria-backend/ # Django REST Framework backend +│ ├── accounts/ # User management and authentication +│ ├── grants/ # Grant management logic +│ ├── documents/ # Document handling +│ ├── divisions/ # Divisions and programs +│ ├── analytics/ # Analytics and reporting +│ ├── task_manager/ # Task management +│ ├── notifications/ # Email notifications +│ ├── compass/ # Django project settings +│ └── manage.py +│ +├── nisria-frontend/ # React + Tailwind CSS frontend +│ ├── src/ +│ │ ├── assets/ # Static assets +│ │ ├── components/ # Reusable UI components +│ │ ├── pages/ # Page components +│ │ ├── context/ # React Context (Auth, Theme) +│ │ ├── routes/ # Routing and protected routes +│ │ └── services/ # API service layer +│ ├── public/ +│ └── package.json +│ +└── documents/ # Project documentation +``` + +## Running in Development Mode + +### Backend Development + +```shell +cd nisria-backend +source venv/bin/activate +python manage.py runserver +``` + +The Django development server automatically reloads on code changes by default. + +### Frontend Development + +```shell +cd nisria-frontend +npm run dev +``` + +The Vite development server will hot-reload on file changes. + +### Running with Docker (Production) + +```shell +cd nisria-backend +docker-compose -f docker-compose.prod.yml up --build +``` + +## Running Tests + +### Backend Tests + +The backend includes test file stubs for all major apps. To run tests: + +```shell +cd nisria-backend +python manage.py test +``` + +> **Note:** Test implementations need to be added. Current test files contain only the default Django test structure. + +### Linting + +Frontend: +```shell +cd nisria-frontend +npm run lint +``` + +> **Note:** Backend linting is not yet configured in this project. Consider adding a linting tool like `flake8` or `pylint` to `requirements.txt` for code quality checks. + +# Deployment +[(Back to top)](#table-of-contents) + +For detailed deployment instructions, please refer to [README-deploy.md](./documents/README-deploy.md). + +**Quick deployment overview:** + +1. Backend: Deploy using Docker with the provided `docker-compose.prod.yml` +2. Frontend: Deploy to Vercel or similar platform using the `vercel.json` configuration +3. Configure environment variables for production +4. Set up PostgreSQL database +5. Configure CORS settings for frontend-backend communication +6. Set up SSL certificates for HTTPS + +**Creating the first Super Admin with Docker:** + +When deploying with Docker for the first time, you'll need to create a super admin user. Run the following command: + +```shell +docker-compose -f docker-compose.prod.yml exec web python manage.py createsuperuser +``` + +Follow the prompts to create the super admin account. For detailed setup instructions on production servers, see the [Contabo deployment guide](./documents/CONTABO-SETUP.md). + +# Contribute +[(Back to top)](#table-of-contents) + +We welcome contributions to Compass! However, this is a proprietary project owned by [Nisria.Inc](https://www.nisria.co/). + +**Before contributing:** + +1. Contact us at [wahome@nisria.co](mailto:wahome@nisria.co) for permission and licensing information +2. Review our [Security Policy](./SECURITY.md) +3. Check existing issues and pull requests +4. Follow the code style and conventions used in the project + +**Development workflow:** + +1. Fork the repository (with permission) +2. Create a feature branch (`git checkout -b feature/AmazingFeature`) +3. Commit your changes (`git commit -m 'Add some AmazingFeature'`) +4. Push to the branch (`git push origin feature/AmazingFeature`) +5. Open a Pull Request + +**Reporting bugs or requesting features:** + +Please create an issue with detailed information about the bug or feature request. + +# License +[(Back to top)](#table-of-contents) + +This project is proprietary software owned by [Nisria.Inc](https://www.nisria.co/). + +**Important:** This repository is NOT licensed under any open source license. All rights are reserved by Nisria.Inc. + +For licensing inquiries or permission requests, please contact: [wahome@nisria.co](mailto:wahome@nisria.co) + +See [LICENSE.md](./LICENSE.md) for full details. + +--- + +**Copyright © 2025 [Nisria.Inc](https://www.nisria.co/). All rights reserved.** diff --git a/documents/CONTABO-SETUP.md b/documents/CONTABO-SETUP.md new file mode 100644 index 0000000..cd5887d --- /dev/null +++ b/documents/CONTABO-SETUP.md @@ -0,0 +1,161 @@ +# Contabo Server Setup Guide + +This guide provides instructions for deploying Compass on a Contabo server using Docker. + +## Prerequisites + +- Contabo VPS with Ubuntu/Debian +- Docker and Docker Compose installed +- Domain configured with DNS pointing to your server +- SSH access to the server + +## Initial Server Setup + +1. Update system packages: +```bash +sudo apt update && sudo apt upgrade -y +``` + +2. Install Docker: +```bash +curl -fsSL https://get.docker.com -o get-docker.sh +sudo sh get-docker.sh +``` + +3. Install Docker Compose: +```bash +sudo apt install docker-compose -y +``` + +## Deploy Compass + +1. Clone the repository: +```bash +git clone https://github.com/Merge-Labs/Compass.git +cd Compass/nisria-backend +``` + +2. Configure environment variables: +```bash +cp env.prod.example .env.prod +nano .env.prod # Edit with your production settings +``` + +Key variables to configure in `.env.prod`: +- `SECRET_KEY`: Generate a secure Django secret key +- `DATABASE_NAME`, `DATABASE_USER`, `DATABASE_PASSWORD`: Your PostgreSQL credentials +- `ALLOWED_HOSTS`: Your domain names (e.g., example.com,api.example.com) +- `DEBUG`: Should be `False` in production +- `GUNICORN_WORKERS`: Number of Gunicorn workers (typically 2-4) + +3. Build and run the containers: +```bash +docker-compose -f docker-compose.prod.yml up --build -d +``` + +## Creating the First Super Admin + +After deploying for the first time, you need to create a super admin user: + +```bash +docker-compose -f docker-compose.prod.yml exec web python manage.py createsuperuser +``` + +You will be prompted to enter: +- Email address +- Username +- Password +- Password confirmation + +This account will have full administrative access to the Compass system. + +## Running Migrations + +If needed, run database migrations: +```bash +docker-compose -f docker-compose.prod.yml exec web python manage.py migrate +``` + +## Collecting Static Files + +To collect static files for Django admin: +```bash +docker-compose -f docker-compose.prod.yml exec web python manage.py collectstatic --noinput +``` + +## SSL/TLS Configuration + +Set up SSL certificates using Certbot (replace with your actual domain): + +```bash +sudo apt install certbot python3-certbot-nginx -y +sudo certbot --nginx -d example.com -d api.example.com +``` + +Replace `example.com` with your actual domain name. + +## Monitoring Logs + +View application logs: +```bash +docker-compose -f docker-compose.prod.yml logs -f web +``` + +View nginx logs: +```bash +docker-compose -f docker-compose.prod.yml logs -f nginx +``` + +## Updating the Application + +To update to the latest version: + +```bash +cd Compass +git pull origin main +cd nisria-backend +docker-compose -f docker-compose.prod.yml down +docker-compose -f docker-compose.prod.yml up --build -d +``` + +## Backup Database + +Create a database backup: + +```bash +# Using variables from your docker-compose.prod.yml configuration +# Replace DB_USER and DB_NAME with values from your .env.prod file +docker-compose -f docker-compose.prod.yml exec -T db pg_dump -U > backup_$(date +%Y%m%d).sql +``` + +Example with default values: +```bash +docker-compose -f docker-compose.prod.yml exec -T db pg_dump -U manassehgitau main > backup_$(date +%Y%m%d).sql +``` + +Note: The `-T` flag disables pseudo-TTY allocation for proper output redirection. Replace `` and `` with your actual database credentials from `docker-compose.prod.yml`. + +## Troubleshooting + +### Container not starting +```bash +docker-compose -f docker-compose.prod.yml logs web +``` + +### Database connection issues +Check if the database container is running: +```bash +docker-compose -f docker-compose.prod.yml ps +``` + +### Permission issues +Ensure proper permissions on the docker-entrypoint.sh: +```bash +chmod +x docker-entrypoint.sh +``` + +## Additional Resources + +- [Docker Documentation](https://docs.docker.com/) +- [Django Deployment Checklist](https://docs.djangoproject.com/en/stable/howto/deployment/checklist/) +- [README-deploy.md](./README-deploy.md) - Quick deployment guide