Installation

Overview

This guide covers everything you need to install and configure Checawaa, from local development setup to production deployment. Choose the path that fits your needs.

System Requirements

Minimum Requirements

Python: 3.7 or higher
Memory: 512 MB RAM (1 GB recommended)
Storage: 100 MB free space
Browser: Modern browser with GPS support (Chrome, Firefox, Safari, Edge)

Supported Platforms

Linux

Ubuntu, Debian, CentOS, RHEL

macOS

macOS 10.14 or later

Windows

Windows 10/11, Windows Server

Installation Methods

Local Development
Production Deployment

Perfect for testing, development, and customization.

Local Development Setup

Step 1: Clone the Repository

# Using Git
git clone <your-repository-url>
cd checawaa

# Or download and extract
unzip checawaa.zip
cd checawaa

Step 2: Create Virtual Environment

Using a virtual environment isolates Checawaa’s dependencies from your system Python:

# Create virtual environment
python3 -m venv venv

# Activate it
source venv/bin/activate

# Verify activation (you should see (venv) in your prompt)
which python

When activated, your terminal prompt will show (venv) at the beginning. This indicates all Python packages will be installed in this isolated environment.

Step 3: Install Dependencies

Checawaa’s dependencies are listed in requirements.txt:

requirements.txt

flask
geopy
gunicorn

The requirements.txt is minimal. The actual dependencies in app.py include: flask, flask-login, flask-mail, apscheduler, and reportlab. You’ll need to install all of them.

Install all required packages:

pip install flask flask-login flask-mail apscheduler reportlab geopy gunicorn

Or create a complete requirements.txt:

requirements.txt

flask>=2.3.0
flask-login>=0.6.2
flask-mail>=0.9.1
apscheduler>=3.10.0
reportlab>=4.0.0
geopy>=2.3.0
gunicorn>=21.0.0

Then install:

pip install -r requirements.txt

Step 4: Configure Environment Variables

Instead of hardcoding credentials in app.py, use environment variables for security:

Create a .env file

Create .env in your project root:

touch .env

Add your configuration

.env

# Flask Configuration
SECRET_KEY=your-secret-key-change-this-in-production
FLASK_ENV=development

# Email Configuration
MAIL_SERVER=smtp.gmail.com
MAIL_PORT=587
MAIL_USE_TLS=True
MAIL_USERNAME=[email protected]
MAIL_PASSWORD=your-gmail-app-password

# Scheduler Configuration (24-hour format)
REMINDER_HOUR=8
REMINDER_MINUTE=0

# Attendance Configuration
TARDY_THRESHOLD=08:30:00

Update app.py to use environment variables

Modify the configuration section in app.py:

app.py

import os
from dotenv import load_dotenv

load_dotenv()  # Load .env file

app = Flask(__name__)
app.secret_key = os.getenv('SECRET_KEY', 'fallback-key-for-dev')

# Email Configuration
app.config['MAIL_SERVER'] = os.getenv('MAIL_SERVER', 'smtp.gmail.com')
app.config['MAIL_PORT'] = int(os.getenv('MAIL_PORT', 587))
app.config['MAIL_USE_TLS'] = os.getenv('MAIL_USE_TLS', 'True') == 'True'
app.config['MAIL_USERNAME'] = os.getenv('MAIL_USERNAME')
app.config['MAIL_PASSWORD'] = os.getenv('MAIL_PASSWORD')

Install python-dotenv to load .env files: pip install python-dotenv

Never commit .env to version control! Add it to .gitignore:

.gitignore

.env
venv/
__pycache__/
*.pyc
data/*.json

Step 5: Initialize Data Directory

Checawaa stores data in JSON files within the data/ directory:

# Create data directory
mkdir -p data

# Create initial users file
cat > data/usuarios.json << 'EOF'
[
    {
        "username": "admin",
        "pass": "admin123",
        "email": "[email protected]"
    },
    {
        "username": "john",
        "pass": "john123",
        "email": "[email protected]"
    },
    {
        "username": "jane",
        "pass": "jane123",
        "email": "[email protected]"
    }
]
EOF

# Create empty registros file
echo "[]" > data/registros.json

The application auto-creates these files on first run if they don’t exist (see app.py:28-39). Manual creation gives you control over initial users.

Step 6: Configure Gmail App Password

To send automated reminder emails, you need a Gmail App Password:

Enable 2-Step Verification

Go to Google Account Security
Click “2-Step Verification”
Follow the prompts to enable it

Generate App Password

In Security settings, scroll to “App passwords”
Click “App passwords” (you may need to sign in again)
Select “Mail” and “Other (Custom name)”
Name it “Checawaa” or similar
Click “Generate”

Copy the 16-character password

Copy the generated password (format: xxxx xxxx xxxx xxxx)

Add to .env

.env

MAIL_USERNAME=[email protected]
MAIL_PASSWORD=xxxxxxxxxxxxxxxxxxxx

(Remove spaces from the password)

Step 7: Run the Development Server

Start Checawaa:

python app.py

Expected output:

 * Serving Flask app 'app'
 * Debug mode: on
WARNING: This is a development server. Do not use it in a production deployment.
 * Running on http://0.0.0.0:5000
Press CTRL+C to quit

The server binds to 0.0.0.0:5000, making it accessible from other devices on your local network. Access it at:

Same device: http://localhost:5000
Other devices: http://YOUR_LOCAL_IP:5000

Step 8: Verify Installation

Test the login page

Navigate to http://localhost:5000/loginYou should see the login form without errors.

Test employee login

Username: john
Password: john123

You should be redirected to the employee dashboard.

Test admin login

Log out, then log in with:

Username: admin
Password: admin123

You should be redirected to the monitoring dashboard (/monitor).

Verify data persistence

Check that JSON files were created:

ls -lh data/

You should see usuarios.json and registros.json.

Production Deployment

Deployment Checklist

Before deploying to production:

Deployment Options

Heroku
Railway
VPS/Cloud Server

Deploy to Heroku

Checawaa includes a Procfile for easy Heroku deployment:

web: gunicorn app:app

Install Heroku CLI

Download from heroku.com/cli

heroku login
heroku create checawaa-your-org

Set environment variables

heroku config:set SECRET_KEY=your-secret-key
heroku config:set [email protected]
heroku config:set MAIL_PASSWORD=your-app-password

Deploy

git push heroku main

Open your app

heroku open

Heroku’s ephemeral filesystem means JSON files will be lost on dyno restart. Migrate to PostgreSQL for production:

heroku addons:create heroku-postgresql:mini

Deploy to Railway

Railway offers simple deployment with persistent storage:

Connect your repository

Visit railway.app
Click “Start a New Project”
Select “Deploy from GitHub repo”
Choose your Checawaa repository

Configure environment variables

In Railway dashboard:

Go to Variables tab
Add all variables from your .env file

Add persistent volume

# In railway.toml
[deploy]
startCommand = "gunicorn app:app"

[[volumes]]
mountPath = "/app/data"

Deploy

Railway auto-deploys on push to main branch.

Deploy to VPS (Ubuntu)

For maximum control, deploy to your own server:

Install dependencies

sudo apt update
sudo apt install python3 python3-pip python3-venv nginx

Clone and setup

cd /var/www
git clone <your-repo> checawaa
cd checawaa
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Configure systemd service

Create /etc/systemd/system/checawaa.service:

[Unit]
Description=Checawaa Attendance System
After=network.target

[Service]
User=www-data
WorkingDirectory=/var/www/checawaa
Environment="PATH=/var/www/checawaa/venv/bin"
EnvironmentFile=/var/www/checawaa/.env
ExecStart=/var/www/checawaa/venv/bin/gunicorn -w 4 -b 127.0.0.1:5000 app:app

[Install]
WantedBy=multi-user.target

Configure Nginx

Create /etc/nginx/sites-available/checawaa:

server {
    listen 80;
    server_name checawaa.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /static {
        alias /var/www/checawaa/static;
    }
}

Enable the site:

sudo ln -s /etc/nginx/sites-available/checawaa /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Start services

sudo systemctl start checawaa
sudo systemctl enable checawaa
sudo systemctl status checawaa

Enable HTTPS with Let's Encrypt

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d checawaa.yourdomain.com

Database Migration (Optional)

For production systems with many employees, migrate from JSON to PostgreSQL:

Install PostgreSQL Support

pip install psycopg2-binary flask-sqlalchemy

Create Models

models.py

from flask_sqlalchemy import SQLAlchemy
from datetime import datetime

db = SQLAlchemy()

class User(db.Model):
    __tablename__ = 'usuarios'
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(50), unique=True, nullable=False)
    password = db.Column(db.String(100), nullable=False)
    email = db.Column(db.String(100), nullable=False)

class Registro(db.Model):
    __tablename__ = 'registros'
    id = db.Column(db.Integer, primary_key=True)
    usuario = db.Column(db.String(50), nullable=False)
    lat = db.Column(db.Float)
    lon = db.Column(db.Float)
    fecha = db.Column(db.Date, default=datetime.utcnow)
    hora = db.Column(db.Time, default=datetime.utcnow)

Update app.py

app.py

from models import db, User, Registro

app.config['SQLALCHEMY_DATABASE_URI'] = os.getenv('DATABASE_URL')
db.init_app(app)

with app.app_context():
    db.create_all()

Troubleshooting

Common Issues

ImportError: No module named 'flask'

Solution: Ensure your virtual environment is activated and Flask is installed:

source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install flask

Scheduler running twice

Solution: This is expected with debug=True and Flask’s reloader. The app.py file already disables reloader:

app.py

app.run(host='0.0.0.0', port=5000, debug=True, use_reloader=False)

Emails not sending

Causes:

Invalid Gmail App Password
2-Step Verification not enabled
Firewall blocking port 587

Solution:

# Test email configuration
python -c "
from flask_mail import Mail, Message
from flask import Flask

app = Flask(__name__)
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'] = 'your-app-password'

mail = Mail(app)
with app.app_context():
    msg = Message('Test', sender=app.config['MAIL_USERNAME'], recipients=['[email protected]'])
    msg.body = 'Test email'
    mail.send(msg)
    print('Email sent successfully!')
"

GPS not working on production

Cause: Modern browsers require HTTPS for Geolocation API (except localhost).Solution: Enable HTTPS using Let’s Encrypt or your hosting provider’s SSL certificate.

Port 5000 already in use

Solution: Change the port or kill the process using it:

# Find process using port 5000
lsof -i :5000

# Kill it
kill -9 <PID>

# Or use a different port
app.run(host='0.0.0.0', port=8080, debug=True, use_reloader=False)

Next Steps

Quick Start

Complete your first check-in and explore features

Configuration

Customize reminder times and tardiness rules

API Reference

Integrate with other systems

Admin Guide

Add, edit, and manage employee accounts

Get Started

Core Features

User Guides

Deployment

Overview

System Requirements

Minimum Requirements

Supported Platforms

Linux

macOS

Windows

Installation Methods

Local Development Setup

Step 1: Clone the Repository

Step 2: Create Virtual Environment

Step 3: Install Dependencies

Step 4: Configure Environment Variables

Step 5: Initialize Data Directory

Step 6: Configure Gmail App Password

Step 7: Run the Development Server

Step 8: Verify Installation

Production Deployment

Deployment Checklist

Deployment Options

Deploy to Heroku

Deploy to Railway

Deploy to VPS (Ubuntu)

Database Migration (Optional)

Install PostgreSQL Support

Create Models

Update app.py

Troubleshooting

Common Issues

Next Steps

Quick Start

Configuration

API Reference

Admin Guide

Build docs developers (and LLMs) love

Get Started

Core Features

User Guides

Deployment

​Overview

​System Requirements

​Minimum Requirements

​Supported Platforms

Linux

macOS

Windows

​Installation Methods

​Local Development Setup

​Step 1: Clone the Repository

​Step 2: Create Virtual Environment

​Step 3: Install Dependencies

​Step 4: Configure Environment Variables

​Step 5: Initialize Data Directory

​Step 6: Configure Gmail App Password

​Step 7: Run the Development Server

​Step 8: Verify Installation

​Production Deployment

​Deployment Checklist

​Deployment Options

​Deploy to Heroku

​Deploy to Railway

​Deploy to VPS (Ubuntu)

​Database Migration (Optional)

​Install PostgreSQL Support

​Create Models

​Update app.py

​Troubleshooting

​Common Issues

​Next Steps

Quick Start

Configuration

API Reference

Admin Guide

Build docs developers (and LLMs) love

Overview

System Requirements

Minimum Requirements

Supported Platforms

Installation Methods

Local Development Setup

Step 1: Clone the Repository

Step 2: Create Virtual Environment

Step 3: Install Dependencies

Step 4: Configure Environment Variables

Step 5: Initialize Data Directory

Step 6: Configure Gmail App Password

Step 7: Run the Development Server

Step 8: Verify Installation

Production Deployment

Deployment Checklist

Deployment Options

Deploy to Heroku

Deploy to Railway

Deploy to VPS (Ubuntu)

Database Migration (Optional)

Install PostgreSQL Support

Create Models

Update app.py

Troubleshooting

Common Issues

Next Steps