docs: [#31] add core concepts and deployment locality + provider isolation scope

josecelano · josecelano · commit da89922e1b7e · 2025-08-12T14:28:50.000+01:00
- Add comprehensive core concepts documentation with 5 fundamental concepts:
  - Environment: Complete operational tracker instance configuration
  - Environment Goal: Development lifecycle purpose categorization
  - Provider: Infrastructure platform abstraction (libvirt, hetzner)
  - Provider Context: Provider-specific config, credentials, resources
  - Deployment Locality: Local vs remote infrastructure provisioning

- Document provider account resource isolation as explicit out-of-scope
  - Clarify limitations of multiple environments in same provider account
  - Explain lack of resource-level isolation mechanisms
  - Provide workarounds (Hetzner projects, AWS separate accounts)

- Enhanced project-words.txt with technical terminology

Establishes clear conceptual foundation for redesign phase based on PoC
development experience. Addresses deployment patterns and scope boundaries
for contributor clarity.
diff --git a/docs/redesign/phase0-goals/project-goals-and-scope.md b/docs/redesign/phase0-goals/project-goals-and-scope.md
@@ -93,6 +93,30 @@ the barrier to tracker adoption.**
 - **Acceptable**: Provider-specific manual configuration where APIs are insufficient
 - **Focus**: Automate the 90% that provides the most value
 
+### Provider Account Resource Isolation
+
+**Rationale**: Provider-level resource isolation requires complex provider-specific
+implementation that varies significantly across cloud providers.
+
+- **Not included**: Resource name prefixes for environment isolation
+- **Not included**: Private network creation for environment separation
+- **Not included**: Provider-specific isolation mechanisms (VPCs, resource groups, etc.)
+- **Not included**: Automatic project/account boundary management
+
+**Implication**: Multiple environments deployed to the same provider account will
+create independent resources (VMs, storage, networking) but these resources remain
+visible and potentially accessible to each other within the provider account scope.
+
+**Provider-Specific Workarounds**: Some providers offer account-level isolation:
+
+- **Hetzner Cloud**: Use separate projects with project-specific API tokens for true isolation
+- **AWS**: Use separate accounts or strict IAM policies per environment
+- **Application Perspective**: The installer treats each provider context (token/credentials)
+  as a completely isolated infrastructure boundary, regardless of actual provider-level separation
+
+**Alternative**: Manual provider account management and project separation by users who
+require strict environment isolation.
+
 ## Target Audience
 
 ### Primary Users
diff --git a/docs/redesign/phase1-requirements/core-concepts-and-terminology.md b/docs/redesign/phase1-requirements/core-concepts-and-terminology.md
@@ -0,0 +1,248 @@
+# Core Concepts and Terminology
+
+## Overview
+
+This document defines the fundamental concepts used throughout the Torrust Tracker
+installer project. These definitions establish clear terminology for technical
+contributors and eliminate ambiguity in design discussions.
+
+## Core Concepts
+
+### Environment
+
+**Definition**: A complete, operational tracker instance configuration that can be
+deployed to any supported infrastructure provider.
+
+**Purpose**: Represents a complete deployment target with all necessary configuration
+to install and run the Torrust Tracker.
+
+**Characteristics**:
+
+- Contains all configuration needed for tracker deployment
+- Independent of deployment stage (provisioned, deployed, or running)
+- Can target local or remote infrastructure
+- Multiple environments can exist simultaneously
+- Each environment is isolated and self-contained
+
+**Examples**:
+
+- `dev-local` - Developer's local testing environment using libvirt
+- `staging-hetzner` - Staging environment on Hetzner Cloud
+- `prod-aws` - Production environment on AWS
+
+### Environment Goal
+
+**Definition**: The intended purpose or stage of an environment within the
+development lifecycle.
+
+**Purpose**: Categorizes environments by their intended use case to apply
+appropriate configuration defaults and constraints.
+
+**Valid Values** (closed set):
+
+- `development` - Local development and debugging
+- `testing` - Automated testing environments
+- `e2e-testing` - End-to-end integration testing
+- `staging` - Pre-production validation
+- `production` - Live production deployment
+
+**Characteristics**:
+
+- Single environment goal per environment
+- Multiple environments can share the same goal (e.g., multiple developers
+  each have their own `development` environment)
+- Goals typically have one instance for shared environments (`staging`,
+  `production`) and multiple instances for personal environments (`development`)
+
+**Configuration Impact**:
+
+- Development: Relaxed security, debug logging, self-signed certificates
+- Testing: Isolated, reproducible, fast deployment/teardown
+- Staging: Production-like configuration, real SSL certificates, monitoring
+- Production: Maximum security, performance optimization, backup automation
+
+### Provider
+
+**Definition**: A supported infrastructure platform or virtualization technology
+that can host Torrust Tracker deployments.
+
+**Purpose**: Defines the technical capabilities and API interfaces available
+for deploying infrastructure.
+
+**Currently Supported**:
+
+- `libvirt` - Local KVM/QEMU virtualization for development
+- `hetzner` - Hetzner Cloud platform for remote deployments
+
+**Provider Capabilities**:
+
+- Virtual machine provisioning and management
+- Network configuration and firewall rules
+- Storage management and backup capabilities
+- API interfaces for automation
+- Resource scaling and optimization features
+
+**Provider-Agnostic Design**: The installer abstracts provider-specific
+implementation details, allowing environments to be portable across different
+providers with minimal configuration changes.
+
+### Provider Context
+
+**Definition**: The complete set of provider-specific configuration, credentials,
+and resource specifications needed to deploy to a specific provider account.
+
+**Purpose**: Contains all provider-specific details required for actual
+deployment while keeping environment definitions provider-agnostic.
+
+**Components**:
+
+- **Authentication**: API tokens, credentials, access keys
+- **Resource Specifications**: VM sizes, storage types, network configurations
+- **Regional Settings**: Data center locations, availability zones
+- **Account-Specific**: Quotas, limits, billing preferences
+
+**Examples**:
+
+- `hetzner-personal` - Personal Hetzner account with CPX31 servers in Nuremberg
+- `hetzner-company` - Company Hetzner account with dedicated servers in Helsinki
+- `libvirt-workstation` - Local development machine with 8GB RAM allocation
+
+**Isolation Scope**: Provider contexts represent individual cloud accounts or
+infrastructure boundaries. Multiple environments can share a provider context,
+but isolation between environments within the same account is limited to
+resource naming and network separation.
+
+### Deployment Locality
+
+**Definition**: The physical location where infrastructure provisioning occurs,
+determining whether resources are created locally on the installer machine or
+remotely via cloud APIs.
+
+**Purpose**: Distinguishes between local virtualization-based deployments and
+remote cloud-based deployments, affecting resource management, networking,
+and access patterns.
+
+**Types**:
+
+- **Local Deployment**: Infrastructure provisioned on the machine running the installer
+
+  - Uses local virtualization (libvirt/KVM, VirtualBox, etc.)
+  - Resources consume local machine CPU, memory, and storage
+  - Network access through local hypervisor networking
+  - Examples: `libvirt`, local Docker containers
+
+- **Remote Deployment**: Infrastructure provisioned via remote cloud provider APIs
+  - Uses cloud provider services (Hetzner Cloud, AWS, Azure, etc.)
+  - Resources allocated from provider's infrastructure pool
+  - Network access through cloud provider networking
+  - Examples: `hetzner`, `aws`, `azure`
+
+**Characteristics**:
+
+- Determines resource allocation source (local vs. cloud)
+- Affects networking configuration and accessibility
+- Influences cost model (local resources vs. cloud billing)
+- Defines deployment workflow (local commands vs. API calls)
+
+**Implementation Note**: Currently supported deployment localities are `libvirt`
+(local) and `hetzner` (remote). The architecture supports extension to additional
+providers of both types.
+
+## Relationship Diagram
+
+```text
+Environment
+├── Environment Goal (development|testing|staging|production)
+├── Provider Context
+│   ├── Provider (libvirt|hetzner|aws)
+│   ├── Authentication (API tokens, credentials)
+│   ├── Resource Specs (VM size, storage, network)
+│   └── Regional Settings (location, zones)
+└── Tracker Configuration
+    ├── Application Settings (ports, features, logging)
+    ├── Security Configuration (SSL, authentication)
+    └── Operational Settings (backups, monitoring)
+```
+
+## Usage Patterns
+
+### Development Workflow
+
+1. **Create Environment**: Define new environment with goal and provider context
+2. **Configure Application**: Set tracker-specific settings for the environment
+3. **Deploy Infrastructure**: Provision resources using provider context
+4. **Deploy Application**: Install and configure tracker software
+5. **Validate Deployment**: Test functionality and performance
+6. **Iterate**: Update configuration and redeploy as needed
+
+### Environment Naming Convention
+
+**Recommended Pattern**: `{goal}-{provider}-{identifier}`
+
+**Examples**:
+
+- `dev-libvirt-alice` - Alice's local development environment
+- `staging-hetzner-main` - Primary staging environment on Hetzner
+- `prod-aws-primary` - Primary production environment on AWS
+- `e2e-libvirt-ci` - CI/CD end-to-end testing environment
+
+### Configuration Inheritance
+
+**Hierarchy** (most specific wins):
+
+1. Environment-specific configuration
+2. Environment goal defaults
+3. Provider context defaults
+4. Global system defaults
+
+This hierarchy allows environments to inherit sensible defaults while
+enabling complete customization when needed.
+
+## Implementation Notes
+
+### Environment Identification
+
+**Current Approach**: Environments are identified by unique names chosen
+by users. The specific mechanism (folder names, file names, database keys)
+is implementation-dependent and not specified at this conceptual level.
+
+**Future Considerations**: As the system matures, we may introduce formal
+environment registries or namespacing to prevent conflicts and improve
+management.
+
+### Provider Context Isolation
+
+**Current Limitation**: No built-in mechanism for isolating multiple
+environments within a single provider account beyond resource naming
+and network configuration.
+
+**Scope Decision**: Advanced isolation features (separate cloud accounts,
+VPC isolation, resource tagging) are currently out of scope but may be
+considered for future versions.
+
+### Security Considerations
+
+**Credential Management**: Provider contexts contain sensitive authentication
+information that must be handled securely:
+
+- Never commit credentials to version control
+- Use environment variables or secure credential stores
+- Implement proper access controls and audit logging
+- Support credential rotation and expiration
+
+**Environment Isolation**: While environments can share provider contexts,
+security-sensitive deployments should use dedicated provider contexts
+to minimize blast radius and improve access control.
+
+## Related Documentation
+
+- [Three-Phase Deployment Architecture](three-phase-deployment-architecture.md) -
+  How these concepts integrate into the deployment workflow
+- [Dependency Tracking and Incremental Builds](dependency-tracking-and-incremental-builds.md) -
+  How environment changes trigger rebuilds
+- [Firewall Dynamic Handling](firewall-dynamic-handling.md) - Provider-specific
+  security configuration
+
+## Revision History
+
+- **v1.0** - Initial concept definitions based on PoC development experience
diff --git a/project-words.txt b/project-words.txt
@@ -70,6 +70,7 @@ mktemp
 myip
 mysqladmin
 Namecheap
+namespacing
 netcat
 netdev
 netplan
