Comserv Application Documentation

Back to top of Documentation

Overview

Main Features of the New Site:

1. AI Integration with the Site:

   Integrates the ability to search internal resources, external resources, and add information to the local system.

2. Modular Design:

   Ensures the site is built in a modular fashion for ease of maintenance and scalability.

3. ToDo, Project Management, Logs:

   Incorporates tools for managing tasks, projects, and maintaining logs for better tracking and management.

4. Admin Functions:

   Provides capabilities to edit files, control Cascading Style Sheets, update the application, and manage the schema.

5. Security:

   Implements robust security measures to protect data and user information.

6. Documentation:

   Maintains comprehensive documentation to assist developers and users.

7. Search:

   Uses Artificial Intelligence to build a comprehensive information base, improving search accuracy and relevance.

8. Reference System of Documents:

   Offers a well-organized system for managing and referencing documents.

9. Power Monitoring System:

   Includes a system for monitoring power usage and efficiency.

10. Web-Based Email:

    Provides a web-based email client for managing emails.

11. Web-Based Calendar:

    The application now includes a web-based calendar module. This module can be used by all other modules in the application for scheduling and event management. It provides features such as creating, viewing, and editing events, setting reminders, and sharing events with other users. The calendar module is designed to be flexible and adaptable, allowing it to be integrated with other modules in various ways. For example, the project management module could use the calendar to schedule project deadlines and milestones, while the education module could use it to schedule classes and exams.

12. Web-Based Address Book:

    Maintains a web-based address book for contact management.

13. Web-Based File Manager:

    Includes a web-based file manager for file storage and organization.

14. Web-Based Photo Album:

    Provides a web-based photo album for managing and sharing photos.

15. Web-Based Music Player:

    Includes a web-based music player for playing and managing music files.

16. Hosting Multiple Sites:

    Supports the ability to host multiple sites using the same software.

17. Extensive Herbal and Health Information:

    Provides detailed information on herbs and health-related topics.

Back to top of Main Features

Suggestions for Improvement and Expansion

• AI Integration Planning: Create a detailed plan for integrating Artificial Intelligence into various modules of the application. This should include specific tasks, goals, and technologies to be used. Consider adding an AI.tt documentation file to outline this plan.
• User Feedback Mechanism: Implement a system for collecting user feedback to continuously improve the user experience and functionality of the site.
• Enhanced Security Measures: Regularly review and update security protocols to address new vulnerabilities and threats.
• Performance Optimization: Optimize the application's performance to handle increasing amounts of data and user activity efficiently.
• Accessibility Improvements: Ensure the site meets accessibility standards to provide an inclusive experience for all users.
• Regular Updates and Maintenance: Establish a schedule for regular updates and maintenance to keep the site current and secure.
• Training and Support Resources: Develop training materials and support resources for users and administrators to maximize the application's potential.
• Calendar Module Enhancements: Continue to enhance the functionality of the calendar module. Consider adding features such as recurring events, event categories, and integration with external calendar services. Also, explore ways to further integrate the calendar with other modules in the application.

Instructions for Developers

To ensure the continuous improvement and consistency of this project, please adhere to the following guidelines:

• Naming Conventions: Follow the existing naming conventions strictly. If you find inconsistencies, normalize them to maintain uniformity.
• Code Quality: Write clear, well-documented code. Use meaningful variable and function names to enhance readability and maintainability.
• Error Handling: Implement robust error handling to ensure the application behaves predictably under unexpected conditions.
• Contributing to the Todo List: If you identify any issues or potential improvements, add them to the 'Todo' section of the documentation.
• Code Reviews: Submit your code for peer review to catch potential issues early and ensure adherence to best practices.

We are committed to evolving the Comserv application to meet the needs of our users. Your contributions and adherence to these guidelines are crucial for our continued success.

Back to top of Overview

Back to top of Documentation

Admin Module

Table of Contents

• Site Management
• Database Schema Management

The Admin module provides a suite of tools for managing various aspects of the site, with a current focus on handling schema changes within the application.

Site Management

The Site Management section includes the following features:

• Edit Documentation
• Change Styles
• Update Software
• Change User Roles
• Access Logging

Database Schema Management

The Database Schema Management section focuses on managing database schema changes from within the application. It includes the following features:

• Admin Controller: The Admin Controller handles various administrative tasks. Here are the routes defined in the controller and their functionalities:
  1. begin: Checks if the user is logged in and if they have the 'admin' role. If not, redirects to an error page.
  2. index: Sets the Template Toolkit template to 'admin/index.tt' and forwards the request to the view.
  3. edit_documentation: Sets the Template Toolkit template to 'admin/edit_documentation.tt'.
  4. add_schema: Handles the addition of new schemas. If the request method is 'POST', retrieves the schema name and description from the form, runs the 'create_migration_script.pl' script, and checks if the script ran successfully.
  5. migrate_schema: Handles the migration of schemas. If the request method is 'POST', runs the 'migrate_schema.pl' script.
  6. toggle_debug: Toggles the 'CATALYST_DEBUG' environment variable and redirects to the admin index page.
  7. get_table_info: Retrieves information about a specific table from the 'DBEncy' model. If the table exists, displays its schema. If the table does not exist, displays an error message.
• Add New Schema: This feature allows you to add new schemas to the database. It works as follows:
  1. When you click on the "Add New Schema" link, it will open a new window or tab and take you to a specific route in the Catalyst application.
  2. This route points to a method in the Admin controller. This method handles the logic for adding a new schema.
  3. The method first retrieves the current schemas from the database and the application schema.
  4. It then compares the two sets of schemas. If there are any schemas present in the application schema that are not in the database, these are the new schemas that need to be added.
  5. For each new schema, it is added to the database.
  6. If there are any schemas in the application that are also in the database but have differences, these are the schemas that need to be modified. These schemas are updated in the database.
  7. Finally, a success message is returned if the operation was successful, or an error message if there were any issues.

  To use this feature, click on the link below:

  Add New Schema
• Get Table Information Retrieves information about a specific table from the 'DBEncy' model. If the table exists, displays its schema. If the table does not exist, displays an error message.
• Migrate Schema Handles the migration of schemas. If the request method is 'POST', runs the 'migrate_schema.pl' script.

For more information on how to use these features, please refer to the specific documentation for each feature.

Back to top of Documentation

AI Integration Plan

This document outlines the integration of AI features into the Comserv application, focusing on enhancing user interactions and data management.

Objectives

• Implement AI-driven recommendations for content management.
• Utilize natural language processing for user queries and interactions.
• Enhance data analysis capabilities for better decision-making.

Implementation Steps

1. Research and select appropriate AI frameworks and libraries.
2. Integrate AI components into the existing architecture.
3. Test AI functionalities in a controlled environment.
4. Deploy AI features in production and monitor performance.

Future Enhancements

Explore additional AI capabilities such as predictive analytics and automated content generation.

Back to top of Documentation

DBI Setup

DBI (Database Independent Interface) is a database access module for the Perl programming language. It defines a set of methods, variables, and conventions that provide a consistent database interface, independent of the actual database being used.

In the `Comserv::Model::DBEncy` and `Comserv::Model::DBForager` modules, DBI is used to establish connections to the respective MySQL databases ('Ency' and 'Forager').

The database connection information for each module is retrieved from a JSON file named 'db_config.json', which contains details such as the database name, host, port, username, and password.

The `_build_dbh` method in each module is responsible for establishing the database connection using the DBI->connect method.

Database Operations

The `DBEncy` and `DBForager` modules provide methods for performing various database operations specific to their respective MySQL databases.

Debugging

The code includes extensive debugging output, with print statements showing the progress of execution and the values of important variables. This can be very helpful for troubleshooting problems with database operations.

Security

The code employs security measures such as hashing passwords using the Digest::SHA module to ensure secure password storage.

Catalyst Integration

The `DBEncy` and `DBForager` modules are designed to be used as models in a Catalyst application. They utilize the Catalyst context object ($c) to access session data and other Catalyst features.

For more information on how AI can enhance the functionalities of the DBI module, refer to the AI Integration Plan.

Back to top of Documentation

Beemaster Application.

This application is intended to both educate and provide a platform for beekeepers to manage their hives and apiaries

We have added several links to the main page of the application most are described in the controller. The latest addition to the application is the return of access to the old database table for herbs that from the point of view of BMaster is the Bee pasture view. The BeePastureView give a current list of all the plants that are used by pollinators as pasture.

searchHerbs

The search field now works if the search string appears in the record it is returned. to the browser in a list. The details link pulls all the data in the table.

Please look to the ency module for details on how this works.

The 'searchHerbs' function in the 'Comserv/lib/Comserv/Model/DBForager.pm' file has been updated to improve the search functionality in the BMaster system. The function now uses normalized field names that match the field names in the database and the view. It also stores all debug messages in an array and puts that array into the stash, allowing all debug messages to be passed to the template and displayed in the browser. In the case where no records are returned from the search, a specific debug message stating "No results found" is added to the debug messages array.

Back to top BMaster

BMaster Controller Documentation

base

The 'base' function is the root of the chained actions in the BMaster controller. It captures '/BMaster' in the URL and performs common setup tasks that are shared by multiple actions in the controller. Here are some examples of what the 'base' function can do:

• Loading Model Data: If multiple actions in the BMaster controller need to access the same data from the BMaster model, this data can be loaded in the 'base' function and stored in the stash for other actions to use.
• Checking User Permissions: If multiple actions in the BMaster controller require the user to have certain permissions, these permissions can be checked in the 'base' function. If the user does not have the required permissions, they can be redirected to an error page.
• Setting Common Template Variables: If multiple actions in the BMaster controller use the same template variables, these variables can be set in the 'base' function.

By performing these common setup tasks in the 'base' function, we can avoid duplicating code in multiple actions, making the code more maintainable and easier to understand.

index

This function sets the template to 'BMaster/BMaster.tt' and forwards to the TT view.

frames

This function gets the frames for the given queen and sets the template to 'BMaster/frames.tt'.

api_frames

This function fetches the data for the frames and sets the response body to the JSON representation of the data.

products

This function sets the template to 'BMaster/products.tt'.

yards

This function gets the yards and sets the template to 'BMaster/yards.tt'.

apiary

This function sets the template to 'BMaster/apiary.tt'.

queens

This function sets the template to 'BMaster/Queens.tt'.

hive

This function sets the template to 'BMaster/hive.tt'.

honey

This function sets the template to 'BMaster/honey.tt'.

beehealth

This function sets the template to 'BMaster/beehealth.tt'.

environment

This function sets the template to 'BMaster/environment.tt'.

education

This function sets the template to 'BMaster/education.tt'.

Back to top BMaster

BMaster Model Documentation

get_frames_for_queen

This function fetches the frames for a given queen based on the queen's tag number. It returns a reference to an array of frames.

get_yards_for_site

This function fetches all yards for a given site based on the site's name. It returns a reference to an array of yards.

Back to top BMaster

Queen Management System

Our queen management system is designed to manage the lifecycle of the queen bees in our apiary. Here are the key activities and their timelines:

We store the graft date and the number of days of egg laying in the database. This helps us to track and manage the lifecycle of each queen bee.

Back to top of Documentation

Calendar Module:

Overview:

The Calendar module is a web-based calendar that can be used by all other modules in the application for scheduling and event management. It provides features such as creating, viewing, and editing events, setting reminders, and sharing events with other users.

Features:

The Calendar module provides the following features:

• Creating, viewing, and editing events
• Setting reminders
• Sharing events with other users
• Integration with other modules for scheduling and event management

Usage:

Here's how to use the Calendar module:

Development Plan:

Here's a detailed plan for the development of the calendar module in Catalyst:

1. Database Schema:

Define a database schema for the calendar events. This schema will be used to create a table in your database. The table includes fields such as `event_id`, `event_name`, `start_date`, `end_date`, `description`, `location`, `organizer`, `attendees`, `status`, `last_modified_by`, `last_mod_date`, and `user_id`.

To create this schema, you can use the Catalyst helper scripts. Here are the steps:

1. First, create a new Catalyst model using the `comserv_create.pl` script. This script will generate a new model class in your application. For example:

    script/comserv_create.pl model Calendar DBIC::Schema Comserv::Schema::Ency::Result create=static `perl -MComserv::Model::DBEncy -e 'print Comserv::Model::DBEncy->config->{connect_info}->{dsn}'`
    

In this command, `Calendar` is the name of the model, `DBIC::Schema` specifies that we're creating a DBIx::Class schema, `Comserv::Schema::Ency::Result` is the namespace of the schema, `create=static` tells the script to create a static schema, and the Perl one-liner is used to retrieve the DSN from `DBEncy.pm`.

2. Next, define your schema in the generated model class. Here's an example:

    package Comserv::Model::Schema::Ency::Result::Event;

    use base 'DBIx::Class::Core';

    __PACKAGE__->table('event');
    __PACKAGE__->add_columns(
        event_id => {
            data_type => 'integer',
            is_auto_increment => 1,
        },
        event_name => {
            data_type => 'varchar',
            size => 255,
        },
        start_date => {
            data_type => 'date',
        },
        end_date => {
            data_type => 'date',
        },
        description => {
            data_type => 'text',
        },
        location => {
            data_type => 'varchar',
            size => 255,
        },
        "organizer",
        { data_type => "varchar", default_value => "", is_nullable => 1, size => 50 },
        "attendees",
        { data_type => "text", is_nullable => 1 },
        status => {
            data_type => 'varchar',
            size => 255,
        },
        "last_modified_by",
        { data_type => "varchar", default_value => "", is_nullable => 1, size => 50 },
        last_mod_date => {
            data_type => 'date',
        },
        user_id => {
            data_type => 'integer',
        },
    );
    __PACKAGE__->set_primary_key('event_id');
    __PACKAGE__->belongs_to(user => 'Comserv::Model::Schema::Ency::Result::User', 'user_id');
    

This code defines an `event` table with fields such as `event_id`, `event_name`, `start_date`, `end_date`, `description`, `location`, `organizer`, `attendees`, `status`, `last_modified_by`, `last_mod_date`, and `user_id`.

3. Finally, use the `deploy` method on your schema object to create the table in your database. For example:

    my $schema = $c->model('Calendar')->schema;
    $schema->deploy;
    

This code should be run in a script or controller action that has access to your Catalyst context (`$c`).

To create the table directly in the database using SQL, you can use the following SQL command:

2. Catalyst Model (Calendar.pm):

We have created a Catalyst model named `Calendar` that extends `Comserv::Model::DBEncy` and adds custom methods to interact with the Calendar related tables. Currently, it has a method `get_events` that fetches events from the 'Event' table that match a given search criteria.

3. Catalyst Controller (Calendar.pm):

Create a Catalyst controller with actions for creating, reading, updating, and deleting events.

4. Catalyst View (Calendar.tt):

Create a Catalyst view to display the events in a calendar format.

5. Authentication and Authorization:

Use the existing `User` and `Admin` modules to handle authentication and authorization. If necessary, restrict access to certain actions (for example, only logged-in users can create events).

6. Prebuilt Applications:

There are several Perl modules on CPAN that might be useful. `Data::ICal` can generate iCalendar files, and `DateTime::Event::ICal` can calculate dates based on iCalendar recurrence rules.

Please note that this is a high-level plan and the actual implementation might require additional steps or modifications.

Back to top of Documentation

Document Management

Back to top of Commandment Management

DBI Setup for AutoCRUD Integration

With the integration of `Catalyst::Plugin::AutoCRUD`, we enhance our database operations by providing an automatic CRUD interface for managing content within our Catalyst application, 'Comserv'.

AI features will further enhance the capabilities of AutoCRUD, allowing for intelligent data management and user interactions.

Integration Plan for AutoCRUD

Step 1: Setup & Configuration

• Install AutoCRUD: Use CPAN or your preferred method to install `Catalyst::Plugin::AutoCRUD`.
• Update Catalyst Configuration: add into Conserv.pmS

  
  use Catalyst qw/
      ConfigLoader
      Static::Simple
      AutoCRUD
  /;
  
  PACKAGE->config(
      name => 'Comserv',
      'Plugin::AutoCRUD' => {
          login_url => /user/login',
          logout_url => '/user/logout',
          # More configurations as per your needs
      },
  );
  
  PACKAGE->setup;
  

Step 2: Database Schema Migration

• Define New Schema: Use `DBIx::Class::Schema::Loader` to generate Object-Relational Mapping (ORM) classes from your existing database schema. Adjust these classes to normalize the data structure:

  
  script/comserv_create.pl model DB::PageSchema DBIx::Class::Schema::Loader create=static dbi:mysql:database=ComservDb root password
  

• Normalize Data:
  • Create separate tables for pages, content, metadata, etc., to break down the monolithic 'page.db' structure.
  • Define relationships between these tables in your schema classes.
• Data Migration:
  • Write a Perl script to read from the old `page.db` table and insert data into the new normalized schema:

  
  use DBI;
  use Comserv::Model::DB::PageSchema;
  
  Connect to old database
  my $dbh_old = DBI->connect("dbi:mysql:dbname=old_db", "username", "password") or die $DBI::errstr;
  
  Connect to new database using ORM
  my $schema = Comserv::Model::DB::PageSchema->connect($c->config->{Model::DB::PageSchema}->{connect_info});
  
  Fetch all data from old table
  my $sth = $dbh_old->prepare("SELECT * FROM page");
  $sth->execute();
  
  while (my $row = $sth->fetchrow_hashref) {
      # Convert old data to fit new schema
      my $page = $schema->resultset('Page')->create({
          title => $row->{title},
          content => $row->{content},
          # Map other fields accordingly
      });
      # Handle links or other nested data here
  }
  
  Cleanup
  $sth->finish;
  $dbh_old->disconnect;
  

Step 3: Implement CRUD Operations

• Define Access: Ensure that AutoCRUD has the necessary permissions to interact with your new schema.
• Create CRUD Controllers: Let AutoCRUD generate basic Create, Read, Update, and Delete (CRUD) controllers for your models, which you can customize further:

  
  $c->action_namespace("")->auto_crud({
      resultset => 'Page',
      columns => [qw/id title content/],
      # Further customization options
  });
  

Step 4: Testing & Deployment

• Test the CRUD Interface: Ensure all operations work as expected, especially with the migrated normalized data.
• Deployment: Update your deployment scripts to include the new schema and AutoCRUD configurations.

Step 5: Update Documentation & Training

• Document New Processes: Update this document and any other relevant documentation to reflect changes in database structure and management.
• Training: Train content editors on the new system, focusing on the web-based CRUD operations provided by AutoCRUD.

Debugging

Continue using the existing debugging setup, and add AutoCRUD-specific debugging where necessary.

Security

Ensure that security measures are maintained or enhanced, particularly focusing on data integrity and access control with the new schema setup.

Catalyst Integration

The `DB::PageSchema` module now integrates with Catalyst to manage page content through AutoCRUD, using the Catalyst context for session management and other features.

For further enhancements using Artificial Intelligence (AI), please refer to the AI Integration Plan.

Back to top of Documentation

ENCY Module

ENCY Controller

Return to top

index

The index subroutine handles requests to the root of the ENCY controller's URL. It sets the template to 'ENCY/index.tt', which is used to render the response.

sub index :Path('/ENCY') :Args(0) {
    my ( $self, $c ) = @_;
    # The index action will display the 'index.tt' template
    $c->stash(template => 'ENCY/index.tt');
}

Return to top

botanical_name_view

The botanical_name_view subroutine handles requests to display the Botanical Name View page. It fetches herbal data from the 'DBForager' model and passes this data to the template.

sub botanical_name_view :Path('/ENCY/BotanicalNameView') :Args(0) {
    my ( $self, $c ) = @_;

    # Fetch the herbal data
    my $forager_data = $c->model('DBForager')->get_herbal_data();

    # Pass the data to the template
    my $herbal_data = $forager_data;
    $c->stash(herbal_data => $herbal_data, template => 'ENCY/BotanicalNameView.tt');
}

Return to top

herb_detail

The herb_detail subroutine handles requests to display detailed information about a specific herb. It takes an id as an argument, fetches the corresponding herb from the 'DBForager' model, and sets the herb and the template 'ENCY/HerbDetailView.tt' in the stash.

sub herb_detail :Path('/ENCY/herb_detail') :Args(1) {
    my ( $self, $c, $id ) = @_;
    my $herb = $c->model('DBForager')->get_herb_by_id($id);
    $c->stash(herb => $herb, template => 'ENCY/HerbDetailView.tt');
}

Return to top

get_reference_by_id

The get_reference_by_id subroutine handles requests to get a reference by its id. It takes an id as an argument, fetches the corresponding reference from the 'ENCY' model, and sets the reference and the template 'ency/get_reference_form.tt' in the stash.

sub get_reference_by_id :Local {
    my ( $self, $c, $id ) = @_;
    # Fetch the reference using the ENCY model
    my $reference = $c->model('ENCY')->get_reference_by_id($id);
    $c->stash(reference => $reference);
    $c->stash(template => 'ency/get_reference_form.tt');
}

Return to top

create_reference

The create_reference subroutine handles requests to display the form for creating a new reference. It sets the template 'ency/create_reference_form.tt' in the stash.

sub create_reference :Local {
    my ( $self, $c ) = @_;
    # Display the form for creating a new reference
    $c->stash(template => 'ency/create_reference_form.tt');
}

Return to top

get_category_by_id

The get_category_by_id subroutine handles requests to get a category by its id. It takes an id as an argument, fetches the corresponding category from the 'ENCY' model, and sets the category and the template 'ency/get_category_form.tt' in the stash.

sub get_category_by_id :Local {
    my ( $self, $c, $id ) = @_;
    # Fetch the category using the ENCY model
    my $category = $c->model('ENCY')->get_category_by_id($id);
    $c->stash(category => $category);
    $c->stash(template => 'ency/get_category_form.tt');
}

Return to top

For more information on how AI can enhance the functionalities of the ENCY module, refer to the AI Integration Plan.

create_category

The create_category subroutine handles requests to display the form for creating a new category. It sets the template 'ency/create_category_form.tt' in the stash.

sub create_category :Local {
    my ( $self, $c ) = @_;
    # Display the form for creating a new category
    $c->stash(template => 'ency/create_category_form.tt');
}

Return to top

Each of these subroutines relies on the ENCY model to perform its tasks. The ENCY model is loaded in the ENCY controller with the use Comserv::Model::ENCY; statement. The ENCY model is defined in the 'Comserv::Model::ENCY' package, which is located in the 'lib/Comserv/Model' directory.

Return to top

Future Development

To evolve the ENCY application, consider the following enhancements:

• Improved Data Validation: Implement stricter data validation and error handling in all subroutines to ensure data integrity and provide better user feedback.
• Enhanced User Interface: Develop more interactive and user-friendly templates, possibly integrating JavaScript frameworks for a better user experience.
• API Integration: Create RESTful API endpoints to allow external applications to interact with the ENCY data, enabling wider access and integration.
• Search and Filtering: Add advanced search and filtering capabilities to allow users to find specific information more efficiently.
• Automated Data Updates: Implement automation for data updates from trusted sources to keep the information current and accurate.
• User Contributions: Develop features that allow users to contribute data and corrections, with moderation workflows to ensure quality.

ENCY Model

ENCY Model

The ENCY model is responsible for handling data related to the ENCY controller. It includes several methods, each of which performs a specific task.

Return to top

get_reference_by_id

The 'get_reference_by_id' method is responsible for fetching a reference by its id. It takes an id as an argument, fetches the corresponding reference from the database, and returns the reference.

Return to top

create_reference

The 'create_reference' method is responsible for creating a new reference. It takes the necessary data as arguments, creates a new reference in the database, and returns the new reference.

Return to top

get_category_by_id

The 'get_category_by_id' method is responsible for fetching a category by its id. It takes an id as an argument, fetches the corresponding category from the database, and returns the category.

Return to top

create_category

The 'create_category' method is responsible for creating a new category. It takes the necessary data as arguments, creates a new category in the database, and returns the new category.

Return to top

Each of these methods is used by the ENCY controller to perform its tasks. The ENCY model is defined in the 'Comserv::Model::ENCY' package, which is located in the 'lib/Comserv/Model' directory.

Return to top

Back to top of Documentation

Files

To handle file uploads from multiple users and ensure that each user can only access their own uploaded files, you can follow these steps:

1. When a user uploads a file, save the file in a user-specific directory. The directory can be named after the user's unique ID or username to ensure it's unique for each user.
2. When serving files, check if the requested file is in the directory corresponding to the currently logged-in user. If it is, serve the file. If not, return an error or redirect the user.
3. setfacl -m u:starman_user:rwx /path/to/user/directory/starman Yes, you can automate the process of creating the directory and setting its permissions when a new user is created in Virtualmin. You can do this by adding a script to the "Post-creation script" field in the Server Templates settings. Here's a basic example of what the script could look like: ```bash #!/bin/bash # Create the directory mkdir -p /home/${USER}/public_html/starman # Set the permissions setfacl -m u:starman_user:rwx /home/${USER}/public_html/starman ``` This script will create a 'starman' directory in the 'public_html' directory of the new user's home directory and then set the necessary permissions for the 'starman_user'. Please replace 'starman_user' with the actual username of the user under which the Starman server is running. To add this script to the Server Template: 1. Go to Virtualmin > System Settings > Server Templates. 2. Select the template you want to modify. 3. In the Edit Server Template page, find the "Post-creation script" field under the "Actions upon server and user creation" section. 4. Enter the full path to your script in this field. Now, whenever a new virtual server is created using this template, the script will be executed. Remember to make your script executable by running `chmod +x /path/to/your/script.sh`. Please note that this is a basic example and you might need to adjust it according to your specific needs and environment.
4. Here's how you can modify the `handle_upload` method in the `Comserv::Model::File` model to implement this: ```perl5 sub handle_upload { my ($self, $c, $upload) = @_; # Extract the file's name and size my $filename = $upload->filename; my $filesize = $upload->size; # Define the allowed file types and maximum file size my @allowed_types = ('.jpg', '.png', '.pdf'); # adjust as needed my $max_size = 10 * 1024 * 1024; # 10 MB # Check the file type my ($file_type) = $filename =~ /(\.[^.]+)$/; unless (grep { $_ eq $file_type } @allowed_types) { return "Invalid file type. Allowed types are: " . join(", ", @allowed_types); } # Check the file size if ($filesize > $max_size) { return "File is too large. Maximum size is $max_size bytes."; } # Get the user's unique ID or username my $user_id = $c->user->id; # adjust this line to match your authentication system # Create a directory for the user if it doesn't exist my $directory = "uploads/$user_id"; unless (-d $directory) { mkdir $directory or return "Failed to create directory: $!"; } # Create the full path for the new file my $filepath = "$directory/$filename"; # Save the uploaded file my $result = $upload->copy_to($filepath); return $result ? "File uploaded successfully." : "Failed to upload file."; } ``` This code will save each user's uploaded files in a separate directory. When serving files, you would use a similar approach to check if the requested file is in the directory corresponding to the currently logged-in user. To implement access control in a Catalyst application, you can create a method in your controller that checks if the requested file is in the directory corresponding to the currently logged-in user. If it is, serve the file. If not, return an error or redirect the user.
5. Here's a basic example of how you might implement this in your `Comserv::Controller::File` controller: ```perl5 sub serve_file :Local { my ($self, $c, $filename) = @_; # Get the user's unique ID or username my $user_id = $c->user->id; # adjust this line to match your authentication system # Create the full path for the requested file my $filepath = "uploads/$user_id/$filename"; # Check if the file exists and is readable if (-f $filepath && -r _) { # Serve the file $c->res->header('Content-Type' => 'application/octet-stream'); $c->res->body(scalar read_file($filepath, binmode => ':raw')); } else { # Return an error or redirect the user $c->res->status(403); # Forbidden $c->res->body('You do not have permission to access this file.'); } } ``` In this example, the `serve_file` method is a new action in your `Comserv::Controller::File` controller. It gets the requested filename from the URL, constructs the full path to the file based on the currently logged-in user's ID, and checks if the file exists and is readable. If it is, it serves the file to the user. If not, it returns a 403 Forbidden error. This is a very basic example and doesn't include any error handling or security measures. In a real application, you would want to add checks to ensure the filename is safe to use in a file path, the user is authenticated, and the user has permission to access the file.

Back to top of Documentation

Comserv Development Guidelines

Patch Format

When providing code returns, always use the `+-` patch format to prevent overwriting existing functions. This ensures that changes are clear and maintainable.

Catalyst Coding Standards

Follow these standards when coding in Catalyst:

• Use Moose for object-oriented programming.
• Keep controllers slim by moving business logic to models.
• Use clear and descriptive names for actions and methods.
• Implement error handling gracefully.

Testing Guidelines

Ensure that your code is thoroughly tested, including testing for both .tt templates and the underlying code. Some key points to consider:

• Review .tt templates for proper syntax and ensure all necessary variables are passed correctly.
• Write unit tests to validate the behavior of individual functions and methods.
• Run integration tests to ensure the application components work together as expected.
• Implement automated testing frameworks to catch regressions early in the development process.

Back to top

Documentation Standards

Keep the documentation up-to-date and comprehensive. Ensure that all changes to the codebase are reflected in the corresponding documentation sections.

Back to top

Git Workflow

A Git workflow refers to the agreed-upon process for how developers should use Git to manage code changes, collaborate on features, and maintain the codebase. The key elements of the recommended Git workflow for this project are:

• Establish a clear branching strategy:
  • Guidelines for when to create new feature branches:
    • Create a new feature branch for each new feature or bug fix. This helps in isolating changes and makes it easier to manage and review code.
    • Start a feature branch from the latest version of the main development branch to ensure you have the most recent updates.
    • Use feature branches for experimental work that might not be ready for production.
  • How to name branches:
    • Use descriptive names that reflect the purpose of the branch, such as `feature/login-page` or `bugfix/user-authentication`.
    • Include identifiers like ticket numbers or issue IDs if applicable, e.g., `feature/1234-login-page`.
    • Maintain consistency in naming conventions across the team to avoid confusion.
  • Managing merging back into the main development branch:
    • Before merging, ensure your feature branch is up-to-date with the main development branch by regularly pulling the latest changes.
    • Resolve any conflicts that arise during the merge process to ensure a smooth integration.
    • Conduct code reviews and obtain necessary approvals before merging to maintain code quality and consistency.
    • Use pull requests to facilitate discussion and review of the changes before they are merged into the main branch.
    • Guidelines for deleting or keeping a branch after merging:
      • Delete a branch after merging if:
        • The feature or bug fix is complete and no further changes are expected.
        • Keeping the branch would clutter the repository with obsolete branches.
      • Keep a branch after merging if:
        • Further development or bug fixes are anticipated on the same feature.
        • The branch serves as a reference for ongoing or related work.
• Provide guidance on writing clear and informative commit messages:
  • Explain the purpose and scope of each change.
• Document the process for submitting changes for review:
  • Creating pull requests.
  • Getting approvals from other team members.
• Describe the steps for merging approved changes into the main branch:
  • Include any necessary testing or deployment procedures.
• Emphasize the importance of keeping the codebase clean and well-organized:
  • Regularly remove obsolete branches and commits.

Follow the established Git workflow for the project, including regular commits with meaningful messages and the use of feature branches for new developments.

Back to top

Back to top

Security Guidelines

Back to top

Completed Items

• Created the Git Workflow guidelines section
• Added the Testing Guidelines section

Session Planning

When planning your sessions, please follow these guidelines:

1. Please read sessionplan.tt.
2. Compare the current prompt and the plan you would create for it with the session plan.
3. Modify the current session plan to incorporate the plan you just created.

Example Prompt

When reminding the assistant, you can say: "Please follow the guidelines outlined in guidelines.tt, especially regarding the `+-` patch format for code returns and the prohibition on using placeholders in code returns."

Back to top of Documentation

Git Usage Guide for PyCharm

PyCharm Git Integration

1. Enable Version Control:
   • Go to VCS → Enable Version Control Integration
   • Select "Git" from the dropdown menu
2. Commit Changes:
   • Use Alt+0 (Command+0 on Mac) to open the Commit tool window
   • Select changed files to commit (e.g., Forager.pm)
   • Write a descriptive commit message (e.g., "Add Forager controller for handling forager.com routes")
   • Click "Commit" or "Commit and Push"

Common Workflows

Adding New Features to Production

1. Create a New Branch:

   git checkout -b feature/forager-controller

2. Add and Commit Changes:

   git add Forager.pm
   git commit -m "Add Forager controller for handling forager.com routes"

3. Push to Remote:

   git push origin feature/forager-controller

4. Deploy to Staging for Testing:
   • Use your deployment tool to push to staging environment
   • Test thoroughly for correct site information and route handling
5. Merge to Development/Staging:
   • Create a Pull Request if using GitHub or similar
   • Or directly merge:

     git checkout development
     git merge feature/forager-controller

6. Final Test on Staging:
   • Re-run tests to ensure no issues post-merge
7. Merge to Production:

   git checkout production
   git merge development
   git push origin production

8. Monitor Post-Deployment:
   • Watch for any live site issues

Remove .idea Directory from a Git Branch

1. Fetch the branch from the remote repository:

   git fetch origin branch_name:branch_name

2. Remove the .idea directory from your local working directory:

   rm -rf .idea

3. Switch to the fetched branch:

   git checkout branch_name

4. Remove the .idea directory and commit the change:

   git rm -r .idea
   git commit -m "Remove .idea directory"

5. Push the changes to the remote branch:

   git push origin branch_name

Replace branch_name with the name of the branch you want to remove the .idea directory from.

Troubleshooting Common Issues

• If PyCharm doesn't detect Git:
  1. Go to Settings/Preferences → Version Control → Git
  2. Verify the path to Git executable

Back to top of Documentation

Installation Guide

Module Installation with Perlbrew

1. Switch to Perl 5.40.0:

   perlbrew switch perl-5.40.0

2. Ensure PATH includes Perlbrew's bin:

   echo $PATH

   Ensure `/home/comserv/perl5/perlbrew/bin` and `/home/comserv/perl5/perlbrew/perls/perl-5.40.0/bin` are included.
3. Set up local::lib for user-level installations:

   cpanm --local-lib=~/perl5 local::lib && eval $(perl -I ~/perl5/lib/perl5 -Mlocal::lib)

   Add this to your shell configuration file (e.g., `.bashrc` or `.zshrc`) for persistence across sessions.
4. Check Perl library paths:

   perl -e 'print join "\n", @INC'

   Verify paths like `/home/comserv/perl5/perlbrew/perls/perl-5.40.0/lib/site_perl/5.40.0` are listed.
5. Install Dependencies from cpanfile:

   cpanm --installdeps .

   This command reads your `cpanfile` and installs all listed dependencies
6. Create a directory for Comserv:

   mkdir /path/to/Comserv

7. Clone the repository into the created directory:

   git clone git@github.com:comserv2/Comserv.git /path/to/Comserv

8. Navigate to the cloned directory:

   cd /path/to/Comserv

9. Install required modules from cpanfile:

   cpan
       
   Install required modules using cpanfile:
           
   cd /path/to/Comserv
   cpanm --installdeps .
       
       
   Verify installations:
           
   perl -MModule::Name -e 'print $Module::Name::VERSION'