diff --git a/docs/developer_guide/architecture.md b/docs/developer_guide/architecture.md index 9dc996f0b..a1dcdb1a2 100644 --- a/docs/developer_guide/architecture.md +++ b/docs/developer_guide/architecture.md @@ -50,23 +50,23 @@ Some examples of modularity are: - Calculation of entitlement - {term}`deduplication` of beneficiaries -## High-level Functional Reference Architecture +## High-level functional reference architecture ![High-level functional reference architecture diagram showing data layer, Odoo core, Open G2P core, functional layer, user engagement layer, stakeholders layer, and integration layer](architecture/highlevel_architecture.jpg) The OpenSPP functional architecture diagram above presents an overview of the components and layers of a typical OpenSPP implementation. -**Data Layer** +**Data layer** The Data Layer is responsible for storing and managing the data generated by and used within the OpenSPP system. It consists of the following: - **Database:** The database stores structured data, such as program information, {term}`beneficiary` records, and transaction data. It uses a relational database management system (RDBMS) such as PostgreSQL. -- **Object Storage:** Object Storage is a component that stores unstructured data, such as images, documents, or other multimedia files. +- **Object storage:** Object Storage is a component that stores unstructured data, such as images, documents, or other multimedia files. Currently, file storage has been used. -**Data Access Layer/Odoo ORM** +**Data access Layer/Odoo ORM** The layer simplifies data interaction through object-oriented constructs and offers CRUD operations, querying, and filtering. @@ -104,7 +104,7 @@ Non-functional requirements are the characteristics of the OpenSPP platform that These include security, privacy, audibility, monitoring, performance, scalability, availability, and maintainability. Only a couple of non-functional requirements are shown in the diagram. -## High-level Deployment Reference Architecture +## High-level deployment reference architecture The on-premises deployment of OpenSPP encompasses a suite of interconnected components, each playing a vital role in delivering secure, robust, and highly efficient service. This document is intended to provide an high-level understanding of the OpenSPP on-premises deployment architecture and its key components. @@ -118,30 +118,30 @@ This document is intended to provide an high-level understanding of the OpenSPP Serving as the entry point, the Firewall regulates the inbound and outbound network traffic based on predetermined security rules. It protects the system's integrity by preventing unauthorized access and mitigating potential security threats. -**Application Load Balancer** +**Application load balancer** The Load Balancer optimizes the performance of OpenSPP application servers by evenly distributing the incoming network traffic across multiple servers. This not only enhances resource utilization and throughput but also prevents server overload. The presence of active and passive nodes ensures failover protection and high availability. -**Identity Server** +**Identity server** The Identity Server effectively manages user identities and controls access to resources. It employs advanced features such as single sign-on, access delegation, and identity federation to ensure secure and compliant access to system resources. -**API Manager** +**API manager** The API Manager in OpenSPP manages and secures APIs, controls access, and collects usage analytics. Acting as a gateway, it validates and routes API calls, manages request rates, and supports API versioning. It's instrumental in enhancing system security and optimizing service quality. -**OpenSPP Application Servers** +**OpenSPP application servers** These servers form the nucleus of the OpenSPP system. They execute the OpenSPP application and coordinate with databases and the API Gateway. The use of active and passive nodes guarantees continuous service and failover protection. -**Database Load Balancer** +**Database load balancer** The Database Load Balancer facilitates the efficient distribution of database queries across various instances. This ensures optimal resource usage and high availability of database {term}`services`. @@ -152,36 +152,36 @@ Databases serve as the data storage centers of the system. They interact directly with the application servers and are crucial for OpenSPP's functioning. Given the large volume of data handled by OpenSPP, a scalable and highly available database system is indispensable. -**Caching Databases** +**Caching databases** Caching Databases enhances system performance by temporarily storing frequently accessed data. This reduces the strain on primary databases and expedites data retrieval processes. -**Object Storage** +**Object storage** This component caters to storing unstructured data such as files. Its high scalability makes it an ideal solution for storing large data volumes. -**File Storage** +**File storage** File Storage manages the storage of structured data in a hierarchical file system. It handles files such as documents and spreadsheets. -**Email Gateway** +**Email gateway** The Email Gateway is tasked with managing email communications in a secure and efficient manner. It plays a pivotal role in sending and receiving emails within the system. -**SMS Gateway** +**SMS gateway** The SMS Gateway allows the system to send and receive SMS messages, ensuring a seamless channel for alerts, notifications, and two-factor {term}`authentication`. -**Monitoring and Alerting System** +**Monitoring and alerting system** This component vigilantly monitors the health and performance of the system. It promptly issues alerts for any detected anomalies or performance issues, ensuring rapid response and resolution. -**Log Aggregation** +**Log aggregation** The Log Aggregation component centralizes log data collection from all system components. It is a critical tool for analyzing system behavior, aiding in diagnosing and troubleshooting issues. diff --git a/docs/developer_guide/index.md b/docs/developer_guide/index.md index 22376a5c9..c14ccfc3c 100644 --- a/docs/developer_guide/index.md +++ b/docs/developer_guide/index.md @@ -1,12 +1,12 @@ --- myst: html_meta: - "title": "Developer Guide" + "title": "Developer guide" "description": "Technical documentation and guides for developers working with OpenSPP - setup, architecture, module development, integrations, and API usage" "keywords": "OpenSPP, developer guide, technical documentation, module development, API, integration, architecture" --- -# Developer Guide +# Developer guide This section provides technical information and instructions for developers who need to customize, extend, integrate with, or contribute to OpenSPP. diff --git a/docs/developer_guide/setup.md b/docs/developer_guide/setup.md index 72808f624..4e744621e 100644 --- a/docs/developer_guide/setup.md +++ b/docs/developer_guide/setup.md @@ -8,7 +8,7 @@ myst: # Development setup -## OpenSPP Docker Setup Using Doodba +## OpenSPP Docker setup using Doodba Docker simplifies the installation of Odoo and its dependencies, with the added benefits offered by Doodba. diff --git a/docs/getting_started/index.md b/docs/getting_started/index.md index bcc868c10..ac4239d96 100644 --- a/docs/getting_started/index.md +++ b/docs/getting_started/index.md @@ -6,7 +6,7 @@ myst: "keywords": "OpenSPP, installation, setup, SP-MIS, Social Registry, Farmer Registry" --- -# Getting Started +# Getting started Welcome to OpenSPP! This guide will help you get your social protection platform up and running quickly. @@ -15,25 +15,25 @@ Welcome to OpenSPP! This guide will help you get your social protection platform :::::{grid} 2 :gutter: 3 -::::{grid-item-card} New Installation +::::{grid-item-card} New installation Start here if you're setting up OpenSPP for the first time: -1. **{doc}`Installation Guide `** +1. **{doc}`Installation guide `** Install OpenSPP on Debian/Ubuntu (30 minutes) -2. **{doc}`Module Installation `** +2. **{doc}`Module installation `** Choose {doc}`SP-MIS <../overview/products/sp_mis>`, {doc}`Social Registry <../overview/products/social_registry>`, or {doc}`Farmer Registry <../overview/products/farmer_registry>` -3. **Initial Setup** +3. **Initial setup** Configure your first program and import data :::: -::::{grid-item-card} Learn the System +::::{grid-item-card} Learn the system Explore OpenSPP's capabilities: - **{doc}`Features <../overview/features/index>`** - Understand key features - **{doc}`Products <../overview/products/index>`** - Choose the right product configuration -- **{doc}`User Guide <../user_guide/index>`** - Learn day-to-day operations +- **{doc}`User guide <../user_guide/index>`** - Learn day-to-day operations :::: ::::: diff --git a/docs/getting_started/installation_deb.md b/docs/getting_started/installation_deb.md index c9fa8b810..e6af1ff39 100644 --- a/docs/getting_started/installation_deb.md +++ b/docs/getting_started/installation_deb.md @@ -6,7 +6,7 @@ myst: "keywords": "OpenSPP, installation, Ubuntu 24.04, Debian 12, PostgreSQL, APT repository, setup guide" --- -# Installation Guide +# Installation guide This guide walks you through installing OpenSPP on Ubuntu 24.04 or Debian 12 (Bookworm) using the official APT repository hosted on Nexus. @@ -22,7 +22,7 @@ Before installing OpenSPP, ensure you have: - Internet connection for downloading packages - Access to https://builds.acn.fr (OpenSPP APT repository) -## Step 1: Update System +## Step 1: Update system First, ensure your system is up to date and install `wget` and `gnupg2`: @@ -41,7 +41,7 @@ sudo apt-get install -y postgresql postgresql-client sudo systemctl status postgresql ``` -## Step 3: Configure OpenSPP Repository +## Step 3: Configure OpenSPP repository Add the OpenSPP Public Key and APT repository to your system: @@ -61,7 +61,7 @@ Install OpenSPP directly from the repository: sudo apt-get install -y openspp-17-daily ``` -### Alternative: Manual Download +### Alternative: Manual download If you prefer to download the package manually or the repository is not accessible: @@ -102,7 +102,7 @@ sudo -u postgres psql -c "ALTER USER openspp WITH PASSWORD 'your_secure_password ## Step 6: Configure OpenSPP -### Basic Configuration +### Basic configuration The main configuration file is located at `/etc/openspp/odoo.conf`. @@ -125,7 +125,7 @@ Find and update these lines (paste the generated password): admin_passwd = YOUR_STRONG_PASSWORD_HERE ``` -2. **Database Management Settings**: +2. **Database management settings**: ```ini ; Database Management @@ -133,7 +133,7 @@ list_db = True ; IMPORTANT: Set to True to enable database creation via ; Set to False for production (more secure) ``` -3. **Queue Job Configuration** (REQUIRED for OpenSPP): +3. **Queue job configuration** (REQUIRED for OpenSPP): OpenSPP uses the queue_job module for asynchronous operations. The package includes default configuration, but you may need to adjust it: @@ -170,7 +170,7 @@ longpolling_port = 8072 ; For real-time features log_level = info ; Options: debug, info, warning, error, critical ``` -### Database Configuration +### Database configuration By default, the package is configured to use Unix socket authentication (peer). This means the `openspp` system user can connect to PostgreSQL without a password. @@ -186,7 +186,7 @@ db_host = localhost db_password = your_postgresql_password ``` -## Step 7: Start OpenSPP Service +## Step 7: Start OpenSPP service ### Enable the service to start on boot ```bash @@ -210,9 +210,9 @@ Required to apply any changes to the configuration: sudo systemctl restart openspp ``` -## Step 8: Create Your First Database +## Step 8: Create your first database -### Option A: Via Web Interface (Recommended) +### Option A: Via web interface (recommended) **Prerequisites**: Ensure `list_db = True` is set in `/etc/openspp/odoo.conf` (see Step 6). @@ -233,7 +233,7 @@ sudo systemctl restart openspp 3. Click "Create Database" and wait (this may take 2-3 minutes) -### Option B: Via Command Line +### Option B: Via command line Create the database, then restart the service: ```bash @@ -253,7 +253,7 @@ Once the database is created: - **Email**: The email you provided during database creation - **Password**: The password you set for the admin user -## Step 10: Install OpenSPP Modules +## Step 10: Install OpenSPP modules After logging in, you'll need to activate the OpenSPP modules: @@ -270,17 +270,17 @@ After logging in, you'll need to activate the OpenSPP modules: ## Getting Help - **Documentation**: https://docs.openspp.org -- **Community Forum**: https://community.openspp.org -- **Issue Tracker**: https://github.com/openspp/openspp-modules/issues -- **Email Support**: support@openspp.org -- **APT Repository**: https://builds.acn.fr/repository/apt-openspp/ +- **Community forum**: https://community.openspp.org +- **Issue tracker**: https://github.com/openspp/openspp-modules/issues +- **Email support**: support@openspp.org +- **APT repository**: https://builds.acn.fr/repository/apt-openspp/ -## Next Steps +## Next steps Now that OpenSPP is installed, here are some recommended next steps: -- **Learn to Use OpenSPP**: Start with the {doc}`../user_guide/index` to understand core features. -- **Administer the System**: Refer to the {doc}`../user_guide/administration/index` for guides on security, maintenance, and troubleshooting. -- **Customize and Develop**: Explore the {doc}`../developer_guide/index` to learn how to extend the platform. -- **Set Up a Pilot Program**: Follow the {doc}`../overview/poc_and_pilot` guide to launch a Proof of Concept (PoC). +- **Learn to use OpenSPP**: Start with the {doc}`../user_guide/index` to understand core features. +- **Administer the system**: Refer to the {doc}`../user_guide/administration/index` for guides on security, maintenance, and troubleshooting. +- **Customize and develop**: Explore the {doc}`../developer_guide/index` to learn how to extend the platform. +- **Set Up a pilot program**: Follow the {doc}`../overview/poc_and_pilot` guide to launch a Proof of Concept (PoC). diff --git a/docs/getting_started/module_installation.md b/docs/getting_started/module_installation.md index 4c29c54dd..49eb80d70 100644 --- a/docs/getting_started/module_installation.md +++ b/docs/getting_started/module_installation.md @@ -29,12 +29,12 @@ For development setup instructions, see the {doc}`Development Setup Guide <../de Installing an Odoo module, including those for OpenSPP, follows a standard procedure: 1. **Place Modules in Addons Path**: Ensure the `openspp-modules` directory is included in your Odoo configuration's `addons_path`. -2. **Update Apps List**: +2. **Update apps list**: - Log in to your Odoo instance with administrator privileges. - Activate the developer mode. - Navigate to the **Apps** menu. - Click on **Update Apps List** and confirm the update. -3. **Install the Module**: +3. **Install the module**: - In the **Apps** menu, clear the default "Apps" filter from the search bar. - Search for the desired module by its technical name or title. - Click the **Activate** button on the module's card to begin the installation. @@ -53,14 +53,14 @@ The **SP-MIS** ({doc}`spp_base `), and **Farmer Reg The Social Protection Management Information System ({doc}`SP-MIS <../overview/products/sp_mis>`) configuration provides comprehensive functionality for managing social protection programs. This setup is ideal for organizations running cash transfers, social assistance programs, or humanitarian interventions. -**What's Included:** +**What's included:** - Registry management for individuals and groups - Program cycles and beneficiary enrollment - Eligibility determination and targeting - Entitlement calculation and management - Payment processing integration -**Installation Steps:** +**Installation steps:** 1. Follow the General Installation Process to update your Apps list 2. In the Apps menu, search for {doc}`spp_base ` or "OpenSPP Base" @@ -79,7 +79,7 @@ Once installed, you will see the "Registry" application in your Odoo dashboard, The {doc}`Social Registry <../overview/products/social_registry>` configuration provides a centralized repository for beneficiary data that can be shared across multiple social protection programs. This setup is ideal for governments and organizations coordinating multiple interventions and requiring a single source of truth for beneficiary information. -**What's Included:** +**What's included:** - Unified beneficiary database across programs - Advanced deduplication and data quality management - Dynamic registration and needs assessment @@ -88,7 +88,7 @@ The {doc}`Social Registry <../overview/products/social_registry>` configuration - Socioeconomic data collection and analysis - Data privacy and access control mechanisms -**Installation Steps:** +**Installation steps:** 1. Follow the General Installation Process to update your Apps list 2. In the Apps menu, search for {doc}`spp_registry_base ` or "OpenSPP Social Registry" @@ -100,7 +100,7 @@ Once installed, the Social Registry becomes the central hub for managing benefic The {doc}`Farmer Registry <../overview/products/farmer_registry>` configuration enables convergence between social protection and agricultural development programs. This setup is designed for organizations supporting smallholder farmers, managing agricultural subsidies, or implementing climate-smart agriculture initiatives. -**What's Included:** +**What's included:** - Farmer and farm household registration - Land parcel mapping with GIS integration - Crop and livestock tracking @@ -108,9 +108,9 @@ The {doc}`Farmer Registry <../overview/products/farmer_registry>` configuration - Seasonal cycle management - Integration with agricultural extension services -**Installation Steps:** +**Installation steps:** -1. Follow the General Installation Process to update your Apps list +1. Follow the general installation process to update your Apps list 2. In the Apps menu, search for {doc}`spp_farmer_registry_base ` or "OpenSPP Farmer Registry Base" ![Searching for SPP Farmer Registry module](module_installation/05-spp_farmer1.jpg) @@ -129,14 +129,14 @@ Additional modules automatically detect and respect your base configuration (SP- ### Common extension modules -**Data Management:** -- **Change Request** ({doc}`spp_change_request `) - Workflow for reviewing and approving data modifications -- **Data Import** ({doc}`spp_registrant_import `) - Bulk data import from Excel/CSV files -- **Manual Eligibility** ({doc}`spp_manual_eligibility `) - Manual beneficiary selection +**Data management:** +- **Change request** ({doc}`spp_change_request `) - Workflow for reviewing and approving data modifications +- **Data import** ({doc}`spp_registrant_import `) - Bulk data import from Excel/CSV files +- **Manual eligibility** ({doc}`spp_manual_eligibility `) - Manual beneficiary selection -**Program Features:** -- **Cash Entitlements** ({doc}`spp_entitlement_cash `) - Cash transfer calculations and management -- **In-Kind Distribution** ({doc}`spp_entitlement_in_kind `) - Non-cash benefit distribution +**Program features:** +- **Cash rntitlements** ({doc}`spp_entitlement_cash `) - Cash transfer calculations and management +- **In-kind distribution** ({doc}`spp_entitlement_in_kind `) - Non-cash benefit distribution - **Eligibility SQL** ({doc}`spp_eligibility_sql `) - SQL-based targeting criteria **Integration & APIs:** diff --git a/docs/index.md b/docs/index.md index b7ac05c86..cf9c3d6a3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,47 +16,47 @@ OpenSPP empowers governments and humanitarian organizations to deliver effective The platform's modular architecture offers three integrated products: **SP-MIS** for comprehensive program management, **Social Registry** for beneficiary data coordination, and **Farmer Registry** for agricultural-social protection convergence. Organizations can deploy specific modules that match their needs while maintaining interoperability with existing systems. -## Key Features +## Key features -- **🎯 [Program Management](overview/features/program_management.md)** - Design and operate multiple social protection programs with configurable cycles and eligibility rules -- **📊 [Unified Registry](overview/features/unified_registry.md)** - Maintain consolidated beneficiary data across programs with advanced deduplication -- **🌾 [GIS & Land Management](overview/features/gis_land_management.md)** - Integrate agricultural data, land holdings, and geospatial analysis for farmer support programs -- **💳 [Payment & Disbursement](overview/features/payment_disbursement.md)** - Connect with multiple payment providers and track benefit distribution -- **🎯 [Eligibility & Targeting](overview/features/eligibility_targeting.md)** - Apply sophisticated criteria for beneficiary selection and prioritization -- **📦 [In-Kind Benefits](overview/features/in_kind_benefits.md)** - Manage distribution of goods, vouchers, and non-cash assistance -- **💬 [Grievance Redress](overview/features/grievance_redress.md)** - Handle complaints and feedback with configurable workflows -- **🔌 [APIs & Integration](overview/features/data_integration_apis.md)** - RESTful APIs and data exchange protocols for system interoperability +- **🎯 [Program management](overview/features/program_management.md)** - Design and operate multiple social protection programs with configurable cycles and eligibility rules +- **📊 [Unified registry](overview/features/unified_registry.md)** - Maintain consolidated beneficiary data across programs with advanced deduplication +- **🌾 [GIS & land management](overview/features/gis_land_management.md)** - Integrate agricultural data, land holdings, and geospatial analysis for farmer support programs +- **💳 [Payment & disbursement](overview/features/payment_disbursement.md)** - Connect with multiple payment providers and track benefit distribution +- **🎯 [Eligibility & targeting](overview/features/eligibility_targeting.md)** - Apply sophisticated criteria for beneficiary selection and prioritization +- **📦 [In-kind benefits](overview/features/in_kind_benefits.md)** - Manage distribution of goods, vouchers, and non-cash assistance +- **💬 [Grievance redress](overview/features/grievance_redress.md)** - Handle complaints and feedback with configurable workflows +- **🔌 [Data integration & APIs](overview/features/data_integration_apis.md)** - RESTful APIs and data exchange protocols for system interoperability -## Who Uses OpenSPP +## Who uses OpenSPP OpenSPP serves diverse organizations implementing social protection and agricultural support programs: -- **Government Ministries** - Social welfare, agriculture, and disaster management agencies -- **Humanitarian Organizations** - UN agencies and NGOs delivering emergency assistance -- **Agricultural Development Programs** - Supporting smallholder farmers with subsidies and climate adaptation -- **Cash Transfer Programs** - Conditional and unconditional cash assistance initiatives -- **Food Security Programs** - Coordinating nutrition support with agricultural production +- **Government ministries** - Social welfare, agriculture, and disaster management agencies +- **Humanitarian organizations** - UN agencies and NGOs delivering emergency assistance +- **Agricultural development programs** - Supporting smallholder farmers with subsidies and climate adaptation +- **Cash transfer programs** - Conditional and unconditional cash assistance initiatives +- **Food security programs** - Coordinating nutrition support with agricultural production -## Quick Start +## Quick start :::::{grid} 2 :gutter: 2 -::::{grid-item-card} 🚀 Get Started +::::{grid-item-card} 🚀 Get started :link: getting_started/index :link-type: doc New to OpenSPP? Start with our installation guide and quickstart tutorial. :::: -::::{grid-item-card} 📚 User Guide +::::{grid-item-card} 📚 User guide :link: user_guide/index :link-type: doc Learn how to use OpenSPP for registry and program management. :::: -::::{grid-item-card} 🔧 Developer Guide +::::{grid-item-card} 🔧 Developer guide :link: developer_guide/index :link-type: doc @@ -114,12 +114,12 @@ Our guiding principles are informed by the Digital Public Goods Standard and the - **Interoperability**: The platform is designed to support system interoperability - critical for the creation of cohesive and efficient digital ecosystems. - **Inclusivity**: Our products can be customized to suit linguistic and cultural requirements, accessibility, digital literacy, and deployment in remote and less-developed contexts. -## Common Tasks +## Common tasks - **[Install OpenSPP](getting_started/installation_deb.md)** - Set up your development or production environment -- **[Create a Program](user_guide/program_management/create_program.md)** - Design and launch social protection programs -- **[Manage Registrants](user_guide/registry_management/index.md)** - Add and manage beneficiary data -- **[Configure Integrations](developer_guide/integrations/index.md)** - Connect with external systems +- **[Create a program](user_guide/program_management/create_program.md)** - Design and launch social protection programs +- **[Manage registrants](user_guide/registry_management/index.md)** - Add and manage beneficiary data +- **[Configure integrations](developer_guide/integrations/index.md)** - Connect with external systems ## Digital Public Good & Open Source Foundation diff --git a/docs/reference/modules/index.md b/docs/reference/modules/index.md index e59154377..c0c32e8dc 100644 --- a/docs/reference/modules/index.md +++ b/docs/reference/modules/index.md @@ -1,12 +1,12 @@ -# OpenSPP Modules Index +# OpenSPP modules index ```{warning} **Work in Progress**: This document is actively being developed and updated. Content may be incomplete or subject to change. ``` -## SPP Modules +## SPP modules | Module | Summary | | ------ | ------- | @@ -81,7 +81,7 @@ | [OpenSPP: Starter](spp_starter) | A guided setup wizard configures new OpenSPP instances, defining core program requirements and automatically installing relevant OpenSPP modules. It specializes system deployment based on program type selection and performs initial data cleanup for a production-ready environment. | | [OpenSPP User Roles](spp_user_roles) | The OpenSPP User Roles module defines and manages distinct user roles, categorizing them as global or local, to implement area-based access control. It restricts user access to specific geographical areas by leveraging the spp_area module and automates underlying system permission assignments. | -## G2P Modules +## G2P modules | Module | Summary | | ------ | ------- | diff --git a/docs/user_guide/administration/custom_fields.md b/docs/user_guide/administration/custom_fields.md index 2f9cef0db..b8cc14ec0 100644 --- a/docs/user_guide/administration/custom_fields.md +++ b/docs/user_guide/administration/custom_fields.md @@ -1,5 +1,5 @@ -# Custom Fields +# Custom fields Custom fields are a powerful feature in OpenSPP that allow administrators to add new data fields to registrant profiles without requiring developer intervention. They can be used to capture additional information that is specific to a program's needs, such as a secondary contact number, a disability status, or any other piece of data not included in the standard OpenSPP setup. @@ -32,7 +32,7 @@ First, access the Custom Fields management interface. ![Step01 configuration custom fields](custom_fields/step01_configuration_custom_fields.jpg) -### Create a New Field +### Create a new field On the **Custom Fields** page, you will see a list of existing custom fields. 1. Click the **New** button to start creating a new custom field. @@ -43,7 +43,7 @@ The **Custom Fields** form view will appear. ![Step02a custom fields form view](custom_fields/step02a_custom_fields_form_view.jpg) -### Configure Basic Properties +### Configure basic properties Now, define the basic characteristics of your new custom field. For this example, we are adding a secondary phone number field for individuals. @@ -56,7 +56,7 @@ Now, define the basic characteristics of your new custom field. For this example ![Step03 set type custom](custom_fields/step03_set_type_custom.jpg) -### Configure Properties (Optional) +### Configure properties (Optional) Since this is a standard custom field, you do not need to provide computation logic. However, you can configure its behavior in the **Properties** tab. @@ -69,7 +69,7 @@ For our example, we will leave these options unchecked. ![Step04 specify advanced props](custom_fields/step04_specify_advanced_props.jpg) -### Save and Open an Individual Record +### Save and open an individual record Once all properties are configured, save the new field. @@ -78,7 +78,7 @@ Once all properties are configured, save the new field. ![Step05 open individual list view](custom_fields/step05_open_individual_list_view.jpg) -### Verify the Custom Field +### Verify the custom field 1. To verify that the field was created, open any record in the **Individuals** list view. diff --git a/docs/user_guide/administration/database_management.md b/docs/user_guide/administration/database_management.md index cd883a79b..bd5aeb03b 100644 --- a/docs/user_guide/administration/database_management.md +++ b/docs/user_guide/administration/database_management.md @@ -1,20 +1,20 @@ -# Database Management +# Database management This section explains how to manage your OpenSPP database, including how to reset the database, and how to back up your data before making major changes. Proper database management helps ensure data integrity and system reliability. -## Reset Database +## Reset database If you need to reset your OpenSPP database (e.g., for testing or to start fresh): -### Option A: Via Web Interface (if list_db = True) +### Option A: Via web interface (if list_db = True) 1. Navigate to `http://your-server-ip:8069/web/database/manager` 3. Click the "Delete" from the right side of the Database you wanted to Delete. 4. Enter the Master Password then Click the "Delete". 5. Create a new database with the same name or different name -### Option B: Via Command Line +### Option B: Via command line In your terminal, run the following commands: @@ -39,7 +39,7 @@ This drops the openspp_prod database, creates a new one, initializes it, and sta - User accounts and settings - Custom configurations -## Backup Before Reset +## Backup before reset The following commands create a backup of both the database and the filestore: diff --git a/docs/user_guide/administration/email_gateway.md b/docs/user_guide/administration/email_gateway.md index 438283d8c..45456edae 100644 --- a/docs/user_guide/administration/email_gateway.md +++ b/docs/user_guide/administration/email_gateway.md @@ -1,21 +1,21 @@ --- myst: html_meta: - "title": "Email Gateway Configuration" + "title": "Email gateway configuration" "description": "Configure SMTP outgoing and IMAP/POP incoming email servers in OpenSPP for automated communication and data processing" "keywords": "OpenSPP, email gateway, SMTP, IMAP, POP, email configuration, system administration" --- -# Email Gateway Configuration +# Email gateway configuration The Email Gateway in OpenSPP allows the platform to both send and receive emails, automating key communication and data entry tasks. -- **Outgoing Emails (SMTP):** Used for sending system notifications, user invitations, password resets, and other communications from OpenSPP to users and beneficiaries. -- **Incoming Emails (IMAP/POP):** Used to automatically create or update records in OpenSPP from a dedicated mailbox. For example, an email sent to a specific address could automatically generate a grievance ticket or a change request. +- **Outgoing emails (SMTP):** Used for sending system notifications, user invitations, password resets, and other communications from OpenSPP to users and beneficiaries. +- **Incoming emails (IMAP/POP):** Used to automatically create or update records in OpenSPP from a dedicated mailbox. For example, an email sent to a specific address could automatically generate a grievance ticket or a change request. This guide provides a step-by-step process for configuring both outgoing and incoming email servers in OpenSPP. --- -## Outgoing Email Server (SMTP) Configuration +## Outgoing email server (SMTP) Configuration Configuring an outgoing email server allows OpenSPP to send emails using your organization's own email service. This ensures better deliverability, branding, and control over your email communications. @@ -37,7 +37,7 @@ After completing this section, you will be able to configure OpenSPP to reliably The process involves activating developer mode, navigating to the outgoing email server settings, creating a new configuration, and testing it to ensure it works correctly. -#### Activate Developer Mode +#### Activate developer mode To access the technical settings required for email configuration, you must first activate developer mode. @@ -49,7 +49,7 @@ To access the technical settings required for email configuration, you must firs Once activated, a bug icon will appear in the top-right corner of the header, and new technical menus will become available. -#### Navigate to Outgoing Email Servers +#### Navigate to outgoing email servers With developer mode active, you can now access the menu for configuring outgoing email servers. @@ -59,7 +59,7 @@ With developer mode active, you can now access the menu for configuring outgoing ![Technical menu dropdown showing the Email section with 'Outgoing Email Servers' option highlighted](email_gateway/A-step02-open-outgoing-email-servers.jpg) -#### Create a New Server Configuration +#### Create a new server configuration On the **Outgoing Email Servers** page, you will see a list of any existing servers. @@ -69,7 +69,7 @@ On the **Outgoing Email Servers** page, you will see a list of any existing serv This will open a new form where you can enter your SMTP server details. -#### Fill in Server Details +#### Fill in server details Now, fill in the form with the details from your email provider. @@ -83,7 +83,7 @@ Now, fill in the form with the details from your email provider. ![SMTP server configuration form showing fields for Name, Priority, Connection Encryption, Username, Password, SMTP Server, and SMTP Port](email_gateway/A-step04-fill-in-server-details.jpg) -#### Test and Save the Configuration +#### Test and save the configuration After filling in all the details, it's crucial to test the connection to ensure everything is correct. @@ -97,7 +97,7 @@ After filling in all the details, it's crucial to test the connection to ensure Your new email server is now configured and, if it has the lowest priority, will be used by OpenSPP to send all outgoing emails. --- -## Incoming Email Server (IMAP/POP) Configuration +## Incoming email server (IMAP/POP) Configuration Configuring an incoming email server allows OpenSPP to fetch emails from a dedicated mailbox and process them automatically. This is a powerful feature that can create or update records based on the content of the emails. For example, an email sent to `support@youremailserver.com` could automatically create a new Grievance ticket. @@ -120,11 +120,11 @@ After completing this section, you will be able to configure OpenSPP to fetch em The process is similar to configuring an outgoing server, involving developer mode and navigating to the technical settings. -#### Activate Developer Mode +#### Activate developer mode If you have not already, activate developer mode to access the technical settings. -#### Navigate to Incoming Email Servers +#### Navigate to incoming email servers 1. Go back to the main **Settings** page. 2. Click on the **Technical** menu in the header. @@ -132,7 +132,7 @@ If you have not already, activate developer mode to access the technical setting ![Technical menu dropdown showing the Email section with 'Incoming Email Servers' option highlighted](email_gateway/B-step02-open-incoming-email-servers.jpg) -#### Create a New Server Configuration +#### Create a new server configuration 1. On the **Incoming Email Servers** page, click the **New** button. @@ -140,7 +140,7 @@ If you have not already, activate developer mode to access the technical setting This will open a form to enter your incoming server details. -#### Fill in Server Details +#### Fill in server details Fill in the form with the details for the mailbox you want OpenSPP to monitor. @@ -156,7 +156,7 @@ Fill in the form with the details for the mailbox you want OpenSPP to monitor. ![IMAP/POP server configuration form showing fields for Name, Server Type, Server Name, Port, SSL/TLS, Username, Password, and Action settings](email_gateway/B-step04-fill-in-server-details.jpg) -#### Test and Save +#### Test and save 1. Click the **Test & Confirm** button. 2. OpenSPP will attempt to connect to the mailbox. If successful, you will see a confirmation. diff --git a/docs/user_guide/administration/indicator_fields.md b/docs/user_guide/administration/indicator_fields.md index 119dc1524..77e5dda57 100644 --- a/docs/user_guide/administration/indicator_fields.md +++ b/docs/user_guide/administration/indicator_fields.md @@ -1,5 +1,5 @@ -# Indicator Fields +# Indicator fields Indicator fields are a powerful feature in OpenSPP that allow for dynamic data calculation based on existing information in the registry. They can be used to create simplified data points, such as the number of children in a household or the count of members with a specific attribute. These indicators are crucial for program operations, particularly for defining eligibility criteria and targeting beneficiaries for social protection programs. @@ -23,16 +23,16 @@ After completing this tutorial, you will understand how to create, configure, an The process involves navigating to the Custom Fields menu, defining the properties of the new indicator, providing the calculation logic, and verifying its presence on the group records. -### Navigate to Custom Fields +### Navigate to custom fields -First, access the Custom Fields management interface. +First, access the custom fields management interface. 1. Click on the menu icon in the top-left corner and select **Registry**. 2. In **Registry** click the **Configuration** menu. 3. Click on the **Custom Fields** sub-menu. ![Step01 configuration custom fields](indicator_fields/step01_configuration_custom_fields.jpg) -### Create a New Field +### Create a new field On the **Custom Fields** page, you will see a list of existing custom fields. 1. Click the **New** button to start creating a new indicator field. @@ -43,7 +43,7 @@ The **Custom Fields** form view will appear. ![Step02a custom fields form view](indicator_fields/step02a_custom_fields_form_view.jpg) -### Configure Basic Properties +### Configure basic properties Now, define the basic characteristics of your new indicator field. For this example, we are counting male members in a group. @@ -56,7 +56,7 @@ Now, define the basic characteristics of your new indicator field. For this exam ![Step03 set type calculated](indicator_fields/step03_set_type_calculated.jpg) -### Configure Advanced Properties +### Configure advanced properties Since this is a calculated field, you must provide the logic for its computation in the **Properties** tab. @@ -78,7 +78,7 @@ self.compute_count_and_set_indicator('x_ind_grp_total_male', kinds, domain) ![Step04 specify compute field code](indicator_fields/step04_specify_compute_field_code.jpg) -### Save and Open a Group +### Save and open a group Once all properties are configured, save the new field. @@ -87,7 +87,7 @@ Once all properties are configured, save the new field. ![Step05 open group list view](indicator_fields/step05_open_group_list_view.jpg) -### Verify the Indicator Field +### Verify the indicator field 1. To verify, open any record in the **Groups** list view. diff --git a/docs/user_guide/administration/inventory_configuration.md b/docs/user_guide/administration/inventory_configuration.md index 05146efcf..ef7e7ad6b 100644 --- a/docs/user_guide/administration/inventory_configuration.md +++ b/docs/user_guide/administration/inventory_configuration.md @@ -1,18 +1,18 @@ --- myst: html_meta: - "title": "Inventory Configuration" + "title": "Inventory configuration" "description": "Configure OpenSPP inventory settings including storage locations and units of measure for in-kind and basket entitlement modules" "keywords": "OpenSPP, inventory, configuration, storage locations, units of measure, entitlements" --- -# Inventory Configuration +# Inventory configuration OpenSPP's In-Kind and Basket Entitlement modules leverage Odoo's powerful Inventory application to manage the distribution of goods and services to beneficiaries. To ensure these modules function correctly, specific features within the Inventory settings must be activated. This guide provides a step-by-step process for enabling two critical inventory features: -- **Storage Locations:** Allows for the management of specific locations within a warehouse (e.g., shelves, bins), which is essential for detailed stock tracking. +- **Storage locations:** Allows for the management of specific locations within a warehouse (e.g., shelves, bins), which is essential for detailed stock tracking. - **Units of Measure:** Enables the use of different units for buying, selling, and storing products (e.g., kilograms, boxes, individual units), which is crucial for accurate entitlement definition. ## Prerequisites @@ -31,25 +31,25 @@ After completing this guide, you will have enabled the necessary Inventory confi The process involves navigating to the Inventory settings and activating two key options: Storage Locations and Units of Measure. -### Enabling Storage Locations +### Enabling storage locations This feature allows you to manage a structured warehouse with specific locations. -#### Navigate to Inventory Settings +#### Navigate to inventory settings 1. Click on the menu icon in the top-left corner and select **Inventory**. 2. In the **Inventory** dashboard, click on the **Configuration** menu and select **Settings**. ![OpenSPP interface showing the main menu with Inventory selected and Configuration submenu with Settings option highlighted](inventory_configuration/A-step01-navigate-to-inventory-settings.jpg) -#### Activate Storage Locations +#### Activate storage locations 1. On the **Settings** page, scroll down to the **Warehouse** section. 2. Check the box next to **Storage Locations**. ![Inventory Settings page displaying the Warehouse section with the Storage Locations checkbox available for activation](inventory_configuration/A-step02-activate-storage-locations.jpg) -#### Save the Configuration +#### Save the configuration 1. After checking the box, a **Save** button will appear at the top of the page. 2. Click **Save** to apply the changes. @@ -61,7 +61,7 @@ This feature allows you to manage a structured warehouse with specific locations This feature is essential for defining product quantities in different units. -#### Navigate to Inventory Settings +#### Navigate to inventory settings If you are not already on the settings page: 1. Go to the **Inventory** application. @@ -74,7 +74,7 @@ If you are not already on the settings page: ![Inventory Settings page showing the Products section with the Units of Measure checkbox ready for activation](inventory_configuration/B-step02-activate-unit-of-measure.jpg) -#### Save the Configuration +#### Save the configuration 1. Click the **Save** button at the top of the page to apply the changes. diff --git a/docs/user_guide/administration/monitoring_maintenance.md b/docs/user_guide/administration/monitoring_maintenance.md index 7cd6fe520..264f5914d 100644 --- a/docs/user_guide/administration/monitoring_maintenance.md +++ b/docs/user_guide/administration/monitoring_maintenance.md @@ -1,9 +1,9 @@ -# Monitoring and Maintenance +# Monitoring and maintenance This section provides basic instructions for monitoring your OpenSPP system, viewing logs, managing services, and performing updates. Regular monitoring and maintenance help keep your system running smoothly and securely. -## View Logs +## View logs ### Real-time service logs @@ -21,7 +21,7 @@ sudo tail -f /var/log/openspp/openspp.log sudo tail -f /var/log/postgresql/postgresql-*.log ``` -## Service Management +## Service management ### Restart service ```bash @@ -56,7 +56,7 @@ sudo apt-get upgrade openspp sudo systemctl start openspp ``` -## Alternative: Manual Update +## Alternative: manual update If updating manually, run the following commands to get the latest debian package and upgrade OpenSPP: diff --git a/docs/user_guide/administration/security_tuning.md b/docs/user_guide/administration/security_tuning.md index 1812e1c7e..314869b43 100644 --- a/docs/user_guide/administration/security_tuning.md +++ b/docs/user_guide/administration/security_tuning.md @@ -1,11 +1,11 @@ -# Security and Performance Tuning +# Security and performance tuning This guide provides essential recommendations for securing your OpenSPP instance and tuning its performance for production environments. It covers database security, firewall setup, SSL/TLS configuration with Nginx, and implementing regular backups. Additionally, it offers tips on performance tuning, including adjusting worker processes, memory limits, and PostgreSQL settings to handle high-load scenarios. -## Security Recommendations +## Security recommendations -### 1. Database Security Configuration +### 1. Database security configuration After initial setup and database creation, it's strongly recommended to modify the configuration file: @@ -35,7 +35,7 @@ sudo systemctl restart openspp - Initial setup phase - When multiple databases need frequent management -### 2. Firewall Configuration +### 2. Firewall configuration **Install ufw** ```bash @@ -129,7 +129,7 @@ sudo nginx -t sudo systemctl reload nginx sudo certbot --nginx -d your-domain.com ``` -### 4. Regular Backups +### 4. Regular backups Create a backup script: @@ -166,7 +166,7 @@ sudo chmod +x /usr/local/bin/openspp-backup.sh echo "0 2 * * * /usr/local/bin/openspp-backup.sh" | sudo crontab - ``` -## Performance Tuning +## Performance tuning For production environments with high load: diff --git a/docs/user_guide/administration/troubleshooting.md b/docs/user_guide/administration/troubleshooting.md index 42f7d2e8c..9364ba2c8 100644 --- a/docs/user_guide/administration/troubleshooting.md +++ b/docs/user_guide/administration/troubleshooting.md @@ -3,7 +3,7 @@ This guide provides solutions to common problems encountered while running OpenSPP. It covers issues such as the service failing to start, inability to access the web interface, database connection problems, and background jobs not running. It also includes a procedure for resetting the admin password if it's forgotten. -## Service Won't Start +## Service won't start Check logs for errors: ```bash @@ -15,7 +15,7 @@ Common issues: - **Port already in use**: Another service using port 8069 - **Permission denied**: Check file ownership in `/var/lib/openspp/` -## Cannot Access Web Interface +## Cannot access web interface 1. Check if service is running: ```bash @@ -33,7 +33,7 @@ Common issues: curl -I http://localhost:8069 ``` -## Database Connection Issues +## Database connection issues 1. Verify PostgreSQL is running: ```bash @@ -50,7 +50,7 @@ Common issues: sudo cat /etc/postgresql/16/main/pg_hba.conf | grep -E '^(local|host)' ``` -## Queue Jobs Not Running +## Queue jobs not running If background jobs are not being processed: @@ -82,7 +82,7 @@ If background jobs are not being processed: - Navigate to Settings > Technical > Queue Job > Jobs - Check for failed or pending jobs -## Reset Admin Password +## Reset admin password If you forget the admin password for the database: diff --git a/docs/user_guide/administration/uninstalling.md b/docs/user_guide/administration/uninstalling.md index fb2aad8bc..51952a177 100644 --- a/docs/user_guide/administration/uninstalling.md +++ b/docs/user_guide/administration/uninstalling.md @@ -2,28 +2,28 @@ # Uninstalling OpenSPP This guide provides instructions for uninstalling OpenSPP from a Debian or Ubuntu system. It covers two main scenarios: -- **Complete Uninstallation**: Removes the application, configuration, data, and database. -- **Partial Uninstallation**: Removes the application but keeps your data and configuration for future use. +- **Complete uninstallation**: Removes the application, configuration, data, and database. +- **Partial uninstallation**: Removes the application but keeps your data and configuration for future use. -## Before You Begin: Back Up Your Data +## Before you begin: back up your data **Warning**: A complete uninstallation is irreversible and will permanently delete your data. Before proceeding, it is strongly recommended to create a full backup of your database and filestore. For detailed backup instructions, refer to the {doc}`database_management` guide. -## Complete Uninstallation +## Complete uninstallation Follow these steps to completely remove OpenSPP and all its components from your system. -### Step 1: Stop and Disable the OpenSPP Service +### Step 1: Stop and disable the OpenSPP service -**Stop and Disable (Remove) OpenSPP service** +**Stop and disable (remove) OpenSPP service** ```bash sudo systemctl stop openspp sudo systemctl disable openspp ``` -### Step 2: Remove OpenSPP Package +### Step 2: Remove OpenSPP package **Remove OpenSPP package and configuration files** ```bash @@ -35,7 +35,7 @@ sudo rm -f /usr/bin/openspp-server sudo rm -f /usr/bin/openspp-shell ``` -### Step 3: Remove PostgreSQL Database (Optional) +### Step 3: Remove PostgreSQL database (Optional) **Warning**: This will permanently delete all OpenSPP data. @@ -46,7 +46,7 @@ sudo -u postgres dropdb name_of_your_db sudo -u postgres dropuser openspp ``` -### Step 4: Remove Repository Configuration +### Step 4: Remove repository configuration **Remove APT repository configuration and GPG Key** ```bash @@ -55,7 +55,7 @@ sudo apt-key del "OpenSPP Repository" sudo apt-get update ``` -### Step 5: Clean Up Dependencies (Optional) +### Step 5: Clean up dependencies (Optional) If you want to remove PostgreSQL as well: @@ -66,12 +66,12 @@ sudo rm -rf /var/lib/postgresql sudo rm -rf /etc/postgresql ``` -## Partial Uninstallation +## Partial uninstallation If you want to keep the database but remove the application: -**Stop, Disable (Remove) service, and remove package** +**Stop, disable (remove) service, and remove package** ```bash sudo systemctl stop openspp sudo systemctl disable openspp @@ -81,6 +81,6 @@ sudo apt-get remove openspp-17-daily - Keep database and filestore for potential reinstallation - var/lib/openspp/ and PostgreSQL database remain intact -## Reinstall After Uninstallation +## Reinstall after uninstallation To reinstall OpenSPP after uninstallation, follow the {doc}`../../getting_started/installation_deb`. \ No newline at end of file diff --git a/docs/user_guide/administration/user_access.md b/docs/user_guide/administration/user_access.md index 29ae07c3c..decc45eb3 100644 --- a/docs/user_guide/administration/user_access.md +++ b/docs/user_guide/administration/user_access.md @@ -6,9 +6,9 @@ myst: "keywords": "OpenSPP, user access, role-based access control, permissions, user management, roles, security" --- -# User Access +# User access -User Access Management in OpenSPP lets administrators control who can access platform features and data. +User access management in OpenSPP lets administrators control who can access platform features and data. OpenSPP uses role-based access control, allowing assignment of specific permissions to users or groups. This ensures only authorized users can access sensitive data and perform necessary actions. diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md index b59287388..6b0cf3f51 100644 --- a/docs/user_guide/index.md +++ b/docs/user_guide/index.md @@ -1,9 +1,9 @@ -# User Guide +# User guide This section provides practical, task-oriented instructions for using OpenSPP's features in day-to-day operations. These guides are designed for administrators and end-users who need to accomplish specific tasks within the platform. -## Registry Management +## Registry management Guides for managing registrant data and registry operations: @@ -15,7 +15,7 @@ Guides for managing registrant data and registry operations: - {doc}`registry_management/using_event_data` - {doc}`registry_management/dms` -## Program Management +## Program management Guides for creating and managing social protection programs: @@ -40,7 +40,7 @@ Administrative tasks and system management: - {doc}`administration/email_gateway` - {doc}`administration/hardware_integration` -## Other Features +## Other features - {doc}`pos_usage` - {doc}`grievance_management` diff --git a/docs/user_guide/program_management/index.md b/docs/user_guide/program_management/index.md index 82cf6ced0..e160a0ae8 100644 --- a/docs/user_guide/program_management/index.md +++ b/docs/user_guide/program_management/index.md @@ -1,5 +1,5 @@ -# Program Management +# Program management This section offers comprehensive guides to help you create, manage, and deliver social protection programs effectively. From initial setup and beneficiary enrollment to fund allocation and cycle management, these documents provide step-by-step instructions to ensure your programs are well-defined and efficiently executed. diff --git a/docs/user_guide/registry_management/import_export_registrant_data.md b/docs/user_guide/registry_management/import_export_registrant_data.md index 10dc80b82..89814a6b1 100644 --- a/docs/user_guide/registry_management/import_export_registrant_data.md +++ b/docs/user_guide/registry_management/import_export_registrant_data.md @@ -6,7 +6,7 @@ myst: "keywords": "OpenSPP, data import, data export, registrant data, CSV, XLSX, system administration" --- -# Import and Export Registrant Data +# Import and export registrant data This guide offers a comprehensive, step-by-step overview of the process for exporting registrant data from OpenSPP. It details the procedures, configurable options, and considerations available to system administrators, including how to use the export functionality to prepare files for re-import into OpenSPP. @@ -45,7 +45,7 @@ If you want to export more records than are displayed on the page, select them b ![Export users select all](import_export_registrant_data/export_users_select_all.png) -### Define Export parameters +### Define export parameters After selecting the records, click the **Action** button and select the **Export** action from the list of actions. @@ -77,7 +77,7 @@ After saving, you can select your template by clicking on the dropdown arrow aga The specific steps and interface may vary depending on the OpenSPP version. Always seek assistance from the support team if you need further guidance. -### Perform Import +### Perform import #### Import to update existing registrant data @@ -135,7 +135,7 @@ When the file is considered valid, click the **Import** button. This will redire ![Import export successful import](import_export_registrant_data/import_export_successful_import.png) -### Error Handling +### Error handling OpenSPP displays different types of error messages on the import page when encountering an error after clicking the **Test** button. This ensures no invalid value or file would compromise data in OpenSPP. Therefore, it is important to always **Test** the file first before importing. Here are common errors encountered during import. diff --git a/docs/user_guide/registry_management/index.md b/docs/user_guide/registry_management/index.md index b111bb5cd..bc6bd12f9 100644 --- a/docs/user_guide/registry_management/index.md +++ b/docs/user_guide/registry_management/index.md @@ -1,5 +1,5 @@ -# Registry Management +# Registry management This section provides essential guides for managing the core of OpenSPP: the registry. From initial data entry to ongoing maintenance, these documents cover the key processes for ensuring your data is accurate, secure, and well-organized. Whether you are setting up a new registry or managing an existing one, these guides will provide the necessary steps to maintain a robust and reliable system.