silverlinux-infra/docs/decisions.md

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

---

Future Decisions

Document future decisions using the following template:

Date:

Decision:

Reason:

Alternatives Considered:

Status: