Welcome to the DjangoForge User Manual! DjangoForge is a Django-based project, designed to streamline deployment and enhance business operations for small to medium-sized enterprises (SMEs). This manual provides comprehensive guidance on how to deploy and maintain the project using GitHub Actions.

DjangoForge is built around a tiered architecture, offering a scalable solution tailored to various business needs:

1. Base Project: Core functionality and generic apps that serve as the foundation of the ecosystem.
2. Tier 1 Applications: Common business apps such as CRM, ERP, and inventory management that build on the Base Project.
3. Tier 2 Applications: Industry-specific extensions, providing advanced features and customizations.

• Framework: Django
• Databases:
  • Default: Primary database for raw data storage.
  • Gold: Business intelligence database for refined and aggregated data.
• Containerization: Managed with Docker and Docker Compose for both development and production environments.
• CI/CD: Automated with GitHub Actions for seamless deployment to cloud services like Digital Ocean, with plans for future PaaS integration.

• Purpose: Collects and aggregates logs for HTTP requests and errors.
• Key Components:
  • Models: base.py, aggregated.py
  • Tasks: aggregate_access_logs.py, aggregate_error_logs.py
  • Views: base.py, aggregated.py

• Purpose: Manages the website frontend and acts as a basic CMS.
• Planned Updates: Streamlining to focus on static page rendering.

• Purpose: Provides backend management tools and data visualization.
• Planned Updates: Modularization and integration with Gold BI for enhanced data insights.

• Purpose: Handles ETL (Extract, Transform, Load) processes and task scheduling using Django Q.
• Planned Updates: Enhanced task scheduling capabilities.

1. On the GitHub repository page, click "Use this template."
2. Create a new repository based on the template.

git clone --recursive https://github.com/your-username/your-new-repo.git your-new-repo
cd your-new-repo
git remote add template https://github.com/leoBitto/DjangoForge.git
git remote add origin https://github.com/your-username/your-new-repo.git

To fetch updates from DjangoForge:

git fetch --all
git merge template/main --allow-unrelated-histories

1. Clone the required apps as submodules into the src directory.

   git submodule add <URL to submodule> src/<name of app>

2. Update settings.py to include your apps, and modify urls.py accordingly. Use git add, git commit, and git push to save changes.

The manager.sh script simplifies project management:

• source manager.sh build: Builds and starts containers, applies migrations, runs collectstatic, and prompts for superuser creation.
• source manager.sh start: Starts containers.
• source manager.sh stop: Stops containers.
• source manager.sh destroy: Destroys containers.

After building, the application will be accessible at http://localhost.

• GitHub account
• DigitalOcean account (or similar IaaS provider)

Tip: Begin with Django's development server for initial testing before moving to Docker.

Warning: Update the IMAGE_NAME in the CI/CD workflow files to control the image name displayed in GitHub's packages tab.

1. Log in to DigitalOcean.
2. Navigate to "Droplets" and click "Create Droplet."
3. Configure options (distribution, size, datacenter, etc.).
4. Choose "SSH Key" for authentication, and select/create an SSH key pair.
5. Click "Create Droplet."

Note: DigitalOcean is used here as an example; other IaaS providers are also supported.

1. Generate an SSH key pair:

   ssh-keygen -t ed25519 -C "[email protected]"

2. Add your private key to the ssh-agent:

   eval "$(ssh-agent -s)"
   ssh-add ~/.ssh/id_ed25519

3. Copy your public key:

   cat ~/.ssh/id_ed25519.pub

4. Add this public key to your GitHub account and save the private key as a GitHub secret under "Settings" -> "Secrets."

Add the following secrets to your GitHub repository:

• DEBUG: False
• DOMAIN: Your domain or IP address
• EMAIL: Valid email for SSL
• GHCR_TOKEN: GitHub token
• HOST: Droplet IP address
• POSTGRES_DB: Database name
• POSTGRES_PASSWORD: Database password
• POSTGRES_USER: Database user
• PRIVATE_KEY: Server private key
• SECRET_KEY: Django secret key
• USERNAME: root

Important: Ensure that the IMAGE_NAME in build-and-push.yml is lowercase.

Once the secrets are configured, manually start the workflow in server_setup.yml to set up the server, providing domain names or IP addresses for SSL configuration via Certbot.

• Project Purpose: Centralize and automate data management for SMEs using Business Intelligence (BI).
• Target Users: SMEs in sectors like distribution, restaurants, and craft industries.
• Philosophy: Democratize access to BI tools, making them affordable and scalable for businesses of all sizes.

• Logging App: Aggregates and manages logs.
• Website App: Basic CMS for frontend management.
• Backoffice App: Tools for backend management.
• Gold BI: ETL processing and task scheduling with Django Q.

• Components interact through Django's native functionality, ensuring seamless communication across apps.

Docker Configuration:

• Dockerfile: Builds the app image, installs dependencies, and configures the Gunicorn server.
• Docker Compose for Development (docker-compose.dev.yml):
  • Services: Includes web, djangoq, db, db_gold, and nginx.
  • Volumes: Persist data like databases and media files.
  • Network: Bridges services for internal communication.

Management Script (manager.sh):

• Simplifies common tasks like building, starting, stopping, and destroying containers.

Docker Compose for Production (docker-compose.prod.yml):

• Similar to the development setup, but tailored for production with pre-built Docker images and secure configurations.

The backoffice app offers a comprehensive administrative interface, integrating tools from the logging_app and gold_bi for consistent UI and data management.

• Template: backoffice_base.html for consistent layout.
• Views: Includes a dashboard requiring authentication.
• URLs: Mapped in backoffice/urls.py.
• Dependencies: Utilizes Bootstrap, DataTables, HTMX, and FontAwesome for a modern, interactive interface.

• Accessible by logging in, with users directed to the main dashboard for app management.

The gold_bi app manages ETL processes and data aggregation, using Django Q for task scheduling.

• Models, Views, Forms: Handles data management and user interactions. Models defined here are for aggregated informations that require models from more than 1 app Views define the views that allow to choose the type of report you want Forms define the structure to give information to views regardin the report type
• Task Scheduling: Managed via tasks_scheduler.py with scheduling using Django Q.

The logging_app tracks and manages access and error logs.

• Middleware: Ensure it’s added to MIDDLEWARE in settings.py.
• Periodic Tasks: Set up with Celery or Django Q for log aggregation.

• Views: Handle log listing and details.
• Templates: Include base and detailed log views.

• URL Configuration: Defined in urls.py.
• Static Assets: CSS and JS should be included in the static directory.

The website app provides basic CMS functionality for managing frontend content.

• Templates and Views: Manage content display and user interactions.
• URLs: Define routes for different pages.

• **Static and Media Files

**: Managed via Django settings.

• Authentication: Implement admin access for content management.

For further assistance or to report issues, please refer to the DjangoForge GitHub repository or contact support.