TaskMan

TaskMan is a web application designed to manage tasks individually or in teams (or families). It allows users to register, create teams, and effectively manage tasks with team-based isolation. The application is deployed and accessible at: https://taskman.tech

Features

• User Registration: Users can register to create an account and log in to the TaskMan application.
• Team Management: Users can create teams and invite other users to join, or work independently without a team
• Task Management: Create tasks with detailed information including title and description
• Team-Based Isolation: All task-related entities (executors, statuses, labels) are isolated by team membership
• Task Assignment: Assign tasks to team members only*
• Custom Task Status: Create and manage custom task statuses (e.g., To Do, In Progress, Done) within your team with custom color for each status; any status can be marked as final (completed tasks are hidden from the default list with a 3-state toggle: active / completed / all, and the deadline countdown is frozen for completed tasks)
• Labels: Organize tasks with custom labels created by team members
• Notes: Create text notes with title and content, optionally linked to tasks; available in both individual and team modes with full markdown support and live preview; text is optional when at least one image is attached; attach up to 10 images per note (JPEG/PNG/GIF/WebP, 5 MB each) with a gallery in the note detail view; images open in a zoomable viewer (pinch, mouse wheel, double click, +/- buttons, drag to pan)
• Advanced Filtering: Filter tasks by executors, statuses, and labels - all scoped to your team
• Task Search: Search tasks by title and description
• Task Sorting: Sort task list by creation date, update date, and alphabetically
• Theme Switching: Switch between Light, Dark, and System themes
• Free Plan Limits: Resource limits for free plan (teams, members, tasks, statuses, labels, notes, checklist items) with usage tracking and upgrade prompts

Language Support

The TaskMan application is available in multiple languages:

• English
• Russian
• Tajik
• Azerbaijani
• Kyrgyz
• Spanish
• Simplified Chinese
• Kazakh

Requirements

• OS: Linux (recommended)
• Python: ^3.12
• Poetry: ^1.2.2 (for non-Docker setup)
• Docker Engine: ^20.10 (for Docker setup)
• Docker Compose: ^2.0 (for Docker setup)

Getting Started

The project includes an .env.example file in the repository root. You will use this as a template to create configuration files for different environments.

Option 1: Docker Setup (Recommended for production)

⚠️ For local development, use Option 2 (Traditional Setup). Docker setup is intended for production-like environments only.

Prerequisites

• Docker and Docker Compose installed on your system

Quick Start

# clone the repository:
git clone https://github.com/Onoiro/TaskMan.git
cd TaskMan

# create the Docker environment file from example:
cp .env.example .env.docker

# configure .env.docker:
# Open .env.docker and update the variables for production/docker environment:

# --- .env.docker example content ---
DEBUG=False
SECRET_KEY=generate_a_strong_secret_key_here
DJANGO_LANGUAGE_CODE=en-us
ADMIN_USERNAME=something_unexpected
ADMIN_PASSWORD=change_me_at_least_20_chars
ADMIN_URL=not-standart-url

# Database settings (PostgreSQL)
POSTGRES_DB=taskman_db
POSTGRES_USER=your_db_user
POSTGRES_PASSWORD=your_secure_password
POSTGRES_PORT=5432

# Optional: Rollbar integration
# POST_SERVER_ITEM_ACCESS_TOKEN=your_token
# -----------------------------------

# Note: The Makefile commands for Docker automatically use .env.docker

# build and start the application for first time:

# build images
make d-build # docker compose build

# start all services in background
make up # docker compose up -d

# run database migrations
make d-migrate # docker compose exec django-web python manage.py migrate

# create superuser
make d-createsu # docker compose exec django-web python manage.py createsuperuser

# collect static files:
make d-collect # docker compose exec django-web python manage.py collectstatic --no-input

Access the application: Open your browser and navigate to: http://localhost:8001

Docker Management Commands

make up # start services
make down # stop services
make logs # view logs
make restart # restart services
make deploy # rebuild and deploy
make d-bash # enter Django container
make db-shell # access database
make d-backup # create database backup
make help # view all available commands

Option 2: Traditional Setup (Without Docker for local development)

Prerequisites

• Python 3.12 or higher
• Poetry 1.2.2 or higher
• PostgreSQL (for production) or SQLite (for development included)

Note: This setup is intended for local development and functional testing. It runs with DEBUG=True, default admin credentials (admin/admin), and SQLite database.

Setup Steps

# clone the repository:
git clone https://github.com/Onoiro/TaskMan.git
cd TaskMan

# create the local environment file from example:
cp .env.example .env

# configure environment variables in .env:

# Open .env and ensure it is set for local development:

# --- .env example content ---
DEBUG=True
SECRET_KEY=dev_secret_key
DJANGO_LANGUAGE_CODE=en-us
ADMIN_USERNAME=admin
ADMIN_PASSWORD=admin
ADMIN_URL=admin
DATABASE_URL=sqlite:///db.sqlite3
# if you use postgresql instead of sqlite, add the following
# DATABASE_URL=postgresql://your_db_user:your_password@localhost:5432/your_db_name
# ----------------------------

# install dependencies and setup database:
make build

# run local development server:
make dev

Access the application: Open your browser and navigate to: http://127.0.0.1:8001/

Django Debug Toolbar: The Django Debug Toolbar menu opens on the right side of the page. It provides useful information for development and debugging:

• Timer: Request/response time and Django startup time
• Settings: Django settings values
• Headers: HTTP request/response headers
• SQL: Number of SQL queries executed and execution time
• Cache: Cache operations (hits/misses)
• Signals: Django signals emitted during the request
• Templates: Templates rendered during the request

Traditional Management Commands

make dev # run development server
make start # run production server
make test # run tests
make lint # check code style
make migrations # create migrations
make migrate # apply migrations
make messages # create translations
make compile # compile translations
make shell # access Django shell

Team-Based Workflow

TaskMan implements a team-based isolation system:

• Teams: Users can create teams and invite other members
• Team Invites: Team admins can generate invite links to add new members. Each link is single-use
• Join Request: Users can also request to join a team by providing the team name and password. This is convenient when an admin wants to add multiple members at once without generating individual links
• Task Isolation: When creating or editing tasks, only team members are available as executors
• Status & Labels: Custom statuses and labels are shared only within team members
• Notes: Notes can be created independently or linked to specific tasks; team members can view all team notes, while only the author or team admin can edit or delete them. Notes support full markdown functionality with live preview. Note images are served through a private view (no direct MEDIA_URL access) and files are cleaned up when a note or image is deleted. A note needs text or at least one image; image-only notes are shown as "Untitled Note" with a thumbnail in the note list. Clicking any image (gallery or inline markdown) opens a zoomable viewer: pinch or mouse wheel to zoom, double click/tap to toggle zoom, drag to pan, plus zoom in/out/reset buttons
• Notifications: Team members receive real-time notifications for important events:
  • New task assignment
  • Task status changes
  • Team membership changes (invites, joins, removals)
  • Unread notifications show a badge on the PWA app icon (Badging API, supported on Android and iOS 16.4+; silently ignored elsewhere)
• Filtering: Task filters show only values created by team members
• Independent Work: Users can also work independently without joining any team

Development

Code Quality

# check code style
make lint
# run tests
make test
# generate test coverage
make test-cov

Database Operations

# create new migrations
make migrations  # or make d-migrations for Docker
# apply migrations
make migrate     # or make d-migrate for Docker
# access database shell
make shell       # or make db-shell for Docker

Internationalization

The application supports 8 languages: English, Russian, Tajik, Azerbaijani, Kyrgyz, Spanish, Simplified Chinese (zh-hans, stored as zh_Hans), and Kazakh. Translations are automated using Yandex Translate API with a two-stage workflow for quality control.

Why Two-Stage Translation?

Machine translation services (including Yandex) translate strings without context - they don't know that these texts are for application users, buttons, labels, or messages. Therefore:

1. English → Russian: You can verify and correct Russian translations manually (if you know Russian)
2. Russian → other languages: Once Russian is verified, use it as the source for translating to other languages

This ensures quality: you control the Russian translation, and other languages are translated from the verified Russian version.

Translation Workflow

Step 1: Extract new translatable strings from code

# Run from the task_manager/ directory: django-admin is not in PATH
# outside Poetry, and a root-level locale/ directory would be created
# instead of the one Django actually reads.
cd task_manager && poetry run django-admin makemessages -a && cd ..

This creates/updates task_manager/locale/*/LC_MESSAGES/django.po files with new English strings.

New strings are marked fuzzy and get the translation of a similar old msgid, which msgfmt then skips entirely. Such entries are translated again in step 2.

Step 2: Translate English → Russian

make translate-ru

This uses Yandex Translate API to translate new English strings to Russian.

Step 3: Review and fix Russian translations

# Open task_manager/locale/ru/LC_MESSAGES/django.po in your editor
# Fix translations as needed, for example:
# "Next" → "Следующая" (not "Следующий")
# "Add checklist item" → "Добавьте пункт в чеклист" (context-aware)

This is the most important step — you ensure Russian translations are correct and context-appropriate. Yandex has no idea about the application context, so it happily translates team as «отряд» and note images as «обратите внимание на изображения».

Step 4: Translate other languages from verified Russian

make translate-from-ru

This translates Azerbaijani, Kyrgyz, Tajik, Spanish, Simplified Chinese and Kazakh from the verified Russian translations, not from English. Entries without a Russian translation are skipped and listed at the end of the run.

Step 5: Check the result mechanically, then compile

poetry run python .agents/skills/translation-checker/check_po.py fix --dry-run
poetry run python .agents/skills/translation-checker/check_po.py fix
poetry run python .agents/skills/translation-checker/check_po.py check
make compile    # or make d-compile for Docker

check_po.py (see .agents/skills/translation-checker/SKILL.md) catches what is objectively wrong: broken placeholders, HTML tags, fuzzy entries, stale #| msgid leftovers, missing punctuation and inconsistent product terms. fix repairs the placeholder damage the API causes (%(name) s, %(tam_name)s, <strong >).

make compile compiles .po files to .mo (binary format used by Django). The .mo files are tracked in the repository, so commit them together with the .po files.

Environment Variables for Translation

Variable	Description	Example
YANDEX_TRANSLATE_API_KEY	Yandex Cloud API key	your_api_key
YANDEX_FOLDER_ID	Yandex Cloud folder ID	b1g...
SKIP_LANGS	Comma-separated list of languages to skip	ru,az
TARGET_LANG	Translate only one language	ru
FROM_RU=1	Use Russian as source for az/ky/tg/es/zh-hans/kk	1
DRY_RUN=1	Preview without API calls	1

Additional Commands

# Translate only one specific language (e.g., only Russian)
TARGET_LANG=ru make translate

# Translate from Russian to all other languages (skip English and Russian)
make translate-from-ru

# Skip specific languages (e.g., skip Russian and Azerbaijani)
SKIP_LANGS=ru,az make translate

# Preview what would be translated without making changes
DRY_RUN=1 make translate

# List untranslated strings with line numbers (Russian only)
make translate-dry-ru

# List untranslated strings for every language
poetry run python scripts/translate_po.py list

Yandex Translate API Setup

To use automatic translation, you need a Yandex Cloud API key:

1. Create a Yandex Cloud account at https://cloud.yandex.com
2. Create a new project or select existing
3. Enable the Machine Translation API
4. Create an API key in the service account settings
5. Set YANDEX_TRANSLATE_API_KEY and YANDEX_FOLDER_ID in your .env file

Note: The script uses polib library (already in dev dependencies) and urllib.request (stdlib) — no additional HTTP clients required.

Production Deployment

For production deployment with Docker:

• Configure production environment variables Ensure your .env.docker file contains production values (DEBUG=False, strong SECRET_KEY).
• Use the deploy command:

make deploy

This command will:

• Create dir /staticfiles
• Rebuild images
• Start services
• Run migrations
• Collect static files
• Clear Docker cache
• Check services

make redeploy

Used in specific cases:

• Changes in docker-compose.yml
• PostgreSQL image updates
• Problems with container state
• Full rebuild without cache is required

Differences from deploy:

• Stops all containers
• Rebuilds images without cache (--no-cache)
• Completely recreates containers
• Waits 15 seconds before migrations
• Clears images and builder cache

Database Backup and Restore

# create backup (compressed with gzip, automatic folder creation)
make d-backup
# restore from backup (supports compressed .sql.gz files)
make d-restore FILE=backup_filename.sql.gz
# download latest backup from production server
make d-pull-backup
# upload backup to production server
make d-push-backup
# reset database completely
make d-reset-db

Backup Features:

• Backups are compressed with gzip to save disk space
• Backups are stored in backups/ directory
• Old backups are automatically deleted after 7 days (via backup.sh)
• Restore command includes safety checks and confirmation prompts

Troubleshooting

Docker Issues

# check service status:
make status
# view logs:
make logs
# or:
make logs-web
# clean Docker objects:
make d-clean
# check disk usage:
make d-space

Common Solutions

• If using Docker commands, ensure .env.docker exists and is configured correctly.
• If using local 'make dev', ensure .env exists and is configured correctly.
• For database connection issues, ensure PostgreSQL container is healthy ('make status').
• Use 'make help' to see all available commands

Contributing

TaskMan is an open-source project, and contributions are highly welcome! Whether you are a beginner or an experienced developer, you can help us improve this project. If you want to help - pick an issue and submit a pull request.

How to start:

1. Browse open issues
2. Find an issue labeled help wanted or good first issue
3. Leave a comment: "I would like to work on this"
4. Fork → branch → make changes → open PR

CI runs automatically on every PR (lint + tests on Python 3.12 and 3.13). A PR can only be merged after CI passes and the maintainer approves it.

• We maintain 98% test coverage, making it safe and easy to contribute without breaking things.
• Please read our CONTRIBUTING.md for details on how to set up the project locally, run tests, and submit a Pull Request.

License

This project is licensed under the MIT License.

Links

• Live Application: https://taskman.tech
• Repositories: https://github.com/Onoiro/taskman https://gitverse.ru/oriono/taskman
• Author: Andrey Bogatyrev mailto:donoriono@gmail.com