jessikitty/Raccoon-TimeKeeper
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README with security documentation

Browse Source
This commit is contained in:
jessikitty
2025-12-10 10:46:57 +11:00
parent 446414da3e
commit 3a3e8e46aa
1 changed files with 145 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files

226
README.md
View File

@@ -1,33 +1,46 @@
# 🦝 Raccoon Timekeeper # 🦝 Raccoon Timekeeper
A self-hosted time tracking application with a sleek grayscale design. A self-hosted time tracking application with multi-user support and role-based access control.
![Raccoon Timekeeper](https://img.shields.io/badge/version-1.0.0-gray)
![Python](https://img.shields.io/badge/python-3.10+-blue)
![License](https://img.shields.io/badge/license-MIT-green)
## Features ## Features
- ⏱️ **Flexible Time Entry** - Log time in multiple formats (1:30, 1.5, 90m, 1h 30m) - **Multi-user support** - Each user has their own tasks and time entries
- 📅 **Weekly Summaries** - View time grouped by task and day (Monday-Sunday weeks) - **Role-based access** - Admin users can manage all users, regular users can only see their own data
- 🖨️ **Printable Timesheets** - Generate clean printable weekly reports - **First-run setup** - Admin account created on first launch via web interface
- 📋 **Task Management** - Create, edit, and organize your tasks - **CLI management** - Reset admin password or create users from command line
- 📊 **Data Export** - Export your data as JSON or CSV - **Weekly timesheets** - View and print weekly summaries
- 🎨 **Raccoon Theme** - Sleek grayscale design - **Flexible time input** - Supports formats like `1:30`, `1.5`, `90m`, `1h 30m`
- **Task management** - Each user manages their own task list
## Quick Start ## Security Model
### User Isolation
- Each user can only view and modify their own:
- Tasks
- Time entries
- Weekly summaries
- All API endpoints filter by `current_user.id`
### Admin Privileges
Admin users can:
- View all users
- Create new users
- Edit user details (email, display name, admin status)
- Activate/deactivate user accounts
- Reset user passwords
- Delete users (and all their data)
Admin users **cannot**:
- Deactivate their own account
- Remove their own admin status
- Delete their own account
## Installation
### Using Docker (Recommended) ### Using Docker (Recommended)
```bash ```bash
# Clone the repository
git clone https://gitea.hideawaygaming.com.au/jessikitty/Raccoon-TimeKeeper.git
cd Raccoon-TimeKeeper
# Start with Docker Compose
docker-compose up -d docker-compose up -d
# Access at http://localhost:5000
``` ```
### Manual Installation ### Manual Installation
@@ -39,89 +52,140 @@ cd Raccoon-TimeKeeper
# Create virtual environment # Create virtual environment
python -m venv venv python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate source venv/bin/activate # Linux/Mac
# or: venv\Scripts\activate # Windows
# Install dependencies # Install dependencies
pip install -r requirements.txt pip install -r requirements.txt
# Copy environment file # Initialize database
cp .env.example .env flask init-db
# Run the application # Run the application
python app.py flask run --host=0.0.0.0 --port=5000
# Access at http://localhost:5000
``` ```
## Configuration ## First-Run Setup
Create a `.env` file based on `.env.example`: 1. Navigate to `http://localhost:5000`
2. You'll be redirected to the setup page
3. Create your admin account:
- Username (min 3 characters)
- Email
- Display name (optional)
- Password (min 8 characters)
4. Log in with your new credentials
```env ## CLI Commands
SECRET_KEY=your-super-secret-key-change-me
DATABASE_URL=sqlite:///data/timekeeper.db ### Initialize Database
DEBUG=false ```bash
flask init-db
``` ```
## Time Entry Formats ### Reset Admin Password
If you're locked out, reset the admin account from the command line:
```bash
flask reset-admin
```
You'll be prompted for:
- New admin username
- New admin email
- New password
The time input field accepts multiple formats: This will either update the existing admin or create a new one if none exists.
| Format | Example | Result | ### Create User from CLI
|--------|---------|--------| ```bash
| Hours:Minutes | `1:30` | 1h 30m | flask create-user
| Decimal Hours | `1.5` | 1h 30m | ```
| Minutes | `90m` | 1h 30m | Options:
| Hours | `2h` | 2h 0m | - `--admin` flag to make the user an administrator
| Combined | `1h 30m` | 1h 30m |
### List All Users
```bash
flask list-users
```
Shows all users with their status (active/inactive) and admin flag.
## Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `SECRET_KEY` | Flask secret key for sessions | Auto-generated |
| `DATABASE_URL` | Database connection string | `sqlite:///timekeeper.db` |
| `DEBUG` | Enable debug mode | `false` |
## API Endpoints ## API Endpoints
| Method | Endpoint | Description | ### Authentication
|--------|----------|-------------| - `GET /login` - Login page
| GET | `/api/tasks` | Get all tasks | - `POST /login` - Process login
| POST | `/api/tasks` | Create a task | - `GET /logout` - Logout user
| PUT | `/api/tasks/<id>` | Update a task | - `GET /setup` - First-run admin setup
| DELETE | `/api/tasks/<id>` | Delete a task | - `GET /change-password` - Change password page
| GET | `/api/entries` | Get all time entries |
| POST | `/api/entries` | Create a time entry |
| PUT | `/api/entries/<id>` | Update a time entry |
| DELETE | `/api/entries/<id>` | Delete a time entry |
| GET | `/api/weekly-summary` | Get weekly summary |
## Project Structure ### Pages (require login)
- `GET /` - Main time logging page
- `GET /settings` - Task management
- `GET /admin/users` - User management (admin only)
``` ### Tasks API (user-scoped)
raccoon-timekeeper/ - `GET /api/tasks` - List user's tasks
├── app.py # Main Flask application - `POST /api/tasks` - Create task
├── requirements.txt # Python dependencies - `PUT /api/tasks/<id>` - Update task
├── Dockerfile # Docker build file - `DELETE /api/tasks/<id>` - Delete task
├── docker-compose.yml # Docker Compose config
├── .env.example # Example environment file
├── templates/ # HTML templates
│ ├── base.html
│ ├── index.html
│ └── settings.html
└── static/
├── css/
│ └── style.css # Raccoon grayscale theme
└── js/
├── app.js # Shared utilities
├── index.js # Index page logic
└── settings.js # Settings page logic
```
## Development ### Entries API (user-scoped)
- `GET /api/entries` - List user's entries
- `POST /api/entries` - Create entry
- `PUT /api/entries/<id>` - Update entry
- `DELETE /api/entries/<id>` - Delete entry
- `GET /api/weekly-summary` - Get weekly summary
```bash ### Admin API (admin only)
# Run in debug mode - `GET /api/admin/users` - List all users
DEBUG=true python app.py - `POST /api/admin/users` - Create user
``` - `PUT /api/admin/users/<id>` - Update user
- `DELETE /api/admin/users/<id>` - Delete user
## Database Schema
### Users
| Column | Type | Description |
|--------|------|-------------|
| id | Integer | Primary key |
| username | String(80) | Unique username |
| email | String(120) | Unique email |
| password_hash | String(256) | Hashed password |
| display_name | String(100) | Display name |
| is_admin | Boolean | Admin flag |
| is_active | Boolean | Account active |
| created_at | DateTime | Creation timestamp |
| last_login | DateTime | Last login time |
### Tasks
| Column | Type | Description |
|--------|------|-------------|
| id | Integer | Primary key |
| user_id | Integer | Owner (FK to users) |
| name | String(100) | Task name |
| active | Boolean | Active flag |
| created_at | DateTime | Creation timestamp |
### Time Entries
| Column | Type | Description |
|--------|------|-------------|
| id | Integer | Primary key |
| user_id | Integer | Owner (FK to users) |
| task_id | Integer | Task (FK to tasks) |
| date | Date | Entry date |
| hours | Integer | Hours component |
| minutes | Integer | Minutes component |
| total_minutes | Integer | Total in minutes |
| notes | String(500) | Optional notes |
| created_at | DateTime | Creation timestamp |
## License ## License
MIT License - feel free to use and modify! MIT License
---
Made with 🦝 by Raccoon Timekeeper