- 💪🐧 Linux CLI Trainer
Linux CLI Trainer is a full stack web application designed to help users learn and practice basic Linux command line skills.
It provides interactive exercises where users must enter the correct commands based on given prompts. The goal is to help beginners become familiar with the Linux terminal through practice and repetition.
The project is built using a React frontend and an Express (Node.js) backend, with a PostgreSQL database for storing exercises and related data.
The user interface is designed with a focus on usability, accessibility, and responsive design. It aims to be intuitive and easy to navigate, supports both light and dark themes, and adapts to different screen sizes and devices.
- Interactive Linux command line exercises
- Configurable practice sessions (topics, difficulty, and session length)
- Multiple topic categories and three difficulty levels
- Instant feedback on submitted answers with hints
- Session summary showing number of correct answers
- Light and dark themes
- Admin view for managing exercises
- Simple authentication for admin access
- Loading indicators for a smoother user experience
- Responsive UI with navigation drawer and help dialog
- React frontend with an Express REST API backend
- PostgreSQL database for persistent exercise storage
-
Configure your practice session:
- Select one or more topics
- Choose a difficulty level
- Select how many exercises you want to complete.
-
Press Start to begin the session.
-
For each exercise:
- Read the question carefully
- Type the correct Linux command
- Press Submit
-
You will receive immediate feedback:
- ✅ Correct → proceed to the next exercise
- ❌ Incorrect → a hint will be shown
-
Press Next to continue through the exercises.
-
At the end of the session, you will see how many answers you got correct.
-
Open the side menu from the top right corner.
-
Select Admin login.
-
Enter your admin credentials and log in.
-
Choose what you want to manage:
- Exercises
- Topics
-
You can perform the following actions:
- ➕ Create new items
- 👁️ View existing items
- ✏️ Update items
- 🗑️ Delete items
-
Use the Log out button to exit admin mode.
Changes are saved immediately and reflected in the database.
This project is developed as part of a Full Stack Development course at Tampere University of Applied Sciences (TAMK).
The goal of the project is to demonstrate the ability to design and implement a complete full stack application including:
- Frontend development
- RESTful backend API
- SQL database design
- Version control with Git
- Documentation and deployment
- React
- Vite
- Material UI
- Node.js
- Express
- Winston (logging)
- Jest & Supertest (testing)
- PostgreSQL
- Docker
- Git & GitHub
- npm Workspaces
- Prettier
Linux CLI Trainer follows a typical full stack architecture with a React frontend, an Express backend, and a PostgreSQL database.
- The React frontend provides the user interface for practicing Linux CLI exercises.
- The Express backend exposes a REST API for fetching exercise data.
- The PostgreSQL database stores exercises, categories, difficulty levels, and other persistent data.
During development, the frontend runs on a Vite development server and API requests are proxied to the backend. In production, the frontend is built into static files and served by the Express backend.
Browser
↓
React frontend
↓
Express REST API
↓
PostgreSQL database
The frontend follows a component-based architecture.
The structure below illustrates how the main components are composed:
Root
↓
App
├── Header
├── Menu
│ └── LoginDialog
├── HelpDialog
├── StudentMode
│ ├── SettingsCard
│ ├── ExerciseCard
│ └── ResultsCard
├── AdminMode
│ ├── ManageExercises
│ └── ManageTopics
└── Footer
Make sure the following tools are installed:
- Node.js 20+ (the Docker environment uses Node.js 20)
- npm 10+ (tested with Node.js 20 / npm 10)
- PostgreSQL
- Docker (optional)
Clone the repository:
git clone https://github.com/ilkkavv/linux-cli-trainer
cd linux-cli-trainerInstall dependencies:
npm install
Important
Before starting the development servers, you must create the PostgreSQL database and the .env file.
See the instructions below.
Start the development servers:
npm run start
The frontend will run on the Vite development server, and API requests will be proxied to the backend.
Refer to the PostgreSQL documentation for instructions on how to:
- install PostgreSQL
- start the database server
- create a new database
Once you have created a database, run the initialization script from the repository root directory:
psql -d <database> -f database/init.sqlThis will:
- Create the database schema
- Insert seed data
- Execute all scripts in the correct order
Note
For more information about the project database, see the database documentation.
Create a .env file in the backend directory.
A template file .env.example is included in the repository. You can create the .env file by copying it and updating the values:
cp backend/.env.example backend/.envThese variables are required for the application to start:
DATABASE_URL=postgres://USER:PASSWORD@HOST:PORT/DATABASE
ADMIN_USERNAME=your_admin_username
ADMIN_PASSWORD=your_admin_passwordThe .env file is ignored by Git and should never be committed to the repository.
This repository includes a Dockerfile that can be used to build and run the application in a container.
Build the Docker image:
docker build -t linux-cli-trainer .
Run the container:
docker run --env-file ./backend/.env -p 3000:3000 linux-cli-trainer
Note
The Docker image in this repository only runs the application. It does not create or run a PostgreSQL database inside the container.
Keeping the application and database separate allows the application to connect to an external database, such as a cloud-hosted PostgreSQL instance. In the deployed version of this project, the application and the database run as separate services (Render for the app and Neon for PostgreSQL).
If you want to run both the application and PostgreSQL locally with Docker, additional setup is required (for example, using Docker Compose with a separate PostgreSQL container).
Backend tests are implemented using Jest and Supertest.
To run the tests:
npm run test-backendThe test suite includes:
- Basic API endpoint tests
- Error handling (e.g. invalid input, unknown routes)
- Admin authentication flow (login, session, logout)
Note
The test suite is minimal and not fully comprehensive. It was created primarily for learning and experimenting with Jest and Supertest, rather than as a complete production-level test coverage.
The application is deployed as a live demo on Render.
The PostgreSQL database is hosted on Neon.
The production deployment runs the application inside a Docker container, where the React frontend is built and served as static files by the Express backend.
If the frontend and backend were deployed separately (different origins), CORS configuration would be required in the backend.
Project versions follow semantic versioning (MAJOR.MINOR.PATCH) and are published using GitHub Releases.
Each release represents a milestone in the development process:
- 1.0.0-alpha – Initial MVP
- 1.0.0-beta – Feature improvements
- 1.0.0-rc – Release candidate
- 1.0.0 – Final version
The deployed version is based on the latest GitHub release.
The backend exposes a REST API for retrieving Linux CLI exercises, validating user answers, and managing exercise content.
The API includes both public user endpoints and admin-protected endpoints. Administrative routes require authentication via a session-based login.
The API follows standard HTTP status codes (200 OK, 400 Bad Request, 401 Unauthorized, etc.)
Admin routes are protected using session-based authentication.
To access admin endpoints:
- Log in via
/api/admin/login - The server sets an HTTP-only cookie (
admin_session) - Subsequent requests automatically include authentication via the cookie
Sessions are stored in memory on the server.
This project uses a simplified authentication approach for admin access.
Admin credentials are stored in environment variables (.env) instead of a database.
This was a deliberate design choice, as full authentication and user management were not covered during the course.
Admin credentials are configured via environment variables and are not persisted in the database.
The solution is intended for demonstration and learning purposes.
/api/exercises/api/topics/api/admin
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/exercises/random |
Returns random exercises based on selected filters |
| GET | /api/exercises |
Returns all exercises with topic data |
| GET | /api/exercises/:id |
Returns a single exercise by ID |
| POST | /api/exercises/check |
Validates the user's answer for an exercise |
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/topics |
Returns all available exercise topics |
These routes handle admin authentication and session management. They are used to create and verify authentication state and do not require an existing session.
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/admin/login |
Logs in admin and creates session |
| POST | /api/admin/logout |
Ends admin session |
| GET | /api/admin/session |
Checks authentication status |
All admin routes require a valid session cookie obtained from login and are protected by authentication middleware.
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/exercises |
Create a new exercise |
| PUT | /api/exercises/:id |
Update an existing exercise |
| DELETE | /api/exercises/:id |
Delete an exercise |
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/topics |
Create a new topic |
| PUT | /api/topics/:id |
Update a topic |
| DELETE | /api/topics/:id |
Delete a topic |
GET http://localhost:3000/api/exercises/1
Response:
{
"id": 1,
"topic_id": 1,
"difficulty": "beginner",
"question": "Navigate up from the current location.",
"correct_answer": "cd ..",
"hint": "Use cd with two dots to move to the parent directory."
}POST http://localhost:3000/api/topics
{
"name": "Networking"
}Response:
{
"id": 6,
"name": "Networking"
}This project is primarily based on course lectures and previous assignments.
In addition, the following external resources were used to support learning React and Express development:
- Material UI documentation and examples
- Sam Meech-Ward (Youtube channel)
- Stack Overflow
- Web Dev Simplified (YouTube channel)
ChatGPT (OpenAI GPT-5.3) was used during this project primarily as a learning aid. The tool was mainly utilized to clarify course concepts and to help with proofreading and improving documentation (README, code comments, and commit messages).
AI was also used for the following tasks:
- Generating Linux command exercises for the application
- Learning and understanding React and Material UI
- Learning and understanding authentication concepts
- Clarifying error messages during development
This project is licensed under the GNU General Public License v3.0 (GPL-3.0).
You are free to use, modify, and distribute this project, provided that any derivative work is also distributed under the same license.
See the LICENSE file for details.