SilverSolutions/silverlinux-infra
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4cf06da0a88b717d884a091ebd10237875dc15cf
silverlinux-infra/docs/decisions.md
T

9.5 KiB
Raw Blame History

Architecture Decisions

Purpose

This document records important architectural and operational decisions made for SilverLinux.

The goal is to document not only what was implemented, but also why the decision was made.

2026-06-17

Ubuntu 24.04 LTS Selected

Decision:

Use Ubuntu Server 24.04 LTS as the operating system.

Reason:

  • Long-term support
  • Large community
  • Excellent Docker support
  • Familiar administration tools

Status:

Implemented

2026-06-17

Docker Standardization

Decision:

All services should run in Docker containers whenever possible.

Reason:

  • Consistent deployment
  • Easier backups
  • Easier migrations
  • Better isolation

Status:

Implemented

2026-06-17

Nginx Proxy Manager Selected

Decision:

Use Nginx Proxy Manager as the reverse proxy solution.

Reason:

  • Easy SSL management
  • Simple administration
  • User-friendly interface
  • Fast deployment

Status:

Implemented

2026-06-17

Gitea Selected

Decision:

Use Gitea for source control.

Reason:

  • Self-hosted
  • Lightweight
  • GitHub-like experience
  • Excellent Docker support

Status:

Implemented

2026-06-17

PostgreSQL Selected

Decision:

Use PostgreSQL as the central database platform.

Reason:

  • Reliability
  • Mature ecosystem
  • Supports multiple applications
  • Strong backup tooling

Status:

Implemented

2026-06-17

OpenProject Selected

Decision:

Use OpenProject for project management.

Reason:

  • Mature platform
  • Open source
  • Strong planning features
  • Work package management
  • Time tracking

Status:

Implemented

2026-06-21

Plane.so Removed

Decision:

Do not deploy Plane.so.

Reason:

  • OpenProject fully satisfies requirements
  • Reduces maintenance burden
  • Avoids duplicate functionality

Status:

Implemented

2026-06-21

Centralized Secrets Management

Decision:

Store shared credentials in a single secrets file.

Location:

/srv/secrets/company.env

Reason:

  • Avoid secrets in Docker Compose files
  • Easier credential rotation
  • Easier disaster recovery
  • Reduced risk of accidental exposure

Status:

Implemented

2026-06-21

OpenID Disabled in Gitea

Decision:

Disable OpenID authentication.

Reason:

  • Not required
  • Reduces attack surface
  • Simplifies authentication model

Status:

Implemented

2026-06-21

Gmail SMTP Selected

Decision:

Use Gmail SMTP for outbound email.

Sender:

noreply@silveressence.net

Reason:

  • Reliable delivery
  • Easy setup
  • Supports application notifications

Status:

Implemented

2026-06-21 - Adopt Gitea Actions + Self-Hosted Runner for Package Publishing

Decision:

  • Replace GitHub Actions with self-hosted Gitea Actions.
  • Execute package publishing on SilverLinux using the global silverlinux-runner.
  • Publish internal NuGet packages to BaGet.
  • Store the runner registration token in /srv/secrets/company.env and publishing credentials in Gitea Actions Secrets.
  • Use [Package] in commit messages to request commit-driven package publishing.

Reason:

  • Keep source control, build execution and package hosting inside SilverLinux.
  • Avoid storing credentials in repositories.
  • Provide a simple, explicit package-release convention.

Status:

Accepted

2026-06-21 - BaGet Secret Storage

Decision:

The BaGet API key is currently stored directly in the BaGet Docker Compose configuration.

Reason:

  • Simplicity during initial deployment.

Future Plan:

Move the API key into the centralized SilverLinux secrets management system located at:

/srv/secrets/company.env

when additional services begin consuming the same secret management approach.

2026-06-22 - Deploy Microsoft SQL Server Express Alongside PostgreSQL

Decision:

  • Run Microsoft SQL Server 2022 Express alongside PostgreSQL.
  • Attach MSSQL only to the internal Docker network.
  • Do not publish port 1433 or route MSSQL through the reverse proxy.
  • Store MSSQL_SA_PASSWORD in /srv/secrets/company.env.

Reason:

  • Support Silver projects that require Microsoft SQL Server compatibility.
  • Allow both database platforms to coexist without exposing database ports.

Status:

Implemented

2026-06-22 - Select DbGate for Database Administration

Decision:

  • Use DbGate to administer Microsoft SQL Server and PostgreSQL.
  • Connect DbGate to both the internal and proxy Docker networks.
  • Publish only the DbGate web interface through Nginx Proxy Manager.
  • Require DbGate authentication and HTTPS.

Reason:

  • Provides one lightweight, modern browser interface for both database platforms.
  • Keeps PostgreSQL and MSSQL private.

Follow-up:

Move the DbGate password from the server-side Compose configuration to /srv/secrets/company.env.

Status:

Implemented

2026-06-24 - Formalize Multi-Network Segmentation

Decision:

  • Treat SilverLinux as a three-layer Docker network architecture.
  • Use internal for private databases and backend service traffic.
  • Use proxy for public HTTP and HTTPS services routed through Nginx Proxy Manager.
  • Use isolated stack networks for Jitsi, Xray and CI/CD runner traffic where the active runtime attachments support it.

Reason:

  • Keep databases private while allowing selected web interfaces to be public.
  • Reduce unnecessary cross-service connectivity.
  • Make specialized infrastructure stacks easier to reason about and audit.

Status:

Accepted

2026-06-24 - Confirm Nginx Proxy Manager as the Single Reverse Proxy

Decision:

Use Nginx Proxy Manager as the sole reverse proxy and SSL termination layer for SilverLinux HTTP and HTTPS services.

Reason:

  • The active platform uses Nginx Proxy Manager for domain routing.
  • No Traefik or alternate reverse proxy is active.
  • A single proxy layer keeps exposure and certificate management centralized.

Status:

Confirmed

2026-06-24 - Add Xray Connectivity Layer

Decision:

  • Classify Xray as a network tunneling and connectivity layer.
  • Attach Xray to the proxy network for public endpoint access.
  • Keep xray_default documented as the Compose-created Xray stack network.
  • Monitor the service as an exposed connectivity endpoint rather than as an application backend.

Reason:

  • Improve connectivity stability to SilverLinux.
  • Support secure long-distance connection paths.
  • Keep tunneling concerns separate from application and database services.

Status:

Accepted

Runtime Note:

The 2026-06-24 Docker snapshot showed the running xray container attached to proxy only. The xray_default network existed but had no running containers attached.

2026-06-24 - Confirm Jitsi Meet Is Fully Deployed

Decision:

Treat the Jitsi Meet stack as an operational isolated collaboration stack.

Components:

  • jitsi-web
  • jitsi-jvb
  • jitsi-jicofo
  • jitsi-prosody

Networks:

  • proxy
  • jitsi-docker-jitsi-meet-aa76415_meet.jitsi

Reason:

  • Jitsi Web is expected to be public.
  • Internal Jitsi components should remain isolated inside the Jitsi stack network.

Status:

Confirmed

2026-06-24 - Adopt Phased Infrastructure Roadmap

Decision:

Use a phased roadmap for planned SilverLinux platform improvements.

Phases:

  • Phase 1: Grafana, Prometheus, Loki, Redis and Authelia.
  • Phase 2: CrowdSec, Sentry, Restic, Fail2Ban upgrade and Cloudflare rate limiting/WAF.
  • Phase 3: SonarQube, Harbor, Backstage and Nextcloud.

Reason:

  • Prioritize observability, access control and shared runtime foundations first.
  • Add security and backup maturity before larger platform expansion.
  • Keep enterprise developer-platform tools grouped together.

Status:

Accepted

2026-06-25 - Select Prometheus And Grafana Monitoring Stack

Decision:

Deploy a dedicated monitoring Docker stack using:

  • Prometheus for metrics collection
  • Grafana for visualization
  • Node Exporter for host metrics
  • cAdvisor for Docker metrics

Reason:

  • Prometheus provides a standard pull-based metrics system.
  • Grafana provides flexible dashboards and datasource integration.
  • Node Exporter provides host CPU, memory and disk visibility.
  • cAdvisor provides Docker container visibility.

Status:

Implemented

Validation:

  • Prometheus UI validated
  • Prometheus targets validated
  • Grafana datasource connected to Prometheus
  • Initial monitoring dashboards created and validated

2026-06-25 - Export Backup Metrics Through Node Exporter

Decision:

Export SilverLinux backup metrics through the Node Exporter Textfile Collector.

Metrics:

  • Backup success
  • Backup duration
  • Backup size

Reason:

  • Keep backup status visible in the same monitoring stack as host and container metrics.
  • Avoid a separate metrics service for backup scripts.
  • Allow Grafana dashboards to show backup health.

Status:

Implemented

2026-06-25 - Validate Backup v2 And Restore Workflow

Decision:

Treat Backup v2 as the operational SilverLinux backup system.

Implemented:

  • HTML backup reports
  • Email notifications
  • Automatic archive creation
  • Backup logging
  • Restore validation
  • MSSQL data inclusion fix
  • Backup metrics
  • Automatic low disk space cleanup
  • Daily cron execution

Validation:

  • Dry-run restore completed
  • Full archive validation completed
  • PostgreSQL restore coverage verified
  • MSSQL backup integrity verified
  • Gitea backup verified
  • BaGet backup verified
  • OpenProject assets verified
  • Docker configuration verified

Status:

Implemented

Future Decisions

Document future decisions using the following template:

Date:

Decision:

Reason:

Alternatives Considered:

Status:

Reference in New Issue View Git Blame Copy Permalink