Skip to main content

​
Overview

This guide will walk you through deploying Checawaa and completing your first successful login and attendance check-in. By the end, you’ll have:
  • A running Checawaa instance
  • Admin and employee accounts configured
  • Your first GPS-verified attendance record
This quick start focuses on getting you up and running fast. For detailed local development setup, see the Installation Guide.

​
Prerequisites

Before you begin, ensure you have:
  • Python 3.7 or higher installed
  • A Gmail account for sending automated email reminders
  • A device with GPS capability (for testing check-ins)

​
Step 1: Get the Code

1

Clone or download the repository

# If using git
git clone <your-repo-url>
cd checawaa

# Or extract from downloaded zip
unzip checawaa.zip
cd checawaa
2

Verify the structure

Your directory should contain:
checawaa/
├── app.py
├── requirements.txt
├── Procfile
├── data/
├── templates/
└── static/

​
Step 2: Install Dependencies

Install the required Python packages: 
pip install flask flask-login flask-mail apscheduler reportlab
Using a virtual environment is recommended to avoid conflicts with other Python projects:
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install flask flask-login flask-mail apscheduler reportlab

​
Step 3: Configure Email Notifications

Checawaa sends automated reminder emails to employees who haven’t checked in by 8:00 AM. You need to configure Gmail SMTP:
1

Open app.py in your editor

Locate the email configuration section around line 16:
app.py
app.config['MAIL_SERVER'] = 'smtp.gmail.com'
app.config['MAIL_PORT'] = 587
app.config['MAIL_USE_TLS'] = True
app.config['MAIL_USERNAME'] = '[email protected]'
app.config['MAIL_PASSWORD'] = 'mcgc unmv wkci dbrr'
2

Update with your Gmail credentials

Replace the MAIL_USERNAME and MAIL_PASSWORD with your Gmail address and app password.
Important: Use a Gmail App Password, not your regular Gmail password. App passwords are more secure and work without 2FA issues.
app.py
app.config['MAIL_USERNAME'] = '[email protected]'
app.config['MAIL_PASSWORD'] = 'your-app-password-here'
3

Generate a Gmail App Password

  1. Go to your Google Account settings
  2. Navigate to Security → 2-Step Verification
  3. Scroll to “App passwords” at the bottom
  4. Generate a new app password for “Mail”
  5. Copy the 16-character password (without spaces)

​
Step 4: Configure Default Users

On first run, Checawaa creates a data/usuarios.json file with default accounts. You can customize these before starting:
data/usuarios.json
[
    { 
        "username": "admin", 
        "pass": "123", 
        "email": "[email protected]" 
    },
    { 
        "username": "employee1", 
        "pass": "123", 
        "email": "[email protected]" 
    }
]
Security Note: The default password "123" is for testing only. Change it immediately in production environments!
The system will auto-generate this file on first run if it doesn’t exist. You can also pre-create it to customize the initial users.

​
Step 5: Start the Server

Run Checawaa locally: 
python app.py
You should see output similar to: 
 * Running on http://0.0.0.0:5000
 * Restarting with stat
WARNING: Do not use the development server in production.
The server runs with use_reloader=False to prevent the automated scheduler from running twice. This is normal and expected.

​
Step 6: Your First Login (Employee)

1

Open the application

Navigate to http://localhost:5000/login in your web browser (use a device with GPS capability).
2

Log in as an employee

Use the default credentials:
  • Username: employee1
  • Password: 123
Click “Entrar” (Enter) to log in.
3

Grant GPS permission

When prompted, allow the browser to access your device location. This is required for attendance tracking.

​
Step 7: First Check-In

1

Start your shift

On the employee dashboard, you’ll see:
  • Welcome message with your username
  • “Iniciar Turno” (Start Shift) button
  • Last update timestamp
Click the “Iniciar Turno” button.
2

Verify tracking is active

After clicking, you should see:
  • Button becomes disabled
  • Message changes to “Rastreo activo (Cada 50 min)”
  • “Último reporte” updates with current time
The system now tracks your location every 50 minutes automatically. You can leave this tab open during your shift.

​
Step 8: View Admin Dashboard

Now let’s check the attendance from the admin perspective:
1

Log out from employee account

Click “Salir” (Exit) in the top-right corner.
2

Log in as admin

At the login screen, use:
  • Username: admin
  • Password: 123
3

Explore the dashboard

The admin panel (/monitor) displays:Attendance Table
  • Employee name with online indicator
  • Check-in date and time
  • Status badge (PUNTUAL or RETARDO)
Analytics Sidebar
  • Doughnut chart showing tardiness distribution
  • Total records count
  • System summary

​
Step 9: Test Key Features

Try these essential features:

​
Generate a PDF Report

Click the ”📥 Reporte PDF” button to download a comprehensive attendance report with:
  • Complete check-in history
  • Individual tardiness counts
  • Professional formatting

​
Send Manual Reminders

Click ”📧 Notificar Faltantes” to immediately send reminder emails to employees who haven’t checked in today.
This uses the same logic as the automatic 8:00 AM reminder, so it’s perfect for testing your email configuration.

​
Test Automatic Reminders

The system automatically sends emails at 8:00 AM to employees without check-ins. To test: 
# Find this line around line 90
scheduler.add_job(enviar_recordatorio_automatizado, 'cron', hour=8, minute=0)

# Change to trigger in 2 minutes (for testing)
scheduler.add_job(enviar_recordatorio_automatizado, 'cron', hour=CURRENT_HOUR, minute=CURRENT_MINUTE + 2)
Remember to restore the original hour=8, minute=0 after testing!

​
Understanding Attendance Status

Checawaa uses simple time-based rules:
Check-In TimeStatusBadge Color
Before 8:30 AMPUNTUAL (On Time)Green
After 8:30 AMRETARDO (Tardy)Red
The system checks hora > "08:30:00" to determine tardiness status (see app.py:149 and app.py:206).

​
Next Steps

You’ve successfully:
  • ✅ Deployed Checawaa locally
  • ✅ Completed your first employee check-in
  • ✅ Viewed the admin dashboard
  • ✅ Generated a PDF report

​
Continue Learning

Installation Guide

Set up for development with environment variables and production deployment

API Reference

Explore all available endpoints and integrations

Configuration

Customize reminder times, tardiness thresholds, and email templates

Deployment

Deploy to production with Heroku, Railway, or your own server

​
Troubleshooting

​
GPS Not Working

Make sure you’re accessing the site via HTTPS or localhost. Modern browsers restrict GPS access on insecure HTTP connections.

​
Email Not Sending

  1. Verify Gmail App Password is correct (no spaces)
  2. Check that “Less secure app access” is NOT enabled (use App Password instead)
  3. Review console output for specific error messages from Flask-Mail

​
”Activa el GPS” Alert

This means the browser couldn’t access GPS. Common causes:
  • Location permissions denied
  • Running on HTTP (not HTTPS) on a remote server
  • Device doesn’t have GPS hardware

​
Can’t Access Admin Dashboard

Ensure you’re logged in with the admin username. The system checks current_user.id != 'admin' and redirects non-admin users to the employee dashboard (see app.py:137-138).

Build docs developers (and LLMs) love

Get started for freeTalk to us