# Linux and PostgreSQL server deployment

This procedure installs the same UIC Connect TMS application on an Ubuntu server with PostgreSQL. Windows installations remain supported with SQL Server. Database selection is configuration-driven; application code and service contracts are shared.

## Provider selection

`TMS.DataService` and `TMS.Setup` read `DatabaseProvider` from the runtime configuration.

| Deployment | `DatabaseProvider` | Connection string |
| --- | --- | --- |
| Windows / SQL Server | `SqlServer` | Standard Microsoft SQL Server connection string |
| Linux / PostgreSQL | `PostgreSql` | Standard Npgsql connection string |

If `DatabaseProvider` is omitted, the application uses `SqlServer` for backward compatibility. Accepted PostgreSQL aliases are `Postgres` and `Npgsql`, although new configurations should use `PostgreSql`. A deployment must retain its chosen engine; switching the value does not migrate data between databases.

## Package and prerequisites

The Linux package contains self-contained `linux-x64` builds of DataService, Portal, MQTT and Setup plus `packaging/linux/install.sh`. The target requires Ubuntu, PostgreSQL, `openssl`, `python3`, `sudo`, `systemd` and UFW. The installer does not require a machine-wide .NET runtime.

Copy the archive and installer to the server, then run as root:

```bash
chmod 0755 /tmp/install-uic-connect-tms.sh
PUBLIC_HOST=tms.example.com sudo -E /tmp/install-uic-connect-tms.sh /tmp/uic-connect-tms-linux-x64.tar.gz
```

`PUBLIC_HOST` may be a DNS name or IPv4 address. The first installation creates a self-signed HTTPS/MQTT certificate. Replace it with an approved certificate before production use.

## Installed resources

| Resource | Location or port |
| --- | --- |
| Versioned releases | `/opt/uic-connect-tms/releases` |
| Active release | `/opt/uic-connect-tms/current` |
| Runtime configuration and certificates | `/etc/uic-connect-tms` |
| Application artifacts | `/var/lib/uic-connect-tms/artifacts` |
| PostgreSQL database / role | `uic_connect_tms` / `uic_tms` |
| Portal HTTPS | TCP 5102 |
| MQTT mutual TLS | TCP 5883 |
| Portal HTTP and DataService gRPC | loopback TCP 15100 / 15101 |

The installer creates the unprivileged `uictms` service account, applies database migrations, enables the services and opens only the two public application ports in UFW. PostgreSQL should remain bound to loopback or a private administration network.

```bash
systemctl status uic-tms-data uic-tms-portal uic-tms-mqtt
journalctl -u uic-tms-data -u uic-tms-portal -u uic-tms-mqtt
```

The initial administrator is created only when the database has no users. Its one-time generated credentials are stored in `/etc/uic-connect-tms/initial-admin.json`, readable by root and the service group. Change the password after first sign-in. Re-running the installer preserves the database, generated secrets, certificates and existing administrator.

## Backups and recovery

Back up PostgreSQL and the artifact directory as one recovery set. A database-only restore can leave released application records without their package files.

```bash
sudo -u postgres pg_dump --format=custom --file=/secure-backup/uic_connect_tms.dump uic_connect_tms
sudo tar -C /var/lib/uic-connect-tms -czf /secure-backup/uic-connect-tms-artifacts.tar.gz artifacts
```

Test restore procedures on an isolated host. Preserve `/etc/uic-connect-tms` separately because it contains certificates and deployment secrets; never place that directory in source control or a public delivery archive.

## SQL Server compatibility

The Windows setup continues to write a SQL Server connection string and relies on the default `SqlServer` provider. SQL Server migrations remain embedded alongside the PostgreSQL baseline. Every persistence change must update and test both provider paths. Provider-specific exception handling must map equivalent constraint errors to the same gRPC result.