# 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:

```text
/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:

```text
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:

```text
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:

```text
/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:

```text
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:

```text
Implemented
```

---

## Future Decisions

Document future decisions using the following template:

Date:

Decision:

Reason:

Alternatives Considered:

Status: