From 77de03d8b59a222201dcea7686d94087129842a0 Mon Sep 17 00:00:00 2001 From: Christian Krakau-Louis Date: Fri, 22 May 2026 21:51:47 +0200 Subject: [PATCH] docs: add 1password secret injection guide --- docs/deployment/configuration.md | 11 +++- docs/deployment/docker.md | 6 +- docs/deployment/manual.md | 4 +- docs/deployment/secrets.md | 94 ++++++++++++++++++++++++++++++++ docs/development/roadmap.md | 4 +- docs/index.md | 2 +- docs/milestones.md | 6 +- docs/todo.md | 2 +- 8 files changed, 117 insertions(+), 12 deletions(-) create mode 100644 docs/deployment/secrets.md diff --git a/docs/deployment/configuration.md b/docs/deployment/configuration.md index 2f226a6..bfb1035 100644 --- a/docs/deployment/configuration.md +++ b/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 diff --git a/docs/deployment/docker.md b/docs/deployment/docker.md index ec6ac47..f18d9dd 100644 --- a/docs/deployment/docker.md +++ b/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 \ No newline at end of file +3. On Windows, ensure you've enabled Docker file sharing for the relevant drives diff --git a/docs/deployment/manual.md b/docs/deployment/manual.md index 3680dfe..748e918 100644 --- a/docs/deployment/manual.md +++ b/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 -``` \ No newline at end of file +``` diff --git a/docs/deployment/secrets.md b/docs/deployment/secrets.md new file mode 100644 index 0000000..fe4f5d6 --- /dev/null +++ b/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. diff --git a/docs/development/roadmap.md b/docs/development/roadmap.md index f4c554e..74e3a45 100644 --- a/docs/development/roadmap.md +++ b/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. diff --git a/docs/index.md b/docs/index.md index 7ce2413..7bd1e8c 100644 --- a/docs/index.md +++ b/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. \ No newline at end of file +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). diff --git a/docs/milestones.md b/docs/milestones.md index f402c2e..aed12e5 100644 --- a/docs/milestones.md +++ b/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. diff --git a/docs/todo.md b/docs/todo.md index ceb7535..49ae262 100644 --- a/docs/todo.md +++ b/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