### Start MailFathom services

Source: https://github.com/krzysztof318/mailfathom/blob/main/docs/operations/deployment-compose.md

Commands to initialize the database and start the application container.

```bash
docker compose up -d postgres                              # creates the role, the database, and the vector extension
# apply the schema — see below
docker compose up -d                                       # starts MailFathom
```

--------------------------------

### GET /started

Source: https://github.com/krzysztof318/mailfathom/blob/main/docs/operations/health-endpoints.md

Checks if the application has finished the startup process.

```APIDOC
## GET /started

### Description
Checks if the application has finished coming up.

### Method
GET

### Endpoint
/started
```

--------------------------------

### Install MailFathom via Helm

Source: https://github.com/krzysztof318/mailfathom/blob/main/docs/operations/deployment-kubernetes.md

Commands to install the chart from the OCI registry and verify the deployment status.

```bash
helm install mailfathom oci://ghcr.io/krzysztof318/charts/mailfathom \
  --version <x.y.z> --namespace mailfathom --values values.yaml
kubectl --namespace mailfathom rollout status deployment/mailfathom
```

--------------------------------

### Install via Windows Package Manager

Source: https://github.com/krzysztof318/mailfathom/blob/main/docs/operations/admin-endpoint.md

Install the portable mfctl binary using winget. This adds the tool to the system PATH and enables future upgrades via winget.

```console
> winget install MailFathom.mfctl
```

--------------------------------

### Install from Local Directory

Source: https://github.com/krzysztof318/mailfathom/blob/main/docs/operations/deployment-kubernetes.md

Deploys the chart directly from a local source checkout for development purposes.

```bash
helm install mailfathom deploy/helm/mailfathom --namespace mailfathom --values values.yaml
```

--------------------------------

### Startup Log for Request Timeout

Source: https://github.com/krzysztof318/mailfathom/blob/main/docs/operations/mcp-endpoint.md

Example of the informational log message displayed at startup when a request timeout policy is active.

```text
info: MailFathom.Host.Hosting.Warnings.TransportRequestTimeoutStartupReport
      The MCP endpoint on /mcp abandons a request that has run for 00:10:00, answering 504 and releasing the
      concurrency permit it held.
```

--------------------------------

### Example of a certificate validity startup log

Source: https://github.com/krzysztof318/mailfathom/blob/main/docs/operations/mcp-endpoint.md

This log entry confirms the certificate details for an HTTPS profile during startup.

```text
info: MailFathom.Host.Security.Transport.TransportServerCertificateStore
      The MCP HTTPS profile public presents a server certificate valid until 2027-01-31 00:00:00Z.
```

--------------------------------

### Enable Multiple Profiles

Source: https://github.com/krzysztof318/mailfathom/blob/main/docs/operations/deployment-compose.md

Example of combining multiple Compose profiles for simultaneous service activation.

```dotenv
COMPOSE_PROFILES=personal-data-scanning,spam-scanning
```

--------------------------------

### View Rate Limiting Startup Report

Source: https://github.com/krzysztof318/mailfathom/blob/main/docs/operations/mcp-endpoint.md

Example of the log output generated at startup detailing the active rate limiting configuration for the MCP endpoint.

```text
info: MailFathom.Host.Hosting.Warnings.TransportRateLimitingStartupReport
      The MCP endpoint on /mcp serves at most 20 requests at once across every caller, queueing 0 beyond that, and
      allows each caller a burst of 60 requests restored at 60 every 00:01:00, queueing 0 of its requests beyond that.
```

--------------------------------

### Example of a certificate validation failure message

Source: https://github.com/krzysztof318/mailfathom/blob/main/docs/operations/mcp-endpoint.md

This message appears when a configured HTTPS profile fails validation during the startup process.

```text
McpEndpoint:Https:Endpoints:0 — the HTTPS profile 'public' has no usable server certificate
[DomainNotCoveredBySubjectAlternativeName].
```

--------------------------------

### Client Assertion JWT Structure

Source: https://github.com/krzysztof318/mailfathom/blob/main/docs/operations/mcp-endpoint.md

Example of the header and claims required for a client assertion JWT.

```json
{ "alg": "ES256", "typ": "mailfathom-client-assertion+jwt" }
{ "aud": "urn:mailfathom:mcp", "exp": 1786060860, "jti": "hLdI6NHKQ4qXCXhPrsRJfA" }
```

--------------------------------

### Clear-text Redirect Response

Source: https://github.com/krzysztof318/mailfathom/blob/main/docs/operations/mcp-endpoint.md

Example of a 308 Permanent Redirect response returned by the clear-text listener.

```console
$ curl -i http://mail.example.com:8080/mcp
HTTP/1.1 308 Permanent Redirect
Location: https://mail.example.com:8443/mcp
```

--------------------------------

### Configure McpEndpoint with Client Certificate Profiles

Source: https://github.com/krzysztof318/mailfathom/blob/main/docs/operations/mcp-endpoint.md

Example configuration for enabling the MCP endpoint with API key authentication and a client certificate profile for a connector.

```json
{
  "McpEndpoint": {
    "Enabled": true,
    "Authentication": [
      { "ApiKey": { "Name": "workstation", "SecretReference": "systemd-credential:mailfathom-mcp-workstation-key" } }
    ],
    "ClientCertificateProfiles": [
      {
        "Name": "chatgpt-connector",
        "Requirement": "Optional",
        "TrustAnchors": [
          {
            "Name": "openai-connectors-ca",
            "SecretReference": "file:/etc/mailfathom/openai-connectors-ca.pem"
          }
        ],
        "SubjectAlternativeNames": ["mtls.prod.connectors.openai.com"]
      }
    ]
  }
}
```

--------------------------------

### Configure Allowed Origins in JSON

Source: https://github.com/krzysztof318/mailfathom/blob/main/docs/operations/mcp-endpoint.md

Example of defining specific allowed origins in the MCP endpoint configuration.

```json
{
  "McpEndpoint": {
    "Cors": {
      "AllowedOrigins": [
        "https://client.example.test",
        "https://console.example.test:8443"
      ]
    }
  }
}
```

--------------------------------

### Enable MCP Endpoint with API Key Authentication

Source: https://github.com/krzysztof318/mailfathom/blob/main/docs/operations/mcp-endpoint.md

Example configuration to enable the MCP endpoint and define an API key for authentication using a systemd credential reference.

```json
{
  "McpEndpoint": {
    "Enabled": true,
    "Authentication": [
      {
        "ApiKey": {
          "Name": "workstation",
          "SecretReference": "systemd-credential:mailfathom-mcp-workstation-key"
        }
      }
    ]
  }
}
```

--------------------------------

### MCP Endpoint Public Key Configuration

Source: https://github.com/krzysztof318/mailfathom/blob/main/docs/operations/mcp-endpoint.md

Example configuration for enabling MCP endpoint authentication using a public key pair, where the deployment only stores the public half.

```json
{
  "McpEndpoint": {
    "Enabled": true,
    "Authentication": [
      {
        "PublicKey": {
          "Name": "reporting-job",
          "SecretReference": "file:/etc/mailfathom/reporting-job.pub",
          "Lifetime": "2027-01-31T00:00:00Z"
        }
      }
    ]
  }
}
```

--------------------------------

### Nginx MCP Location Configuration

Source: https://github.com/krzysztof318/mailfathom/blob/main/docs/operations/mcp-endpoint.md

Example Nginx configuration for proxying to the MCP endpoint, ensuring headers are correctly forwarded and buffering is disabled for streaming.

```nginx
location /mcp {
    proxy_pass         http://10.4.2.11:8080;
    proxy_http_version 1.1;
    proxy_set_header   Host              $host;
    proxy_set_header   X-Forwarded-Proto $scheme;
    proxy_set_header   X-Forwarded-Host  $host;
    proxy_buffering    off;
}
```

--------------------------------

### MCP Endpoint API Key Configuration

Source: https://github.com/krzysztof318/mailfathom/blob/main/docs/operations/mcp-endpoint.md

Example configuration for enabling MCP endpoint authentication using multiple API keys with defined lifetimes and secret references.

```json
{
  "McpEndpoint": {
    "Enabled": true,
    "Authentication": [
      {
        "ApiKey": {
          "Name": "workstation",
          "SecretReference": "systemd-credential:mailfathom-mcp-workstation-key",
          "Lifetime": "NoLimit"
        }
      },
      {
        "ApiKey": {
          "Name": "chatgpt-connector",
          "SecretReference": "file:/run/secrets/mailfathom-mcp-chatgpt-key",
          "Lifetime": "2027-01-31T00:00:00Z"
        }
      }
    ]
  }
}
```

--------------------------------

### Initialize configuration directories

Source: https://github.com/krzysztof318/mailfathom/blob/main/docs/operations/deployment-quadlet.md

Create the necessary directory structure for Quadlet units, configuration, and encrypted credentials.

```bash
mkdir -p ~/.config/containers/systemd
mkdir -p ~/.config/mailfathom/config ~/.config/mailfathom/postgres-init
mkdir -p ~/.config/credstore.encrypted
chmod 700 ~/.config/credstore.encrypted
```

--------------------------------

### Configure HttpAndHttps Transport

Source: https://github.com/krzysztof318/mailfathom/blob/main/docs/operations/health-endpoints.md

Example configuration for a dual-mode transport setup requiring both a standard port and an HTTPS port.

```json
{
  "HealthEndpoints": {
    "Port": 8081,
    "HttpsPort": 8443,
    "Transport": "HttpAndHttps",
    "Domain": "probe.example.test",
    "ServerCertificate": {
      "CertificateChain": {
        "Name": "probe-chain",
        "SecretReference": "file:/etc/mailfathom/tls/probe-fullchain.pem"
      },
      "PrivateKey": {
        "Name": "probe-key",
        "SecretReference": "file:/etc/mailfathom/tls/probe-privkey.pem"
      }
    }
  }
}
```

--------------------------------

### Build and serve the documentation site locally

Source: https://github.com/krzysztof318/mailfathom/blob/main/docs/operations/documentation-site.md

Use these commands to build the documentation artifacts and serve them on a local web server.

```bash
scripts/build-docs-site.sh                 # artifacts/docs-site
dotnet docfx serve artifacts/docs-site     # http://localhost:8080
```

--------------------------------

### Deploy unit files and configuration

Source: https://github.com/krzysztof318/mailfathom/blob/main/docs/operations/deployment-quadlet.md

Copy the Quadlet unit files, configuration templates, and database initialization scripts to the appropriate configuration directories.

```bash
cp deploy/quadlet/mailfathom.container deploy/quadlet/mailfathom-postgres.container \
   deploy/quadlet/*.network deploy/quadlet/*.volume ~/.config/containers/systemd/
cp deploy/quadlet/config/10-mailfathom.json.example ~/.config/mailfathom/config/10-mailfathom.json
cp deploy/compose/postgres/10-create-mailfathom-database.sh ~/.config/mailfathom/postgres-init/
```

--------------------------------

### Start MailFathom Services

Source: https://github.com/krzysztof318/mailfathom/blob/main/docs/operations/deployment-quadlet.md

Commands to enable lingering, reload systemd units, and start the database and application services.

```bash
loginctl enable-linger "$USER"
systemctl --user daemon-reload                       # regenerates the units from the Quadlet sources
systemctl --user start mailfathom-postgres.service   # creates the role, the database, and the vector extension
# apply the schema — see below
systemctl --user start mailfathom.service
```

--------------------------------

### Deploy Legacy OpenSSL Configuration

Source: https://github.com/krzysztof318/mailfathom/blob/main/docs/operations/platform-tls-policy.md

Copy the provided example configuration file to the system directory to enable legacy TLS support.

```bash
cp deploy/openssl/legacy-mail-server.cnf.example /etc/mailfathom/openssl-legacy.cnf
```