Docker Setup
Relevant source files
The following files were used as context for generating this wiki page:
Docker Setup provides a containerized environment for running PRKS, ensuring consistent behavior across different host systems. It packages the Python application, its dependencies, and the frontend assets into a single image, while managing persistent storage through volume mounts.
The system uses Docker Compose to orchestrate the container lifecycle, networking, and environment configuration. It enforces a secure-by-default posture by binding the application service to the host loopback interface and running the process with non-root user privileges derived from the host user.
Sources: README.md:121-125, docker-compose.yml:1-10
Image Construction
PRKS uses a shell script, docker-build.sh, to manage the image creation process. The script builds a local image tagged as prks:latest and performs cleanup by pruning dangling images from previous builds.
The build process involves bundling the classic frontend into ordered JavaScript bundles to reduce the number of network requests from 84 to 2. You can disable this bundling by passing a specific build argument during the build process.
The build flow ensures static assets are optimized for container distribution while allowing for unbundled development builds.
Sources: docker-build.sh:1-10, README.md:121-127, backend/dependency_gate.py:1125-1135
Orchestration and Runtime Configuration
docker-compose.yml defines the operational parameters for the PRKS service. The configuration ensures that the containerized application matches the host user's file permissions and manages persistent data outside the container lifecycle.
Container Environment
The container uses a custom entrypoint script, docker-entrypoint.sh, which performs initial setup tasks before launching the application. It ensures the existence of required directory structures and configures the Python process to listen on all container interfaces (0.0.0.0) so that Docker can forward traffic from the host.
Sources: docker-entrypoint.sh:1-10, README.md:131-135
Service Definitions
The following table summarizes the configuration applied in the standard Docker Compose setup:
| Property | Value | Description |
|---|---|---|
| Image | prks:latest | The locally built application image. |
| User | ${UID}:${GID} | Matches host user/group IDs for file ownership. |
| Network | 127.0.0.1:8080:8080 | Maps host port 8080 to container port 8080 on loopback. |
| Storage Root | /data | The internal path for persistent application data. |
| Host Volume | ./data | Maps local data directory to the container. |
Sources: docker-compose.yml:5-20, README.md:131-135
Persistent Data Layout
Persistent storage is handled by mapping a host directory to the container's /data directory. The application expects specific subdirectories within this root to manage different types of research material and system state.
The diagram illustrates how internal container paths map to the persistent storage root provided by the host.
Sources: README.md:144-150, docker-compose.yml:14-16
Security and Networking
The Docker setup implements a "no application-level authentication" security model. By default, Docker Compose binds the published port only to 127.0.0.1 (loopback) on the host. This prevents external access from the local area network (LAN) unless explicitly overridden by the user.
To enable LAN access, you must set the PRKS_PUBLISH_HOST environment variable to 0.0.0.0. This should only be performed on trusted networks.
Execution Policy for Agents
Automated agents and contributors are restricted from running Docker Compose or the real application unless they receive explicit "run-real" authorization from a user. The default execution path for development and testing remains the local Python process with the --testing flag.
Sources: README.md:128-131, README.md:137-142, AGENTS.md:76-85
Summary
The Docker Setup for PRKS simplifies deployment by encapsulating the environment while maintaining strict data persistence through host volume mapping. It prioritizes local security by restricting network exposure to the host loopback by default and ensures compatibility with host file systems by synchronizing user and group identities. Developers use docker-build.sh for optimized asset bundling, and docker-compose.yml for consistent service orchestration.