# Lamassu Server: Future Nginx Implementation

This document describes how to implement nginx reverse proxy support for the lamassu-server module in the future.

## Current Limitation

The lamassu-admin-server has **hardcoded ports** in upstream:
- Production mode (default): port 443
- Dev mode (`--dev` flag): port 8070

This means nginx cannot be used as a reverse proxy on port 443 because the admin UI would already be bound to it.

## Required Upstream Changes

### 1. Add `--ui-port` flag to admin-server.js

Modify `packages/server/lib/new-admin/admin-server.js`:

```javascript
// Change from:
const devMode = require('minimist')(process.argv.slice(2)).dev

// To:
const argv = require('minimist')(process.argv.slice(2))
const devMode = argv.dev
const UI_PORT = argv['ui-port'] || process.env.UI_PORT

// And in run():
async function run() {
  const app = await loadRoutes()
  const defaultPort = devMode ? 8070 : 443
  const serverPort = UI_PORT ? parseInt(UI_PORT, 10) : defaultPort
  // ...
}
```

This allows configuring the admin UI port via:
- `--ui-port 8443` command line flag
- `UI_PORT=8443` environment variable

### 2. Update nix-bitcoin module

Once upstream supports `--ui-port`, update `modules/lamassu-lnbits.nix`:

#### Re-enable options

```nix
# Uncomment and update:
adminPort = mkOption {
  type = types.port;
  default = 8443;  # Internal port when nginx is used
  description = "Port for the lamassu admin UI (internal, behind nginx).";
};

nginx = {
  enable = mkEnableOption "Nginx reverse proxy on port 443";
  hostname = mkOption {
    type = types.nullOr types.str;
    default = null;
    description = "Hostname for nginx virtual host";
  };
};
```

#### Add nginx configuration

```nix
services.nginx = mkIf cfg.nginx.enable {
  enable = true;
  recommendedTlsSettings = true;
  recommendedProxySettings = true;

  virtualHosts.${cfg.nginx.hostname or cfg.hostname} = {
    forceSSL = true;
    sslCertificate = cfg.certPath;
    sslCertificateKey = cfg.keyPath;

    # Route API endpoints to main server
    locations."/ca".proxyPass = "https://127.0.0.1:${toString cfg.serverPort}";
    locations."/pair".proxyPass = "https://127.0.0.1:${toString cfg.serverPort}";

    # Route everything else to admin UI
    locations."/".proxyPass = "https://127.0.0.1:${toString cfg.adminPort}";
  };
};
```

#### Update admin server service

```nix
ExecStart = "${lamassuAdminEnv} ... lamassu-admin-server --ui-port ${toString cfg.adminPort} ...";

# Only need CAP_NET_BIND_SERVICE if adminPort < 1024 and nginx is disabled
AmbientCapabilities = optionals (cfg.adminPort < 1024 && !cfg.nginx.enable) [ "CAP_NET_BIND_SERVICE" ];
```

#### Update firewall

```nix
networking.firewall.allowedTCPPorts =
  [ cfg.serverPort ] ++
  (optional cfg.nginx.enable 443) ++
  (optional (!cfg.nginx.enable && cfg.adminPort < 1024) cfg.adminPort);
```

## Architecture

### Current (no nginx support)

```
                    ┌─────────────────────────────┐
    :3000 ─────────►│  lamassu-server (API)       │
                    └─────────────────────────────┘
                    ┌─────────────────────────────┐
    :443 ──────────►│  lamassu-admin-server (UI)  │
                    └─────────────────────────────┘
```

### Future (with nginx)

```
                    ┌─────────────────────────────┐
    :3000 ─────────►│  lamassu-server (API)       │
                    └─────────────────────────────┘

                    ┌─────────────────────────────┐
    :443 ──────────►│  nginx                      │
                    │  ├─ /ca, /pair ──► :3000    │
                    │  └─ / ──────────► :8443     │
                    └─────────────────────────────┘
                                 │
                                 ▼
                    ┌─────────────────────────────┐
    :8443 ◄────────│  lamassu-admin-server (UI)  │
                    └─────────────────────────────┘
```

## Benefits of Nginx

1. **Single port (443)** for all HTTPS traffic
2. **Better TLS handling** with nginx's recommended settings
3. **Consistent with other nix-bitcoin services** (BTCPayServer, mempool, etc.)
4. **Future extensibility** for rate limiting, caching, etc.

## Port Conflict Note

If both nginx and lamassu-admin-server try to bind to port 443, systemd will fail to start the services. The assertion below should be added to prevent this:

```nix
assertions = [
  {
    assertion = !(cfg.nginx.enable && cfg.adminPort == 443);
    message = "Cannot use nginx with adminPort 443. Set a different adminPort (e.g., 8443).";
  }
];
```