Conversation
… and backend provisioning
…ment and DB migrations
… via .bash_profile
There was a problem hiding this comment.
Pull request overview
This PR establishes comprehensive development guidelines, improves deployment workflows, and enhances the offline-first architecture of the digitization toolkit. It introduces strict documentation for architecture decisions, CSS practices, and icon usage while streamlining Docker configurations for both development and production environments.
Changes:
- Added AI assistant instructions documenting critical architecture patterns, deployment modes, and development workflows
- Created frontend-specific guidelines for CSS organization and Material Symbols icon usage
- Implemented production-ready scripts for setup, update, and kiosk deployment on Raspberry Pi
- Refactored Docker Compose configurations to separate development and production builds with improved health checks
- Updated README with detailed SD card provisioning instructions for offline distribution
Reviewed changes
Copilot reviewed 23 out of 24 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
.github/copilot-instructions.md |
Core architecture documentation covering deployment modes, database migrations, authentication, and development policies |
.github/instructions/frontend.instructions.md |
Frontend CSS rules requiring all styles in app.css with CSS variable usage |
.github/instructions/icons.instructions.md |
Material Symbols icon usage guidelines with allowed icon reference table |
docker-compose.yml |
Production configuration with multi-stage frontend build and improved health checks |
docker-compose.dev.yml |
Development overrides for Vite dev server with live reload |
scripts/setup.sh |
One-time provisioning script for initial Pi setup with internet |
scripts/update.sh |
Update script for applying code changes to running Pi installations |
scripts/start.sh |
Production startup script using Pi overlay configuration |
scripts/start-dev.sh |
Development startup using dev overlay |
scripts/start-kiosk.sh |
Wayland kiosk mode launcher for Chromium fullscreen |
scripts/install-service.sh |
Systemd service installation with setup guards |
scripts/install-kiosk-service.sh |
Autologin and kiosk auto-start configuration |
README.md |
Expanded documentation for setup, deployment, and SD card imaging |
Comments suppressed due to low confidence (4)
scripts/installkb.sh:25
- Hardcoded path
~/dtk/assumes a specific installation directory. Consider using$PROJECT_ROOTvariable (like in other scripts) or documenting this assumption more clearly, as the actual installation path may vary.
echo " ~/dtk/scripts/start-kiosk.sh"
scripts/installkb.sh:32
- Hardcoded path
~/dtk/assumes a specific installation directory. Consider using$PROJECT_ROOTvariable (like in other scripts) or documenting this assumption more clearly, as the actual installation path may vary.
echo " 2. Then run: sudo ~/dtk/scripts/install-kiosk-service.sh"
docker-compose.yml:27
- Health check interval of 2 seconds with 15 retries creates 30 seconds of polling every 2 seconds during startup. Consider increasing the interval to 5s while keeping retries at 6 for similar total wait time (30s) with less resource usage.
interval: 2s
timeout: 5s
retries: 15
.github/copilot-instructions.md:264
- Consider adding a period at the end of this list item for consistency with other items in the 'Common Mistakes AI Agents Make' section.
10. ❌ Replacing `frontend/Dockerfile` (production multi-stage build) with `Dockerfile.dev` in `docker-compose.yml` — that would re-introduce npm downloads at startup and break offline use
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| for i in $(seq 1 30); do | ||
| if $COMPOSE exec -T db pg_isready -U "${DATABASE_USER:-user}" -d "${DATABASE_NAME:-digitization_toolkit}" >/dev/null 2>&1; then |
There was a problem hiding this comment.
The hardcoded database credentials user and digitization_toolkit are duplicated across multiple scripts (setup.sh line 107, update.sh line 73). Consider extracting these to a shared variable or sourcing from .env to ensure consistency across scripts.
| echo "" | ||
| # Start native backend | ||
| ./scripts/run_backend_native.sh | ||
| cd "$PROJECT_ROOT/backend" && "$PIXI" run start |
There was a problem hiding this comment.
The pixi task start is referenced but the copilot-instructions.md documentation only mentions dev as the available pixi task for starting the server (lines 22, 165, 246, 276). This inconsistency may cause the script to fail if the start task doesn't exist in pixi.toml.
| cd "$PROJECT_ROOT/backend" && "$PIXI" run start | |
| cd "$PROJECT_ROOT/backend" && "$PIXI" run dev |
| KIOSK_USER="${SUDO_USER:-pi}" | ||
| KIOSK_HOME=$(eval echo "~$KIOSK_USER") | ||
| BASH_PROFILE="$KIOSK_HOME/.bash_profile" | ||
| KIOSK_SCRIPT="/home/pi/dtk/scripts/start-kiosk.sh" |
There was a problem hiding this comment.
Hardcoded path /home/pi/dtk/ should use $PROJECT_ROOT or derive from script location for consistency with other scripts that use SCRIPT_DIR and PROJECT_ROOT variables.
| WorkingDirectory=/home/pi/dtk | ||
|
|
||
| # Ensure pixi and docker are on PATH (systemd uses a stripped environment) | ||
| Environment="PATH=/home/pi/.pixi/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" | ||
|
|
||
| # Start the application | ||
| ExecStart=/home/pi/dtk/scripts/start.sh | ||
| ExecStop=/home/pi/dtk/scripts/stop.sh |
There was a problem hiding this comment.
Hardcoded installation paths /home/pi/dtk/ limit flexibility. The install-service.sh script should template these paths based on actual installation location.
| WorkingDirectory=/home/pi/dtk | |
| # Ensure pixi and docker are on PATH (systemd uses a stripped environment) | |
| Environment="PATH=/home/pi/.pixi/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" | |
| # Start the application | |
| ExecStart=/home/pi/dtk/scripts/start.sh | |
| ExecStop=/home/pi/dtk/scripts/stop.sh | |
| WorkingDirectory=%h/dtk | |
| # Ensure pixi and docker are on PATH (systemd uses a stripped environment) | |
| Environment="PATH=%h/.pixi/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" | |
| # Start the application | |
| ExecStart=%h/dtk/scripts/start.sh | |
| ExecStop=%h/dtk/scripts/stop.sh |
This pull request introduces comprehensive architectural documentation and strict development guidelines for the digitization toolkit, clarifies deployment patterns, and improves developer onboarding. It also updates the Docker setup for development, enhances health check reliability, and provides clear instructions for frontend styling and icon usage. The backend is updated to the latest commit, and the README is expanded to cover SD card provisioning and offline deployment.
Documentation & Development Guidelines
.github/copilot-instructions.mddetailing critical architecture decisions, deployment modes, backend plugin system, database migration workflow, authentication, configuration, dependency management (pixi), testing strategy, file organization, and strict policies for documentation and scripts..github/instructions/frontend.instructions.mdspecifying strict CSS rules (all styles infrontend/static/app.css), usage of CSS variables, component styling patterns, screen size optimization, and Svelte component structure..github/instructions/icons.instructions.mdoutlining icon usage rules: only Material Symbols Outlined font, required markup patterns, modifier classes, and icon selection guidance.Deployment & Docker Improvements
docker-compose.dev.ymlto provide development overrides: frontend runs Vite dev server with live reload, backend runs migrations automatically, and node_modules are mounted for hot updates.docker-compose.ymlhealth check for PostgreSQL (shorter interval, more retries, faster start period) and clarified backend startup instructions for Raspberry Pi and development.Project Setup & Distribution
README.mdto clarify dev and production startup, backend dependency management with pixi, and step-by-step SD card provisioning for offline deployment. Added a summary table of what is self-contained after setup.Backend Update