JobRadar

English | Česky

JobRadar is an open-source, self-hosted system for discovering, saving, translating, assessing, and managing job opportunities, with privacy built into its workflow. Each user's records stay in their own private instance.

JobRadar does not automatically apply for jobs. Choosing Respond (Reagovat in the Czech interface) only adds an opportunity to an internal preparation queue. Sending an application is a separate, audited step that requires explicit approval.

The full specification and implementation sequence are in the implementation plan (in Czech). The interface and most detailed documentation are currently in Czech.

Quick start

The repository includes a standalone Docker Compose stack with no dependency on a particular directory, domain, or reverse proxy. Default passwords are intended only for an initial local run; set your own in .env before any other deployment.

Copy-Item .env.example .env
docker compose up -d --build
docker compose exec --user www-data web php bin/jobradar database:migrate
docker compose exec --user www-data web php bin/jobradar user:create-admin user@example.test "Administrator"

On Linux or macOS, use cp .env.example .env for the first command. The application is available only on the local machine at http://localhost:8080.

Related MCP server: jobjourney-claude-plugin

Operation and configuration

Run the stack from any directory with Docker and Docker Compose available. In .env, configure the public application URL (APP_URL), secure database passwords, and optionally APP_PORT. The default APP_BIND_ADDRESS is 127.0.0.1; change it only when deliberately exposing the application through your own network security or reverse proxy.

Manage the database and administrator account inside the application container:

docker compose exec --user www-data web php bin/jobradar database:migrate
docker compose exec --user www-data web php bin/jobradar user:create-admin user@example.test "Administrator"

The administrator password is entered interactively with hidden input, never as a command argument.

An administrator can create an API client and an expiring token:

docker compose exec --user www-data web php bin/jobradar api:create-client user@example.test "Local MCP" mcp --scope=sources:read --scope=opportunities:read --days=30

The full token is shown only when it is created. JobRadar stores its hash and a safe prefix. Specify each permission with a separate --scope option.

Source checks are performed by Codex through Chrome and a separate execution MCP with the search:execute scope. The demonstration runner:work-once command is disabled, and its claim API returns HTTP 410. See the executor documentation (in Czech) for deployment, security, recovery, and testing.

.\executor\install.ps1 -Container <web-container-name>
.\executor\launch.ps1 -Probe
python executor/smoke_stdio.py

Replace <web-container-name> with the name of your deployed web container. On Windows, installation protects the token using DPAPI and does not claim any source check. Enable production automation only after verifying a scheduled run and completing a pilot with configured sources, a candidate profile, and assessment rules. The integration verification guide describes the checks to perform.

The general-purpose MCP server uses the official PHP SDK and standard STDIO transport. Start it with php bin/jobradar-mcp. It reads the API URL from JOBRADAR_MCP_API_URL and its separate token from JOBRADAR_MCP_TOKEN. Grant only the scopes required by the client's tools; a read-only client does not need write permissions.

The server provides tools for sources, checks, opportunities, the response queue, assessments, and reversible individual or atomic batch decisions under a time-limited delegation. Creating a delegation requires the separate decisions:delegate scope. Grant it only to a client that needs to create delegations following your explicit instruction. No tool sends an application.

Example MCP host configuration (supply an absolute path and keep the token outside Git):

{
  "mcpServers": {
    "jobradar": {
      "command": "php",
      "args": ["C:/absolute/path/jobradar/bin/jobradar-mcp"],
      "env": {
        "JOBRADAR_MCP_API_URL": "http://localhost:8080/api/v1",
        "JOBRADAR_MCP_TOKEN": "<separate MCP token>"
      }
    }
  }
}

Inspect configuration and service status:

docker compose config
docker compose ps
docker compose logs -f web db

Stop the environment while preserving the database:

docker compose down

Deleting local data is a separate, deliberate operation and is not part of a normal shutdown.

Backup and restore

SQL backups use a consistent snapshot and never overwrite an existing file. They contain private instance data: keep them out of Git and public repositories, and encrypt them for transfer or long-term storage.

docker compose exec --user www-data web php bin/jobradar database:backup var/backups/jobradar-backup.sql
docker compose cp web:/var/www/html/var/backups/jobradar-backup.sql C:\private-backups\jobradar-backup.sql

For safety, database:restore refuses a database containing any tables. First create a separate, empty MySQL database, configure its DB_NAME and the application user's permissions, then run:

docker compose exec --user www-data -e DB_NAME=jobradar_restore web php bin/jobradar database:restore var/backups/jobradar-backup.sql

The password is neither printed nor passed as a process argument. The mysqldump and mysql clients receive it only through the child process environment. After restoring, verify sign-in, opportunity counts, and the most recent run before using the restored database in production.

Quality checks

PHP integration tests require APP_ENV=test and a separate database named jobradar_test or jobradar_test_<suffix>. Provision that database and its access permissions before running the suite; never point tests at your normal instance database.

docker compose exec --user www-data -e APP_ENV=test -e DB_NAME=jobradar_test web composer check
npm ci
npm run build

GitHub Actions runs the checks against MySQL 8.4 and also verifies repository privacy, reproducible frontend assets, and the standalone Docker image build.

Before committing or pushing, run the privacy guard and review the diff for personal context:

python scripts/privacy-check.py --staged
python scripts/privacy-check.py --history

Enable the included local hooks with git config core.hooksPath .githooks. Automated scanning supplements a human review; it cannot reliably identify personal plans or preferences in ordinary prose.

Project status

Implemented features include a Nette application for opportunities, assessments, reversible decisions, audited source checks, a versioned API, general-purpose and execution MCP servers, and verifiable backup and restore. Execution supports checkpoints, isolation of assigned work, and a dashboard of incomplete source checks. Each deployment needs its own configuration and integration pilot before production portal traversal.

Concrete follow-up steps are stored as internal action_items. Optional Todoist synchronization mirrors them and records links in external_tasks. Choosing Respond alone does not create a task. The target workflow (in Czech) describes responsibilities and integration boundaries.

License

JobRadar is available under the MIT license. Source code and synthetic demonstration data may be public. Real opportunities, candidate profiles, tokens, logs, and databases do not belong in this repository.

See SECURITY.md for security reporting and CONTRIBUTING.md for contribution guidelines.