Configuration Guide
Relevant source files
The following files were used as context for generating this wiki page:
The PRKS configuration system manages server behavior, data persistence, and environment validation. It uses environment variables, command-line arguments, and a bootstrap configuration file to define the operational environment. The system prioritizes local-first storage and single-user security by default.
Sources: README.md:1-12, backend/AGENTS.md:1-12
Storage Configuration
The storage root defines where PRKS persists the SQLite database, PDF files, and thumbnails. PRKS enforces a "one server per storage root" policy using a filesystem lock.
Storage Resolution Priority
The server resolves the storage root directory based on the following priority list. If a choice is set but invalid, the application terminates with a startup error.
- CLI Argument: Path provided via
python prks_app.py --storage-root PATH. - Environment Variable: The value of
PRKS_STORAGE. - Bootstrap File: The
storage.local_rootentry in theconfig.jsonfile. - Default Directory: The project-local
data/directory.
Sources: README.md:107-115, backend/AGENTS.md:80-92
Storage Layout and Markers
Every storage root contains a prks-root.json marker with a unique storage_root_id. The server process holds an operating-system lock on .prks-maintenance/root.lock during operation.
Sources: README.md:117-127, backend/AGENTS.md:80-92
Environment Variables
PRKS uses environment variables to control logging levels, performance monitoring, and backup constraints.
| Variable | Description | Default Value |
|---|---|---|
PRKS_STORAGE | Root directory for persistent data. | Project data/ |
PRKS_TESTING | Enables testing paths and stricter security checks. | 0 (false) |
PRKS_LOG_LEVEL | Stderr log level (INFO, DEBUG, etc.). | INFO |
PRKS_LOG_FILE_LEVEL | Persistent file log level. | ERROR |
PRKS_LOG_RETENTION_DAYS | Number of rotated log copies to keep. | 7 |
PRKS_PERF_SLOW_MS | API duration threshold for "slow" requests. | 250 |
PRKS_PERF_LOG_SLOW | Emit logs for slow API requests. | off |
PRKS_BACKUP_MAX_UPLOAD_BYTES | Maximum size for backup archive uploads. | 64 GiB |
Sources: README.md:79-105
Server Startup and Networking
The PRKS application runs a Python process that acts as the entry point for all operations. By default, the server binds to the loopback interface for security.
CLI Options
--port: Defines the listening port. Testing mode defaults to8070, while normal mode defaults to8080.--host: Defines the binding address. Default is127.0.0.1. Use0.0.0.0for LAN access.--testing: Activates testing mode, which usesdata_testing/by default and restricts access to production data.
Sources: README.md:45-76, AGENTS.md:143-146
Security Constraints
PRKS has no built-in application-level authentication. You must not expose the server to untrusted networks without an external access control layer.
Sources: README.md:73-76, AGENTS.md:162-167
Logging and Performance
The backend enforces strict privacy rules for logging. Logs must contain metadata only to prevent leaking research content.
Logging Privacy
The system normalization logic ensures that the following data is never logged:
- User/Library content (titles, notes, annotations).
- Request bodies or query strings.
- Absolute paths and filenames.
- User-provided URLs.
Sources: backend/AGENTS.md:53-60
Performance Diagnostics
The application records aggregate, privacy-safe runtime measurements. These reset when the process restarts. You can enable slow request logging by setting PRKS_PERF_LOG_SLOW=1.
Sources: README.md:98-101, backend/AGENTS.md:65-75
Browser and UI Configuration
Users configure device-specific settings through the "Settings" modal in the frontend.
Settings Categories
- General: Appearance theme (System, Light, Dark) and annotation author name.
- Reading & Layout: Mobile layout overrides and PDF page memory.
- Export: BibTeX field inclusion toggles.
- Backup: Manual download and restore triggers.
- Maintenance: Rebuilding search indexes or linearizing PDFs.
Sources: frontend/index.html:280-420
Theme and Meta Configuration
The application uses a semantic token system for its design. The theme color is strictly defined to ensure consistency across the browser chrome and web app manifest.
| Token | Value |
|---|---|
theme-color | #6d6cf7 |
--accent | #6d6cf7 |
radius | 0 (Square) |
Sources: frontend/index.html:8, scripts/b5_browser_baselines.py:32
Conclusion
PRKS configuration focuses on storage safety and data privacy. By utilizing a hierarchy of resolution for storage and strictly loopback networking, the system ensures research data remains local and secure. Procedures for changing configurations involve modifying environment variables or using the in-app settings menu for UI-specific preferences.