Merge pull request #111 from christianlouis/codex/onepassword-secret-injection-docs

docs: add 1password secret injection guide

docs/deployment/configuration.md

@@ -10,6 +10,8 @@ DMARQ can be configured through:
 2. A `.env` file
 3. The web-based configuration wizard (on first run)
 
+For production secrets, use the [1Password secret handling guide](secrets.md) so sensitive values are injected into the DMARQ process without being committed or copied into deployment notes.
+
 ## Core Settings
 
 ### Database Configuration
@@ -164,9 +166,12 @@ DMARQ uses the following order of precedence for configuration:
 
 For sensitive information like passwords and API tokens, we recommend:
 
-1. Use environment variables instead of committing them to files
-2. For Docker, use Docker secrets or environment files that are not stored in version control
-3. For production systems, consider using a secrets manager like HashiCorp Vault or AWS Secrets Manager
+1. Use 1Password Environments or another deployment secrets manager instead of committing secrets to files
+2. Inject secrets as environment variables or a locally mounted env file that is not stored in version control
+3. Keep separate secret bundles for development, preprod, and production
+4. Rotate credentials from the secret manager first, then restart DMARQ so it receives the new values
+
+See [Secret Handling with 1Password](secrets.md) for the recommended production workflow.
 
 ## Runtime Configuration Changes
 

docs/deployment/docker.md

@@ -24,7 +24,7 @@ The fastest way to get DMARQ running is to use Docker Compose:
 
 2. **Configure environment variables**
 
-   Create a `.env` file in the project root:
+   Create a `.env` file in the project root. For production, prefer a 1Password-mounted `.env` file; see [Secret Handling with 1Password](secrets.md).
 
    ```
    # Database Configuration
@@ -130,6 +130,8 @@ volumes:
 
 All configuration in the Docker setup is done via environment variables, either directly in the `docker-compose.yml` file or through a separate `.env` file. See the [Configuration](configuration.md) page for detailed information about all available variables.
 
+For production, store secret values in 1Password Environments and inject them into Compose with a mounted `.env` file or your deployment runner's secret-injection feature. Do not commit `.env` files that contain `SECRET_KEY`, database credentials, IMAP passwords, OAuth secrets, or API tokens.
+
 ### Volumes
 
 The Docker Compose setup uses these volumes:
@@ -292,4 +294,4 @@ If you encounter volume mounting problems:
 
 1. Check file permissions on the host
 2. Use absolute paths in your volume mappings
-3. On Windows, ensure you've enabled Docker file sharing for the relevant drives
+3. On Windows, ensure you've enabled Docker file sharing for the relevant drives

docs/deployment/manual.md

@@ -39,7 +39,7 @@ pip install -r requirements.txt
 
 ### 3. Configure Environment Variables
 
-Create a `.env` file in the backend directory with your configuration:
+Create a `.env` file in the backend directory with your configuration. For production, prefer a 1Password-mounted `.env` file; see [Secret Handling with 1Password](secrets.md).
 
 ```
 # Database Configuration
@@ -330,4 +330,4 @@ sqlite3 /path/to/data/dmarq.db .dump > dmarq_backup_$(date +%Y%m%d).sql
 
 # Restore from a backup
 cat dmarq_backup_file.sql | sqlite3 /path/to/data/dmarq.db
-```
+```

docs/deployment/secrets.md

@@ -0,0 +1,94 @@
+# Secret Handling with 1Password
+
+This guide describes the recommended production flow for injecting DMARQ secrets without copying raw values into source-controlled files, shell history, chat logs, or deployment notes.
+
+Use 1Password Environments as the source of truth for sensitive environment variables. DMARQ reads standard environment variables at startup, so the deployment process only needs to make those variables available to the authorized process.
+
+## Recommended Variables
+
+Store these values in a 1Password Environment for each deployment target:
+
+| Variable | Sensitivity | Notes |
+|----------|-------------|-------|
+| `SECRET_KEY` | Secret | Required for stable sessions. Use a strong random value. |
+| `ADMIN_API_KEY` | Secret | Optional fixed admin API key. Use only when needed for automation. |
+| `DATABASE_URL` | Secret when it contains credentials | Prefer this single URL for production PostgreSQL deployments. |
+| `IMAP_PASSWORD` | Secret | Required when IMAP polling is enabled. |
+| `LOGTO_APP_SECRET` | Secret | Required when Logto authentication is enabled. |
+| `CLOUDFLARE_API_TOKEN` | Secret | Optional DNS inspection/integration token. |
+| `FIRST_SUPERUSER_PASSWORD` | Secret | Only needed for bootstrap flows that create an initial local admin. |
+
+Non-sensitive values, such as `IMAP_SERVER`, `IMAP_USERNAME`, `LOGTO_ENDPOINT`, `LOGTO_APP_ID`, and `BACKEND_CORS_ORIGINS`, may also live in the Environment so each deployment has one complete configuration bundle.
+
+## Create the Environment
+
+1. Open 1Password and enable the local MCP server or Environments feature if it is not already enabled.
+2. Create a 1Password Environment named for the target, for example `DMARQ Preprod` or `DMARQ Production`.
+3. Add the variables listed above. Mark secrets as concealed.
+4. Grant access only to the operators and deployment systems that need that target.
+
+## Local Development
+
+For local runs, mount the 1Password Environment as a local `.env` file:
+
+```bash
+# Example mount path for a local checkout
+/path/to/dmarq/.env
+```
+
+Then start DMARQ normally:
+
+```bash
+docker compose up -d
+```
+
+or, for a manual backend run:
+
+```bash
+cd backend
+uvicorn app.main:app --host 127.0.0.1 --port 8000
+```
+
+The mounted `.env` file is managed by 1Password. Do not copy its contents into commits, issues, pull requests, or chat messages.
+
+## Docker Compose Production Pattern
+
+For Docker Compose hosts, mount the Environment as the project `.env` file and keep `docker-compose.yml` using variable references:
+
+```bash
+docker compose pull
+docker compose up -d
+```
+
+This lets Compose read the mounted `.env` file while 1Password remains the system that stores and syncs the actual secret values.
+
+If your deployment runner supports command-level injection instead of local file mounts, run Compose inside that authorized injection context and avoid writing a `.env` file to disk.
+
+## Systemd Production Pattern
+
+For manual Linux deployments, prefer a 1Password-mounted env file referenced by the service:
+
+```ini
+[Service]
+EnvironmentFile=/opt/dmarq/.env
+WorkingDirectory=/opt/dmarq/backend
+ExecStart=/opt/dmarq/venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8000
+```
+
+Restrict the service user and file permissions so only the DMARQ process and the operator account can read the mounted file.
+
+## Rotation Checklist
+
+1. Update the variable in the relevant 1Password Environment.
+2. Restart the DMARQ process or container so it receives the new value.
+3. Verify health checks and login/API behavior.
+4. Revoke the old credential at the upstream provider when applicable.
+5. Record that rotation happened, but do not record the secret value.
+
+## Safety Rules
+
+- Never commit `.env` files or secret values.
+- Never paste mailbox passwords, OAuth secrets, API tokens, database passwords, or generated session keys into issues, pull requests, logs, or chat.
+- Keep `AUTH_DISABLED=true` limited to local development or a deployment protected by a separate authentication proxy.
+- Keep `LOGTO_SKIP_SSL_VERIFY=false` in production.
+- Use separate 1Password Environments for development, preprod, and production.

docs/development/roadmap.md

@@ -69,12 +69,14 @@ Quality bar:
 Objective: make self-hosted deployments safer.
 
 Priority tasks:
-- Document a 1Password secret-injection deployment flow.
 - Keep raw secrets out of diagnostics, logs, and UI responses.
 - Add startup validation for production settings.
 - Add backup and restore documentation.
 - Add a release checklist covering migrations, tests, and smoke checks.
 
+Delivered:
+- Documented a 1Password secret-injection deployment flow for local, Docker Compose, and systemd deployments.
+
 ## Later Milestones
 
 - Notifications and alert rules with Apprise.

docs/index.md

@@ -21,4 +21,4 @@ DMARQ is a full-stack DMARC monitoring platform designed to help organizations t
 
 To get started with DMARQ, please see the [Getting Started](user_guide/getting_started.md) guide.
 
-For installation instructions, check the [Docker Setup](deployment/docker.md) or [Manual Installation](deployment/manual.md) guides.
+For installation instructions, check the [Docker Setup](deployment/docker.md) or [Manual Installation](deployment/manual.md) guides. For production secrets, use [Secret Handling with 1Password](deployment/secrets.md).

docs/milestones.md

@@ -90,12 +90,14 @@ Exit criteria:
 
 ## Milestone 6: Production Secret Handling and Deployment Hardening
 
-Status: Planned
+Status: In progress
 
 Goal: make production deployments safer and easier to operate.
 
+Delivered:
+- 1Password-based secret injection flow for local, Docker Compose, and systemd deployments.
+
 Planned:
-- Document a 1Password-based secret injection flow for local and containerized deployments.
 - Avoid exposing raw mailbox/OAuth secrets in logs, UI responses, and diagnostics.
 - Add startup checks for production-critical configuration.
 - Add backup/restore guidance for database deployments.

docs/todo.md

@@ -155,7 +155,7 @@ This file tracks the specific implementation tasks for each milestone of the DMA
 - [x] Add actionable recommendations for common DMARC failure patterns
 
 ## Future Milestones
-- [ ] Production secret handling guide using 1Password injection
+- [x] Production secret handling guide using 1Password injection
 - [ ] Apprise notifications and alert rules
 - [ ] DNS health guidance and Cloudflare read-only inspection
 - [ ] Guided setup and operator health pages