Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
PRKS is a self-hosted, local-first research library for managing PDFs, Markdown notes, bibliographic metadata, and research relationships. It uses Python 3.12, SQLite, and on-disk storage to provide a single-user workspace.
Sources: README.md:3-8, AGENTS.md:3-6
Installation Requirements
You must have Python 3.12+ installed on your system. PRKS requires exact runtime package pins as specified in requirements.txt. You should use a project-local virtual environment to manage these dependencies.
Sources: README.md:17-21
Quick Start Procedure
- Create a virtual environment:
python3 -m venv .venv - Install dependencies:
./.venv/bin/python -m pip install -r requirements.txt - Launch the application:
./.venv/bin/python prks_app.py
Sources: README.md:25-29
The prks_app.py script validates your Python version and package pins before starting the server. If a mismatch is detected, the process exits with remediation instructions.
Sources: README.md:31-33
Application Access
By default, the PRKS process listens on 127.0.0.1:8080. You access the system by opening http://127.0.0.1:8080 in a web browser.
Sources: README.md:35-36
Execution Options
| Flag | Description | Default |
|---|---|---|
--port | Sets the port for the server process | 8080 |
--host | Sets the bind address (e.g., 0.0.0.0 for LAN access) | 127.0.0.1 |
--testing | Enables testing mode with separate storage and port | Disabled |
--storage-root | Explicitly defines the path for persistent data | data/ |
Sources: README.md:38-51
Data Layout and Storage
PRKS stores all data in a local directory. If the PRKS_STORAGE environment variable is unset, the application uses the data/ directory within the repository root.
Sources: README.md:104-106
The storage root contains a prks-root.json marker with a stable storage_root_id. PRKS refuses to open directories that do not contain this marker or are not empty. Only one server process can access a storage root at a time, enforced by an OS-level lock on .prks-maintenance/root.lock.
Sources: README.md:108-118
Configuration Environment Variables
| Variable | Purpose |
|---|---|
PRKS_STORAGE | Root directory for persistent data |
PRKS_TESTING | Uses data_testing/ and port 8070 when set to 1 |
PRKS_LOG_LEVEL | Sets stderr log level (Default: INFO) |
PRKS_LOG_FILE | Override path for the error log |
PRKS_PERF_SLOW_MS | API duration threshold for "slow" logs (Default: 250) |
Sources: README.md:78-95
Docker Deployment
You can run PRKS using Docker Compose. The build script ./docker-build.sh creates the prks:latest image.
Sources: README.md:58-60
docker compose up -d
The Docker container binds to 0.0.0.0:8080 internally, while Compose publishes it to the host loopback at 127.0.0.1:8080. The host's ./data directory is mounted to /data in the container.
Sources: README.md:65-71
Development Environment
For contributors and agents, PRKS provides specific testing and development workflows.
Testing Mode
Running python prks_app.py --testing sets PRKS_TESTING=1. This mode uses port 8070 and defaults storage to data_testing/. It strictly refuses to touch the production data/ directory.
Sources: README.md:51-56, AGENTS.md:73-75
Development Installation
Install both runtime and development pins:
./.venv/bin/python -m pip install -r requirements.txt -r requirements-dev.txt
Sources: README.md:164-167
Test Commands
| Command | Description |
|---|---|
python run_tests.py | Runs fast unit tests (No Chromium required) |
python run_tests.py --e2e | Runs full browser E2E tests using Playwright |
python run_tests.py --all | Runs both unit and E2E suites |
Sources: README.md:169-178, AGENTS.md:61-63
Summary
Setting up PRKS involves preparing a Python 3.12 environment, installing pinned dependencies, and choosing a storage root. The system emphasizes security through local loopback binding by default and protects data integrity using file-based locking. Developers can utilize the --testing flag and Playwright-based test suites to validate changes without affecting production data.
Sources: README.md:35-37, README.md:51-54, AGENTS.md:64-67