6.3 KiB
AtlasOS – Calypso
Engineering & Architecture Master Document
(CURSOR.md – Single Source of Truth)
Version: 2.0
Status: Baseline – Product Definition
Target OS: Ubuntu Server 24.04 LTS
Category: Backup Appliance / Tape & VTL Virtualization Platform
Date: 2025
0. Project Definition
AtlasOS – Calypso adalah generic backup appliance yang menyediakan:
- Disk-based backup storage (iSCSI block)
- Physical tape library bridging (SAS / FC → iSCSI)
- Virtual Tape Library (VTL) menggunakan MHVTL
- Unified web-based management GUI
- Authentication, authorization, audit, dan monitoring terpusat
Calypso tidak terikat pada backup software tertentu.
Backup software yang didukung mencakup (namun tidak terbatas pada):
- Bacula
- Veeam
- Dell NetWorker
- Veritas NetBackup
- Commvault
- Arcserve
- Custom / proprietary SCSI-compliant backup engines
Calypso berperan sebagai storage & SCSI virtualization appliance, bukan backup controller.
1. Non-Negotiable Design Rules
-
SCST adalah satu-satunya iSCSI target framework
- Tidak menggunakan LIO / targetcli
- Semua disk, physical tape, dan VTL diexport melalui SCST
-
Mapping tape device wajib konsisten
- LUN 0 → Medium changer
- LUN 1..N → Tape drives (maksimal 8)
- Berlaku untuk:
- Physical tape library
- MHVTL virtual library
-
Single initiator policy untuk tape
- Hanya satu IQN initiator boleh login ke tape target
- Pelanggaran harus terdeteksi dan ditampilkan di UI
-
Backup software agnostic
- Tidak ada logic Bacula / NetWorker / Veeam di core
- Hanya SCSI semantics + optional compatibility profile
-
Tidak ada shell/terminal di UI (v1)
- Semua aksi melalui API tervalidasi
-
Least privilege backend
- Backend berjalan sebagai non-root
- Aksi privileged via polkit atau sudoers allowlist ketat
-
Audit wajib
- Setiap perubahan konfigurasi
- Operasi tape
- Apply iSCSI
- Perubahan IAM
-
Operasi berat bersifat async
- Inventory
- Load / unload
- Rescan
- Apply SCST
- Support bundle
2. Core Appliance Capabilities
2.1 Disk Storage
- LVM-backed repository
- Optional ZFS (advanced SKU)
- Export sebagai iSCSI block device
- Digunakan untuk:
- Disk backup target
- Backing store MHVTL
2.2 Physical Tape Bridge (SAS / FC)
- Discovery changer & drive
- Inventory slot & barcode
- Load / unload tape
- Bridge ke backup software via iSCSI
2.3 Virtual Tape Library (MHVTL)
- Virtual changer, drive, slot, dan tape
- Disk-backed tape image
- Barcode emulation
- Export via SCST iSCSI
- Use case:
- Backup staging
- Copy-to-tape
- Testing / development
- Air-gap simulation
3. High-Level Architecture
Backup Software (Any Vendor) | iSCSI | +--------------------------------+ | AtlasOS – Calypso | | | | Disk Repository (LUN) | | MHVTL (Virtual Tape) | | Physical Tape Bridge | | SCST iSCSI Core | | | +--------------------------------+ | SAS / FC | Physical Tape Library
4. Component List (Authoritative)
4.1 Base Platform
- Ubuntu Server 24.04 LTS
- systemd, journald
- udev persistent naming
- chrony
- ufw / nftables
4.2 Disk Storage Layer
- LVM2
- thin-provisioning-tools
- XFS (primary)
- ext4 (alternative)
- Optional ZFS
- smartmontools, nvme-cli
- parted, gdisk
4.3 Physical Tape Subsystem
- SAS / FC HBA drivers
- multipath-tools (optional)
- lsscsi
- sg3_utils
- mt-st
- mtx
4.4 Virtual Tape Library
- mhvtl
- mhvtl-utils / vtlcmd
- Disk-backed tape images
4.5 iSCSI Target Stack
- scst
- iscsi-scst
- scstadmin
4.6 Calypso Core Application
Backend (Go):
- storage
- tape_physical
- tape_vtl
- scst
- iscsi
- tasks
- system
- monitoring
- audit
- profile_engine
Frontend (React + Vite):
- Dashboard
- Disk Repository
- Physical Tape
- Virtual Tape Library
- iSCSI Targets
- Clients / Initiators
- Tasks & Jobs
- Alerts & Logs
- System & IAM
4.7 Authentication & IAM
- PostgreSQL
- Local auth (Argon2id)
- LDAP
- OIDC SSO
- RBAC
- Audit log
4.8 Monitoring & Observability
- Built-in health checks
- Alerts engine
- Event stream (WebSocket)
- Optional Prometheus exporter
- node_exporter
4.9 Web & Security Perimeter
- Caddy (recommended) / Nginx
- TLS
- Security headers
- Rate limiting
4.10 Packaging & Operations
- Debian packages (.deb)
- systemd services:
- calypso-api
- scst
- mhvtl
- postgresql
- caddy/nginx
- Installer & upgrade scripts
- Support bundle generator
5. Repository Structure (Monorepo)
calypso/ README.md CURSOR.md
docs/ COMPONENT-LIST-AtlasOS-Calypso.md SRS-00-Main-AtlasOS-Calypso.md SRS-01-Storage-Component.md SRS-02-VTL-and-Tape-Bridge.md SRS-03-System-Management.md SRS-04-Auth-and-IAM.md SRS-05-Monitoring-and-Observability.md
frontend/ backend/ deploy/
6. API Design Rules
- Base path
/api/v1 - JSON only
- RBAC + audit untuk endpoint mutating
- Async →
task_id - Task status →
/api/v1/tasks/{id} - WebSocket
/ws:- task progress
- alerts
- inventory
- iSCSI session changes
7. Database Scope (PostgreSQL)
Digunakan untuk:
- Users, roles, permissions
- Sessions & tokens
- Audit log
- Appliance configuration
- Async task state
- Alerts
Tidak digunakan untuk:
- Backup data
- Tape data
8. Coding Standards
Backend
- Go ≥ 1.22
- Context everywhere
- No raw shell execution
- Strict validation
- Unit tests untuk:
- SCST config
- Tape discovery
- Task state machine
- RBAC
Frontend
- TypeScript strict
- API via
src/api - No business logic di component
- Unified error handling
- WebSocket reconnect handling
9. Safety & Guardrails
- Blok aksi berbahaya saat tape aktif
- Cegah:
- multi-initiator tape
- remove active drive
- reconfig SCST saat write
- Konfirmasi wajib untuk destructive action
10. Implementation Phases
- Foundation & Auth
- Disk Repository
- Physical Tape Bridge
- Virtual Tape Library (MHVTL)
- Monitoring & IAM extensions
- UI polish & hardening
11. Definition of Done (DoD)
Feature dianggap selesai jika:
- API implemented
- RBAC enforced
- Audit logged
- UI workflow complete
- Error handled
- Docs updated
12. Final Authority
Jika ada konflik antar dokumen:
FILE INI ADALAH SUMBER KEBENARAN.
AtlasOS – Calypso adalah tape & VTL appliance kelas enterprise.