A multi-user, distributed, remotely accessible backup service, designed around zero-trust, and defense-in-depth principles.
This is my Bachelor's degree thesis project in Computer Science at the University of Udine, supervised by Prof. Ivan Scagnetto. Read the full thesis (PDF).
This project is designed by Francesco Verrengia and Riccardo Gottardi
Warning
RAM-USB is a proof of concept and a design exercise for this thesis, not production-ready software. It has not undergone independent security review, and it is not intended for storing real backups or any other serious use.
RAM-USB is built as an in-depth case study on the secure design of distributed backup systems.
For this thesis, design counts more than implementation: getting the architecture, the trust boundaries, and the data flows right is the actual goal.
The Software Requirements Specification is the single source of truth for what this system must do, and the design diagrams show how every part fits together: use cases, architecture, data model, security, and operational flows, each rendered as an SVG you can open directly from the repo.
- Zero-trust: no component implicitly trusts data received from another, even when mutually authenticated.
- Defense-in-depth: every layer independently re-validates input, regardless of upstream checks.
RAM-USB is an n-tier client-server microservices architecture made up of 11 Docker containers, connected over a private Headscale mesh VPN with mTLS between every internal service.
| Component | Role | Status |
|---|---|---|
| User-Client | CLI client: registers, authenticates, backs up/restores files via restic over SFTP |
Done |
| Entry-Hub | Public-facing HTTPS gateway; validates and forwards requests | Done |
| Security-Switch | Internal request router and re-validator | Done |
| Database-Vault | User data persistence (PostgreSQL), credential hashing/encryption | Done |
| Storage-Service | Per-user isolated, chrooted SFTP storage for encrypted backups | Done |
| Network-Manager | Headscale ACL and mesh access control | Done |
| Headscale | Self-hosted Tailscale coordination server for the private mesh VPN | Done |
| Mosquitto (MQTT broker) | Metrics transport between services and the collector | Done |
| Metrics-Collector | Ingests and stores metrics (TimescaleDB) | Done |
| Metrics-Visualizer (Grafana) | Operational dashboards | Done |
| Certificate-Authority | Issues and rotates mTLS certificates (smallstep/certificates) | Done |
- Language: Go
- Personal data persistence: PostgreSQL
- Metrics persistence: TimescaleDB
- Backup persistence: CephFS (target)
- Networking: Headscale
- Client-side compression, encryption and deduplication: restic
- Certificates: smallstep/certificates (private components), Let's Encrypt (public-facing endpoints)
- Deployment: Docker, Proxmox VE
Each component ships its own Docker Compose file under deployments/compose/, one per service. See MANUAL-DISTRIBUTED-RUN.md for the full startup procedure (one terminal per container, correct boot order, and known sharp edges).
This project follows:
- Spiral model for requirements: the SRS is refined iteratively across the versions
- V-model for implementation: tests are written before code (pre-testing, to validate that requirements are testable), and each level of specification has a corresponding level of testing.
- Conventional Commits, scoped by component and tagged with requirement IDs, for full bidirectional traceability between code and requirements.
Parts of the implementation are carried out with the help of Claude Sonnet 5, used strictly as an implementation tool under close supervision.
- I am responsible for: design, code structure, module boundaries, individual function signatures and behavior, and the corresponding tests.
- Claude implements exactly, and only, what I specify, in small, incremental steps, so that each change is small enough for me to fully verify before moving on.
- No change is integrated into the codebase without my review and explicit approval. Nothing generated is merged, committed, or trusted by default; every step is checked against the requirement it is meant to satisfy before it becomes part of the project.
- Thesis (PDF): full write-up of the design and rationale behind this project
- Software Requirements Specification: full requirements, use cases, and known risks
- Contributing guidelines: commit conventions, branching model, workflow
Distributed under the MIT License.
Francesco Verrengia, Riccardo Gottardi