Deploy and manage remote access

Status: Draft

Purpose

Deploy the tested caster to an isolated Linux host. Operate it as a managed service through approved SSH access on a trusted network or VPN.

Learning objectives

After this lesson, you can:

1. Prepare the Linux host and service account.
2. Transfer the application without transferring live configuration.
3. Install the runtime on the target host.
4. Create and manage the systemd service.
5. Inspect redacted logs and perform a safe rollback.

Prerequisites

Complete Lessons 1 to 3. The local tests must pass. An instructor must approve the host, remote-access method, and sanitised configuration.

Key terms

• SSH: A secure remote shell and file-transfer channel.
• VPN: A protected network path between approved systems.
• Service account: The operating-system user that runs the caster.
• systemd: The Linux service manager used by this project guide.
• Working directory: The directory from which the service runs.
• Rollback: A controlled return to the previous known state.

Concept explanation

Deployment boundary

The supplied Windows deployment helper uses tar, scp, and ssh. It copies application files to ~/ntrip_caster. It excludes YAML files, documentation, virtual environments, caches, and Git data. It does not install dependencies or restart the application.

This behaviour protects site configuration from accidental replacement. It also means the operator must prepare the runtime and configuration on the target.

Remote access boundary

Use SSH only through the approved network or VPN. Do not expose the caster or monitor directly to the public internet. Record hostnames and account names as placeholders in learner evidence.

Serial permission

On Linux, use a stable receiver path under /dev/serial/by-id/ when available. The service account normally needs access through the dialout group. A group change normally requires a new login session or reboot before it takes effect.

Service behaviour

The service runs start_ntrip_caster from the project directory. It starts after the network becomes available. It restarts after a failure. The service log must confirm fixed or survey-in receiver mode before the stream is treated as ready.

Worked demonstration

From an approved Windows workstation, the instructor runs:

.\_scripts\windows\deploy.ps1 -Target <user>@<host>

Expected result: application files are copied to ~/ntrip_caster. YAML files are not replaced. Dependencies are not installed. The service is not restarted.

On the Linux host, the instructor then prepares the environment:

cd ~/ntrip_caster
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
chmod +x start_ntrip_caster

The instructor reviews the service definition from the project overview before placing it in /etc/systemd/system/ntrip-caster.service.

After approval:

sudo systemctl daemon-reload
sudo systemctl enable --now ntrip-caster.service
systemctl status ntrip-caster.service
journalctl -u ntrip-caster.service -f

Expected result: the service is active and the log confirms the selected receiver mode.

Guided practice

1. Confirm the target is the isolated course host.
2. Record the current application version and service state.
3. Run the deployment helper with placeholder evidence.
4. Confirm that the target configuration was not replaced.
5. Create or update the target virtual environment.
6. Review the service account and serial permission.
7. Review the service definition before installation.
8. Reload systemd and start the service.
9. Check service status and receiver-mode logs.
10. Stop and start the service once.

Expected result: the service is controllable and uses the intended project and configuration.

Independent practice

Perform a controlled update and rollback in the assessment host snapshot. Keep the previous application directory or host snapshot until the new service has passed its checks.

Checks for understanding

1. Which files does the deployment helper exclude?
2. Does the helper install dependencies or restart the service?
3. Why should the receiver use a stable serial path?
4. Which log result confirms the selected receiver mode?
5. What must be retained before a controlled update?

Assessment and evidence

Deploy to the isolated host and demonstrate:

• successful transfer
• correct runtime preparation
• reviewed service definition
• active service status
• redacted receiver-mode log
• controlled stop, start, and rollback plan

Troubleshooting guidance

Summary

Deployment copies application code but protects target configuration. Prepare the target runtime separately. Use a reviewed systemd service, approved remote access, stable serial permissions, and a tested rollback path.

Source references

• SRC-PROJECT-OVERVIEW: Linux environment, service, log, and permission procedures
• SRC-PROJECT-CODE: deployment helper and start-script behaviour