Deployment

Deployment Instructions for memory-journal-mcp

Tip

Value Proposition: Memory Journal's zero-trust CI/CD pipeline enforces five parallel quality and security gates, SHA-pinned GitHub Actions, Docker Scout CVE verification, and npm provenance attestation—ensuring every container and package release is deterministic, auditable, and supply-chain hardened.

How deployment works

The full CI/CD pipeline (gatekeeper.yml) triggers automatically on push to main or a v* tag. It runs five gates in parallel, then deploys when triggered by a version tag (refs/tags/v*):

1. Lint + Tests (lint-and-test.yml)
2. CodeQL (codeql.yml)
3. Secrets scanning (secrets-scanning.yml)
4. Trivy security scan (security-update.yml)
5. E2E Validation (e2e.yml)

Pushing to main runs the five quality gates. Pushing a v* tag triggers docker-publish.yml once all five gates pass, executing the release pipeline in strict sequence:

1. Docker Scout CVE Scan (builds local image and fails on critical/high CVEs with fixes)
2. Functional Smoke Test (--help CLI verification and /health HTTP endpoint readiness check)
3. Multi-Arch Native Build (linux/amd64 + linux/arm64) & SBOM/Provenance Attestation
4. Manifest Merge & Docker Hub README Sync (DOCKER_README.md < 25,000 chars)
5. npm Publish Handoff (publish-npm.yml via workflow_call to build, verify, and publish memory-journal-mcp to npm with provenance)

Deployment Architecture Constraints

Node.js Requirement: The server explicitly mandates Node.js 24+ (recommend Node.js 26.x LTS) for all deployments.

Single-Instance Requirement: memory-journal-mcp is designed for single-instance operation. If you run multiple instances (e.g., behind a load balancer), you MUST explicitly document and enforce single-writer / single-instance behavior for the restore_backup tool to prevent database corruption during an active restore operation.

Action Versioning Requirement: All CI/CD Actions must be SHA-pinned (by digest, not version tag) according to MCP Builder Rules to prevent supply chain attacks.

To trigger a release

Automatic (push a version tag): Push a version tag matching v* (e.g., vX.Y.Z). When github.ref starts with refs/tags/v, gatekeeper.yml runs all five quality gates and then triggers docker-publish.yml, which chains publish-npm.yml. (Note: Pushing directly to main without a v* tag only runs the five quality gates without triggering docker-publish.yml or publish-npm.yml).

Required GitHub Secrets

Make sure these are set in Settings → Secrets → Actions:

Secret	Purpose
DOCKER_USERNAME	Docker Hub login (writenotenow)
DOCKER_PASSWORD	Docker Hub password or access token
NPM_TOKEN	npm automation token

Required GitHub Environments

Two protected environments must exist with appropriate approval rules:

Environment	Used by	URL
production	Docker manifest push (on tags)	https://hub.docker.com/r/writenotenow/memory-journal-mcp
npm	npm publish	https://www.npmjs.com/package/memory-journal-mcp

What gets published

• Docker Hub: writenotenow/memory-journal-mcp:latest, writenotenow/memory-journal-mcp:v<version>, and writenotenow/memory-journal-mcp:sha-<short> (plus platform-specific sha-<short>-amd64 and sha-<short>-arm64). Multi-arch: linux/amd64 + linux/arm64.
• npm: memory-journal-mcp (public, with provenance). Version is read from package.json. If the current version is already on npm, publish is skipped silently.
• Local Docker Compose (docker-compose.yml): The repository includes a docker-compose.yml defining memory-journal-mcp (default stdio service) and memory-journal-mcp-http (HTTP/SSE service activated via docker compose --profile http up -d, exposing port 3000 and Prometheus metrics port 9465 with a built-in /health healthcheck).

Version bump checklist (before deploying)

Per the release process memory:

1. Update package.json version
2. Update pnpm-lock.yaml (run pnpm install)
3. Update server.json version field
4. Ensure the OCI identifier tag in server.json remains :latest

Docker Hub Limitations

Important: The DOCKER_README.md file must be strictly < 25,000 characters to successfully sync with Docker Hub. If it exceeds this limit, the Docker Hub sync step will fail. Keep the Docker-specific README concise and link out to the full wiki for detailed information.

Docker Scout gate

A security scan runs before any image is pushed. If Docker Scout finds critical/high CVEs with available fixes, the build fails and nothing publishes (neither Docker nor npm). You'll need to address the CVEs first.