Install and verify the software

Status: Draft

Purpose

Install the open-source NTRIP caster in an isolated workspace. Verify the installation with the project tests before you configure hardware or deploy a service.

Learning objectives

After this lesson, you can:

Check the project prerequisites.
Create a Python virtual environment.
Install the pinned dependencies.
run the complete automated test suite.
Interpret the start script's precondition checks.

Prerequisites

Complete Lesson 1. You need Python 3 and a command line. Use an isolated copy of the repository.

Key terms

Repository: The project files used to build and run the software.
Virtual environment: An isolated Python runtime and package location.
Dependency: A package required by the application.
Pinned version: The exact package version declared by the project.
Test suite: Automated checks supplied with the project.
Entry point: The file or command that starts the application.

Concept explanation

Installation boundary

Installation prepares the software. Configuration connects it to a site. Deployment runs it as a managed service. Keep these stages separate.

The repository declares its Python packages in requirements.txt. The Linux start script requires two local items:

an executable .venv/bin/python
a config.yaml file in the application directory

The start script changes to the project directory and uses absolute paths after it starts. This makes service startup less dependent on the caller's current directory.

Supported installation sequence

On Linux, run from the project directory:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt

Run the complete tests:

.venv/bin/python -m unittest discover -v

Do not treat a successful dependency installation as proof that the application is ready for a real receiver. The configuration, serial permissions, receiver mode, and network boundary still require review.

Expected test scope

The current tests cover receiver command behaviour and RTCM or monitoring behaviour. A passing result is useful evidence for the tested code. It does not prove a complete field installation.

Worked demonstration

An instructor uses a clean project copy.

Confirm that no .venv exists in the exercise copy.
Create the environment.
Install the declared requirements.
Run the complete test command.
Record the number of successful tests.
Run ./start_ntrip_caster only in the isolated exercise environment.
Observe the first unmet precondition, such as a missing safe configuration.

Expected result: the tests pass. The start script either starts with an approved exercise configuration or stops with a clear precondition error.

Guided practice

Perform the installation in an exercise copy.

Record the Python version.
Create .venv.
Confirm that .venv/bin/python exists on Linux.
Install requirements.txt.
Run all tests.
Save only the command, final result, and any safe error text.

Do not submit package caches, the complete virtual environment, or sensitive local paths.

Independent practice

Repeat the installation in a new clean exercise copy. Do not reuse the first virtual environment. Explain why the second result is stronger evidence of a repeatable installation.

Checks for understanding

Why must the test suite run before deployment?
What does requirements.txt control?
Why should the virtual environment not be copied to the Linux host?
What two preconditions does the start script check?
Does a passing test suite prove that receiver coordinates are correct?

Assessment and evidence

Install the project in a clean exercise workspace. Submit:

Python version
environment creation result
dependency installation result
final automated test summary

Do not submit credentials, site configuration, or the virtual environment.

Troubleshooting guidance

Symptom	First check
`python3` is not found.	Confirm the supported Python installation and command name.
Environment creation fails.	Check write permission in the exercise directory.
Package installation fails.	Check the pinned requirement and package error. Do not select another version without review.
Tests cannot import the project.	Run the command from the repository root with the environment Python.
Start script reports no environment.	Confirm `.venv/bin/python` exists and is executable.
Start script reports no configuration.	Do not copy a live configuration. Continue with Lesson 3.

Summary

Install the pinned dependencies in a project-local virtual environment. Run the complete tests before configuration or deployment. Treat tests as evidence of the behaviours they cover, not proof of a complete field system.

Source references

SRC-PROJECT-OVERVIEW: supported Linux commands and test scope
SRC-PROJECT-CODE: start script and pinned dependencies
SRC-PROJECT-TESTS: current automated test behaviours