Skip to main content
This guide will help you set up Checawaa on your local machine for development and testing.

​
Prerequisites

Before you begin, ensure you have the following installed on your system:

Python 3.8+

Download from python.org

pip

Usually included with Python installation

Git

Download from git-scm.com

Code Editor

VS Code, PyCharm, or your preferred editor

​
Installation Steps

1

Clone the Repository

Clone the Checawaa repository to your local machine:
git clone https://github.com/your-username/checawaa.git
cd checawaa
2

Create a Virtual Environment

Create an isolated Python environment for the project:
python3 -m venv venv
source venv/bin/activate
You should see (venv) appear at the beginning of your terminal prompt, indicating the virtual environment is active.
3

Install Dependencies

Install all required Python packages from requirements.txt:
pip install -r requirements.txt
This will install:
  • Flask - Web framework
  • geopy - Geocoding library
  • gunicorn - WSGI HTTP server (for production)
Additional dependencies like flask-login, flask-mail, apscheduler, and reportlab are used by the application but may be installed as sub-dependencies.
4

Install Additional Dependencies

The application requires several additional packages not listed in requirements.txt. Install them:
pip install flask-login flask-mail apscheduler reportlab
5

Configure Environment Variables

Create a .env file in the project root or set environment variables directly:
.env
SECRET_KEY=clave_secreta_muy_segura
MAIL_SERVER=smtp.gmail.com
MAIL_PORT=587
MAIL_USE_TLS=True
MAIL_USERNAME=[email protected]
MAIL_PASSWORD=your_app_password
For development, you can use the default values in app.py, but for production, always use environment variables.
See the Environment Variables guide for detailed configuration options.
6

Initialize Data Directory

The application will automatically create the data/ directory and initialize JSON files on first run:
mkdir -p data
The app creates usuarios.json and registros.json automatically with default data (see app.py:30-39).

​
Running the Application

​
Development Server

Start the Flask development server: 
python app.py
The application will start on http://localhost:5000 by default.
The app runs with debug=True and use_reloader=False to prevent the APScheduler from running twice during development (app.py:239).

​
Accessing the Application

Open your browser and navigate to: 
http://localhost:5000/login

​
Default User Accounts

The application comes with pre-configured test accounts (see app.py:32-34): 
{
  "username": "admin",
  "password": "123",
  "email": "[email protected]"
}

​
Development Workflow

​
Project Structure

checawaa/
├── app.py                 # Main application file
├── requirements.txt       # Python dependencies
├── Procfile              # Heroku deployment config
├── data/                 # JSON data storage
│   ├── usuarios.json     # User accounts
│   └── registros.json    # Attendance records
├── templates/            # HTML templates
│   ├── login.html
│   ├── index.html
│   └── monitor.html
└── static/              # Static assets (CSS, JS, images)

​
Key Application Features

Authentication System

Uses Flask-Login for session management (app.py:42-49)

Email Notifications

Configured with Flask-Mail to send automated reminders (app.py:15-21)

Scheduled Tasks

APScheduler sends reminders at 8:00 AM daily (app.py:88-91)

PDF Reports

Generate attendance reports with ReportLab (app.py:184-231)

​
Making Changes

  1. Edit the code in your preferred editor
  2. Save your changes
  3. The server may need to be restarted manually since use_reloader=False
  4. Refresh your browser to see changes
For automatic reloading during development, you can temporarily change use_reloader=False to use_reloader=True in app.py:239, but remember this will cause the scheduler to initialize twice.

​
Testing Email Functionality

​
Using Gmail

To test email sending with Gmail:
1

Enable 2FA

Enable two-factor authentication on your Google account
2

Generate App Password

Go to Google App Passwords and create a new app password
3

Update Configuration

Use the generated 16-character password in your MAIL_PASSWORD configuration
4

Test Sending

Use the admin monitor interface to manually trigger reminder emails

​
Alternative: Using MailHog

For local development without real email sending, consider using MailHog: 
# Update app.py or .env
MAIL_SERVER=localhost
MAIL_PORT=1025
MAIL_USE_TLS=False

​
Deactivating the Virtual Environment

When you’re done working: 
deactivate

​
Troubleshooting

Module Not Found Errors

Ensure your virtual environment is activated and all dependencies are installed:
pip install -r requirements.txt
pip install flask-login flask-mail apscheduler reportlab

Port Already in Use

If port 5000 is occupied, change the port in app.py:239:
app.run(host='0.0.0.0', port=5001, debug=True, use_reloader=False)

Permission Errors on data/

Ensure the application has write permissions:
chmod -R 755 data/

Scheduler Running Twice

This is expected with use_reloader=True. The app uses use_reloader=False by default to prevent duplicate scheduler instances (app.py:239).

​
Next Steps

Configure Environment

Set up production-ready configuration

Deploy to Heroku

Deploy your application to production

API Reference

Explore available endpoints

Admin Guide

Learn how to manage users and attendance

Build docs developers (and LLMs) love

Get started for freeTalk to us