Skip to main content

ADR-001 - Separation of Public Services from Source Code Management (Heaven)

Context​

The current Heaven environment initially hosts multiple services on a single VPS:

  • Public-facing documentation websites (Docusaurus)
  • Reverse proxy (Nginx)
  • Source code management platform (Gitea)

This architecture introduces a co-location of public content and sensitive assets on the same system.

The risk identified is that a compromise of a public-facing service could provide an attacker with a foothold on the host, potentially impacting:

  • Source code repositories
  • CI/CD workflows
  • Stored secrets or deployment credentials

This situation was explicitly identified as a temporary and transitional design.

Decision​

Separate public-facing services and sensitive services by moving Gitea to a dedicated VPS instance.

The target architecture becomes:

  • VPS-01: Public services (websites, reverse proxy)
  • VPS-02 (or new instance): Gitea and associated services

Rationale​

This decision is driven by the following principles:

  • Segmentation over flat exposure
    Reduce lateral movement opportunities by isolating services with different exposure levels.

  • Least exposure / least trust
    Limit the blast radius of a compromise affecting public services.

  • Risk-driven architecture
    The decision directly addresses a risk scenario involving exploitation of exposed services.

  • Control effectiveness
    Improves the effectiveness of access control, monitoring, and incident containment.

Alternatives Considered​

1. Keep current architecture with stronger hardening​

  • Reinforce container isolation
  • Apply stricter access controls
  • Increase monitoring

Rejected
Does not sufficiently reduce the structural risk of co-location.

2. Logical isolation only (containers / namespaces)​

  • Separate services at runtime level

Rejected
Insufficient guarantee in case of host compromise.

3. Dedicated VPS separation (selected option)​

  • Physical / logical separation at infrastructure level

Accepted
Provides clear trust boundary and aligns with security architecture principles.

Security Impact​

Positive​

  • Reduced attack surface per system
  • Improved containment in case of compromise
  • Clearer trust boundaries
  • Better alignment with segmentation principles

Negative / Trade-offs​

  • Increased infrastructure cost
  • Additional operational complexity
  • Need for secure inter-service communication

Implementation Notes​

  • Deploy new VPS for Gitea
  • Restrict network access between VPS instances
  • Ensure secure administration paths (SSH, keys, MFA)
  • Review backup and logging strategy for the new instance
  • Update architecture documentation and trust boundary mapping

Evidence & Traceability​

This decision is linked to:

  • Risk scenario: exploitation of public-facing services
  • Risk register entry: R-001
  • Control categories:
    • Segmentation
    • Access control
    • Monitoring

This ADR supports auditability by documenting why the architecture evolved, not only how.

Current Maturity​

At the current stage, architectural decision documentation is considered early-stage but meaningful.

Established​

  • identification of structural risk (service co-location)
  • explicit documentation of architectural weakness
  • defined target state and justification

In Progress​

  • implementation of service separation
  • update of related architecture views and trust boundaries
  • linkage with control framework and validation mechanisms

Planned / Next Phase​

  • systematic use of ADRs for major architectural decisions
  • stronger linkage between ADRs, risks and controls
  • integration into audit and evidence workflows

This ADR reflects a transition from implicit decisions to documented and auditable architecture governance.