StudentDataGUI is a user-friendly application for managing student data, designed to be easy to set up and use—even for those with little technical experience. It runs inside containers for maximum reliability and simplicity. This guide provides detailed, step-by-step instructions for building, running, and troubleshooting the application, with a focus on using Podman (recommended), and Docker as an alternative.
- StudentDataGUI
StudentDataGUI provides a graphical interface for entering and managing student data. It uses NiceGUI for the interface and SQLite3 for the database. The application is designed to run inside containers, so you don’t need to worry about installing or configuring complicated software.
If you are new to containers, Podman is a modern, rootless alternative to Docker. It is safe, secure, and easy to use.
-
Fedora/Red Hat:
sudo dnf install podman podman-compose
-
Ubuntu/Debian:
sudo apt-get install podman podman-compose
-
For other systems, see the Podman installation guide.
- Download or clone the StudentDataGUI repository to your computer.
-
Open a terminal in the project folder.
-
Make the start script executable (only needed once):
chmod +x start.sh
-
Start the application:
./start.sh start
-
The application will build and run in a container. When ready, open your web browser and go to: http://localhost:8080
-
Build the Application Use the provided script for the easiest experience:
podman compose -f compose.yaml build --no-cache
-
Manual Podman Commands If you prefer, you can use these commands: To start the application, Type the following command and then open http://localhost:8080 in the browser of your choice:
podman compose up -d; podman compose logs -fTo end the application: Close the browser tab or window and then stop the container:
podman-compose down
-
Configuration
-
The application uses port 8080 by default. If this port is busy, you can change it:
export NICEGUI_PORT=8081 ./start.sh start -
Data is now stored in the
/app_homefolder at the project root. All database and student data files are located there.
-
If you prefer Docker, follow these steps:
-
Install Docker and Docker Compose
-
Start the Application
./start.sh start
-
Manual Docker Commands
docker-compose up -d docker-compose logs -f docker-compose down
-
Configuration
- Uses the same environment variables and folders as Podman.
If you run into problems, try these solutions:
-
Permission Denied Errors
-
Make sure you own the data folders:
sudo chown -R $USER:$USER ./data ./database ./logs
-
-
Port Already in Use
-
Change the port:
export NICEGUI_PORT=8081 ./start.sh start
-
-
Build Failures or Application Won't Start
-
Clean and rebuild:
./start.sh clean ./start.sh start -b
-
-
Viewing Logs
-
To see what's happening inside the application:
./start.sh logs
-
-
Checking Status
-
To check if the application is running:
./start.sh status
-
- For container issues, use the troubleshooting steps above.
- For application issues, open an issue on GitHub.
- For accessibility or usability questions, see the Accessibility section below.
StudentDataGUI is designed to be accessible for all users, including those using screen readers or keyboard navigation.
- Uses ARIA landmarks and semantic HTML for easy navigation.
- "Skip to main content" link for keyboard users.
- All buttons and forms have visible, high-contrast focus indicators.
- Error messages are announced to screen readers.
- Dialogs and modals are accessible and manage focus correctly.
- All images and icons have meaningful alternative text or are marked decorative.
- Supports keyboard-only navigation and high-contrast mode.
Known Limitations:
- Some advanced focus trapping in modals may need further improvement.
- Toast notifications may not always be announced by all screen readers.
Reporting Accessibility Issues:
- Open an issue on GitHub with the "Accessibility" label.
- Or contact the maintainer directly via the email address in the repository.
Further Documentation:
- See AccessibilityReport20250722.md for a detailed analysis.
- See AccessibilityTesting.md for a step-by-step testing checklist.
-
Changing the Logo: Replace the logo file (
dsd-mark-white) in the project directory with your own, using the same name and format. Restart the application. -
Updating the GitHub Logo Target: Edit the relevant HTML or configuration file, change the
hreffor the GitHub logo, save, and restart. -
Modifying Footer Copyright: Edit the footer component file, update the copyright text, save, and restart.
-
Fork the repository.
-
Create a new branch:
git checkout -b feature-branch
-
Submit a pull request.
- Follow the Black code formatter for Python code.
The application now creates the following structure in the project root:
<project-root>/app_home
├── errorLogs
├── StudentDataFiles
│ ├── Student1
│ │ ├── AbacusSkillsProgression.csv
│ │ ├── BrailleSkillsProgression.csv
│ │ └── ...
├── backups
├── students20252026.db
- Data Safety: All student data is stored locally in
/app_homeat the project root. Regularly back up theapp_homefolder to prevent data loss. - Updates: To update the application, pull the latest version from GitHub and restart the container.
- Security: Only run the application on trusted computers and networks, especially when handling sensitive student information.
If you have any questions or need further help, please reach out via GitHub or the contact information in this repository.