{"id":44040623,"url":"https://github.com/getkanchi/kanchi","last_synced_at":"2026-02-07T20:37:21.394Z","repository":{"id":316457132,"uuid":"1062750847","full_name":"getkanchi/kanchi","owner":"getkanchi","description":"A realtime celery task monitoring and management system","archived":false,"fork":false,"pushed_at":"2025-12-28T22:25:39.000Z","size":3170,"stargazers_count":161,"open_issues_count":3,"forks_count":11,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-31T12:52:22.049Z","etag":null,"topics":["celery","monitoring","python"],"latest_commit_sha":null,"homepage":"https://kanchi.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/getkanchi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-09-23T17:15:08.000Z","updated_at":"2025-12-31T05:44:07.000Z","dependencies_parsed_at":"2025-09-24T19:19:23.026Z","dependency_job_id":"128ecab5-ccd3-41b5-bdcd-86670b3877a0","html_url":"https://github.com/getkanchi/kanchi","commit_stats":null,"previous_names":["getkanchi/kanchi"],"tags_count":33,"template":false,"template_full_name":null,"purl":"pkg:github/getkanchi/kanchi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getkanchi%2Fkanchi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getkanchi%2Fkanchi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getkanchi%2Fkanchi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getkanchi%2Fkanchi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/getkanchi","download_url":"https://codeload.github.com/getkanchi/kanchi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getkanchi%2Fkanchi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29208162,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-07T20:33:12.493Z","status":"ssl_error","status_checked_at":"2026-02-07T20:30:47.381Z","response_time":63,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["celery","monitoring","python"],"created_at":"2026-02-07T20:37:20.071Z","updated_at":"2026-02-07T20:37:21.380Z","avatar_url":"https://github.com/getkanchi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kanchi\n\nKanchi is a real-time Celery task monitoring (and management) system with an enjoyable user interface. It provides insights into task execution, worker health, and task statistics.\n\n## Features\n\n- Real-time task monitoring via WebSocket\n- Task filtering and searching (date range, status, name, worker, full-text)\n- Task retry tracking and orphan detection\n- Daily task statistics and history\n- Worker health monitoring\n- Auto-migrations with Alembic\n\n## Screenshots\n\n![Dashboard overview](.github/images/dashboard-overview.png)\n![Failed tasks table](.github/images/failed-tasks-table.png)\n![Task detail panel](.github/images/task-detail-panel.png)\n![Workflow automation](.github/images/workflow-automation.png)\n![Task retry chain](.github/images/task-retry-chain.png)\n![Retry task modal](.github/images/retry-task-modal.png)\n\n## Quick Start (Docker Compose)\n\nRun Kanchi using pre-built images from Docker Hub. No repository cloning required—just set a few environment variables and start the container.\n\n### Prerequisites\n\n- Docker Engine + Docker Compose plug-in installed on your host. Follow the [official Docker installation guide](https://docs.docker.com/engine/install/) for your OS.\n- Running Celery broker (RabbitMQ or Redis) instance (and optionally PostgreSQL) reachable from the host.\n\n1. **Create a docker-compose.yaml file**\n\n   Create a new directory and save the following as `docker-compose.yaml`:\n\n   ```yaml\n   services:\n     kanchi:\n       image: getkanchi/kanchi:latest\n       container_name: kanchi\n       ports:\n         - \"3000:3000\"\n         - \"8765:8765\"\n       environment:\n         # Required: Your Celery broker connection string\n         CELERY_BROKER_URL: ${CELERY_BROKER_URL}\n\n         # Optional: Database (defaults to SQLite)\n         DATABASE_URL: ${DATABASE_URL:-sqlite:////data/kanchi.db}\n\n         # Optional: Logging and development\n         LOG_LEVEL: ${LOG_LEVEL:-INFO}\n         DEVELOPMENT_MODE: ${DEVELOPMENT_MODE:-false}\n         ENABLE_PICKLE_SERIALIZATION: ${ENABLE_PICKLE_SERIALIZATION:-false}\n\n         # Optional: Frontend URLs\n         NUXT_PUBLIC_API_URL: ${NUXT_PUBLIC_API_URL:-http://localhost:8765}\n         NUXT_PUBLIC_WS_URL: ${NUXT_PUBLIC_WS_URL:-ws://localhost:8765/ws}\n\n         # Optional: Authentication (disabled by default)\n         AUTH_ENABLED: ${AUTH_ENABLED:-false}\n\n         # Optional: Basic HTTP authentication\n         AUTH_BASIC_ENABLED: ${AUTH_BASIC_ENABLED:-false}\n         BASIC_AUTH_USERNAME: ${BASIC_AUTH_USERNAME}\n         BASIC_AUTH_PASSWORD_HASH: ${BASIC_AUTH_PASSWORD_HASH}\n\n         # Optional: OAuth providers\n         AUTH_GOOGLE_ENABLED: ${AUTH_GOOGLE_ENABLED:-false}\n         GOOGLE_CLIENT_ID: ${GOOGLE_CLIENT_ID}\n         GOOGLE_CLIENT_SECRET: ${GOOGLE_CLIENT_SECRET}\n         AUTH_GITHUB_ENABLED: ${AUTH_GITHUB_ENABLED:-false}\n         GITHUB_CLIENT_ID: ${GITHUB_CLIENT_ID}\n         GITHUB_CLIENT_SECRET: ${GITHUB_CLIENT_SECRET}\n         OAUTH_REDIRECT_BASE_URL: ${OAUTH_REDIRECT_BASE_URL}\n\n         # Optional: Email restrictions for OAuth\n         ALLOWED_EMAIL_PATTERNS: ${ALLOWED_EMAIL_PATTERNS}\n\n         # Optional: CORS and host controls\n         ALLOWED_ORIGINS: ${ALLOWED_ORIGINS}\n         ALLOWED_HOSTS: ${ALLOWED_HOSTS}\n\n         # Optional: Security tokens (generate with: openssl rand -hex 32)\n         SESSION_SECRET_KEY: ${SESSION_SECRET_KEY}\n         TOKEN_SECRET_KEY: ${TOKEN_SECRET_KEY}\n       volumes:\n         - kanchi-data:/data\n       restart: unless-stopped\n       healthcheck:\n         test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:8765/api/health\"]\n         interval: 30s\n         timeout: 10s\n         retries: 3\n         start_period: 40s\n\n   volumes:\n     kanchi-data:\n   ```\n\n2. **Set required environment values**\n\n   At minimum, export `CELERY_BROKER_URL` or place it in a `.env` file alongside `docker-compose.yaml`. Example:\n\n   ```bash\n   # For RabbitMQ:\n   export CELERY_BROKER_URL=amqp://user:pass@rabbitmq-host:5672//\n\n   # For Redis:\n   export CELERY_BROKER_URL=redis://localhost:6379/0\n   ```\n\n   Optional overrides (see docker-compose.yaml for all available options):\n\n   ```bash\n   export DATABASE_URL=postgresql://user:pass@postgres-host:5432/kanchi\n   export LOG_LEVEL=INFO\n   export DEVELOPMENT_MODE=false\n   export ENABLE_PICKLE_SERIALIZATION=false\n   export NUXT_PUBLIC_API_URL=http://your-kanchi-host:8765\n   export NUXT_PUBLIC_WS_URL=ws://your-kanchi-host:8765/ws\n\n   # Authentication / security (all optional)\n   export AUTH_ENABLED=true\n   export AUTH_BASIC_ENABLED=true\n   export BASIC_AUTH_USERNAME=kanchi-admin\n   export BASIC_AUTH_PASSWORD_HASH=pbkdf2_sha256$260000$mysalt$N8Dk...  # see below\n\n   # OAuth\n   export AUTH_GOOGLE_ENABLED=true\n   export GOOGLE_CLIENT_ID=...\n   export GOOGLE_CLIENT_SECRET=...\n   export AUTH_GITHUB_ENABLED=true\n   export GITHUB_CLIENT_ID=...\n   export GITHUB_CLIENT_SECRET=...\n   export OAUTH_REDIRECT_BASE_URL=https://your-kanchi-host\n\n   # Allowed email addresses for OAuth logins (wildcards supported)\n   export ALLOWED_EMAIL_PATTERNS='*@example.com,*@example.org'\n\n   # CORS and host controls\n   export ALLOWED_ORIGINS=https://your-kanchi-host,http://localhost:3000\n   export ALLOWED_HOSTS=your-kanchi-host,localhost,127.0.0.1\n\n   # Token secrets (must be non-default in production)\n   export SESSION_SECRET_KEY=$(openssl rand -hex 32)\n   export TOKEN_SECRET_KEY=$(openssl rand -hex 32)\n\n# Pickle payloads (advanced; defaults to off)\nexport ENABLE_PICKLE_SERIALIZATION=false\n   ```\n\n3. **Start or update Kanchi in one command**\n\n   ```bash\n   docker compose up -d --pull always\n   ```\n\n   Re-run the same command to pull the latest image and restart the container.\n\n4. **Visit the app**\n\n   - Frontend: `http://localhost:3000`\n   - API / Docs: `http://localhost:8765`\n\n5. **Optional commands**\n\n   ```bash\n   docker compose logs -f kanchi      # Tail logs\n   docker compose down                # Stop and remove the container\n   docker compose restart kanchi      # Restart the container\n   docker compose pull                # Pull latest image without restarting\n   ```\n\nKanchi expects a Celery broker (RabbitMQ or Redis) and (if desired) PostgreSQL to be managed separately—point `CELERY_BROKER_URL` and `DATABASE_URL` to the infrastructure you already run.\n\nMigrations run automatically on startup.\n\n### Pickle payloads (opt-in)\n\nKanchi rejects pickle-serialized messages by default for safety. If your Celery producers emit `application/x-python-serialize`, set `ENABLE_PICKLE_SERIALIZATION=true` only when you fully trust all producers and the broker. See `pickle.md` for a short rundown.\n\n### Authentication\n\nAuthentication is opt-in. When `AUTH_ENABLED=false` (the default) anyone who can reach the backend may read metrics and connect over WebSockets. Enable authentication to require access tokens for all API routes and WebSocket connections.\n\n#### Basic HTTP authentication\n\n1. Generate a PBKDF2 hash for the password (for example using Python):\n\n   ```bash\n   python - \u003c\u003c'PY'\n   import os, base64, hashlib\n\n   password = os.environ.get('KANCHI_BASIC_PASSWORD', 'change-me').encode('utf-8')\n   salt = base64.b64encode(os.urandom(16)).decode('ascii').strip('=')\n   iterations = 260000\n   dk = hashlib.pbkdf2_hmac('sha256', password, salt.encode('utf-8'), iterations)\n   print(f\"pbkdf2_sha256${iterations}${salt}${base64.b64encode(dk).decode('ascii')}\")\n   PY\n   ```\n\n2. Set `AUTH_ENABLED=true`, `AUTH_BASIC_ENABLED=true`, `BASIC_AUTH_USERNAME`, and `BASIC_AUTH_PASSWORD_HASH` (or `BASIC_AUTH_PASSWORD` for local testing only).\n\n#### OAuth (Google, GitHub)\n\n1. Configure `AUTH_GOOGLE_ENABLED` and/or `AUTH_GITHUB_ENABLED` with the provider credentials.\n2. Set `OAUTH_REDIRECT_BASE_URL` to the publicly reachable backend URL (e.g., `https://kanchi.example.com`).\n3. Add allowed email patterns via `ALLOWED_EMAIL_PATTERNS` to restrict who can sign in.\n4. The frontend exposes convenient buttons for OAuth providers once enabled.\n\nEvery login issues short-lived access tokens plus refresh tokens. You can adjust lifetimes through `ACCESS_TOKEN_LIFETIME_MINUTES` and `REFRESH_TOKEN_LIFETIME_HOURS` if required.\n\n## Local Development\n\n### Prerequisites\n\n- Python 3.8+\n- Poetry\n- Node.js 20+\n- Celery broker (RabbitMQ or Redis)\n\n### Installation\n\n```bash\ncd agent \u0026\u0026 poetry install\ncd ../frontend \u0026\u0026 npm install\n```\n\n### Run\n\n```bash\n# Use our makefile:\nmake dev\n\n# Or manually:\n\n# Terminal 1: Backend\ncd agent \u0026\u0026 poetry run python app.py\n\n# Terminal 2: Frontend\ncd frontend \u0026\u0026 npm run dev\n```\n\n### Testing Environment\n\n```bash\ncd scripts/test-celery-app\nmake start          # Start RabbitMQ, Redis, Workers\nmake test-mixed     # Generate test tasks\n```\n\n## Contributing\n\n### Backend\n\n```bash\ncd agent\npoetry run black .              # Format\npoetry run ruff check .         # Lint\npoetry run alembic revision --autogenerate -m \"description\"  # Migration\n```\n\n### Frontend\n\n```bash\ncd frontend\nnpm run build                   # Build\nnpx swagger-typescript-api generate -p http://localhost:8765/openapi.json -o app/src/types -n api.ts --http-client axios\n```\n\n## Getting Help\n\nHave questions, feedback, or want to connect with other Kanchi users? Join our community on Discord:\n\n[![Discord](https://img.shields.io/badge/Discord-Join%20us-5865F2?logo=discord\u0026logoColor=white)](https://discord.gg/gSp9wsu3k)\n\n## License\n\nLicensed under [MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetkanchi%2Fkanchi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgetkanchi%2Fkanchi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetkanchi%2Fkanchi/lists"}