oswatcher-deploy

Docker Compose deployment stack for the OSWatcher platform — a queryable graph of operating system evolution.

This repository orchestrates the full OSWatcher service stack:

                 ┌─────────────┐
   HTTPS ──────▶ │   Traefik   │ reverse proxy, TLS termination
                 └──────┬──────┘
              ┌─────────┴──────────┐
              ▼                    ▼
        ┌───────────┐        ┌───────────┐
        │ GraphQL   │        │   MinIO   │ S3-compatible blob storage
        │   API     │───────▶│           │ (file contents)
        └─────┬─────┘        └───────────┘
              ▼
        ┌───────────┐
        │   Neo4j   │ graph database (filesystem/registry/symbol history)
        │ + APOC    │ + oswatcher-procedures (custom tree-diff procedures)
        └───────────┘

The production overlay runs the published images, both on your own machine and on a server. Clone only this repository:

git clone https://github.com/OSWatcher/oswatcher-deploy
cd oswatcher-deploy

The repository includes local defaults; no configuration or password setup is needed. Then start the stack:

docker compose up -d

The committed .env selects compose.yml and compose.prod.yml. It defaults to HTTP on localhost, loopback-only published ports and modest Neo4j memory settings. No domain registration or TLS certificate is needed.

Open http://localhost. Other endpoints:

• GraphQL API: http://api.localhost/graphql or http://localhost:4000/graphql
• Neo4j browser: http://localhost:7474
• MinIO console: http://localhost:9001

Verify the API:

curl --fail -s -X POST http://localhost:4000/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ branches { name } }"}'
# {"data":{"branches":[]}}

A fresh graph is empty. A ready-to-use database download is planned; until it is published, use osw-builder to build and capture OS images. Starting the services does not create an OS corpus.

Stop the stack while keeping its data:

docker compose down

Development mode builds the API, frontend, and Neo4j procedures from sibling checkouts. Clone all three next to this repository first, or the build fails on missing contexts:

cd ..
git clone https://github.com/OSWatcher/graphql-api
git clone https://github.com/OSWatcher/frontend
git clone https://github.com/OSWatcher/oswatcher-procedures
cd oswatcher-deploy

docker compose -f compose.yml -f compose.dev.yml up -d --build

compose.yml is a base layer and is not runnable on its own: the api service has no image or build context until an overlay supplies one. The template selects the production overlay by default. The explicit -f flags above override that selection for development.

Development mode needs no registry credentials and no domain, which makes it suitable for developing the services. Use the quickstart above to evaluate the published images.

• Frontend: http://localhost:5173
• API: http://api.localhost (via Traefik) or http://localhost:4000
• Neo4j browser: http://localhost:7474
• MinIO console: http://localhost:9001

Smoke test:

curl -s -X POST http://localhost:4000/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ branches { name } }"}'
# {"data":{"branches":[]}}

An empty branches list is correct on a fresh deployment: the graph starts empty and is filled with osw-builder.

Use the same compose.prod.yml overlay. Edit .env to set DOMAIN to your domain, HTTP_SCHEME=https, and BIND_ADDRESS to the server interface you intend to expose. Replace the local MinIO credentials, then configure DNS and a trusted TLS certificate for <DOMAIN>, api.<DOMAIN> and storage.<DOMAIN>. Certificate provisioning is not automated by this repository; Traefik otherwise serves its default self-signed certificate.

Configure Neo4j authentication and size its heap/page cache for your corpus. BIND_ADDRESS applies to all published service ports, including the database and storage; restrict those ports through your firewall when exposing the proxy publicly.

The MinIO root password must be non-default. For existing deployments without HTTP_SCHEME or memory overrides, HTTPS routing and the previous server memory defaults are retained.

docker compose up -d

If an existing .env does not set COMPOSE_FILE, use the explicit equivalent:

docker compose -f compose.yml -f compose.prod.yml up -d

See docs/deployment.md for the deployment and rollback runbook.

Scripts in scripts/ cover both stateful services:

./scripts/neo4j-backup.sh                                  # dump Neo4j
./scripts/minio-backup.sh                                  # archive MinIO data volume
./scripts/restore-backup-offline.sh <backup_file> [dev|prod]  # offline Neo4j restore

Warning: never run docker compose down -v — it deletes the named volumes holding the database and blob storage.

Apache 2.0