bytelyst-devops-tools/deployments/open-notebook-pilot/README.md

ByteLyst private Open Notebook pilot

Status: private localhost-only pilot. Do not publish as a public ByteLyst dashboard/subdomain.

Files and runtime locations

• Compose: deployments/open-notebook-pilot/docker-compose.yml
• Protected env/secrets: /etc/bytelyst/open-notebook-pilot.env (mode 0600, not in git)
• Runtime data: /opt/bytelyst/open-notebook-pilot/
  • surreal_data/: SurrealDB RocksDB data
  • notebook_data/: Open Notebook uploaded/app data
  • ollama/: local Ollama model cache
  • test-docs/: sanitized pilot documents
  • reports/: smoke/evaluation outputs
  • backups/: protected backup archives

Network hardening

• Web UI binds to 127.0.0.1:8502 only.
• REST API binds to 127.0.0.1:5055 only.
• SurrealDB has no host-published port.
• Ollama has no host-published port.
• Remote access, if needed, must use SSH tunnel/VPN/private route only:
  • ssh -L 8502:127.0.0.1:8502 -L 5055:127.0.0.1:5055 <vm>
• Do not add this service to the public Caddyfile. If a private reverse proxy is ever required, put it behind strong auth and keep /docs, /openapi.json, and /health away from the public internet.

Secrets

/etc/bytelyst/open-notebook-pilot.env contains:

• OPEN_NOTEBOOK_ENCRYPTION_KEY
• OPEN_NOTEBOOK_PASSWORD
• SURREAL_USER
• SURREAL_PASSWORD
• explicit CORS_ORIGINS
• OLLAMA_BASE_URL=http://ollama:11434

Do not print this file in logs or commit it. Losing or changing the encryption key can make stored provider credentials unreadable.

Operations

From the repo root:

docker compose --env-file /etc/bytelyst/open-notebook-pilot.env -f deployments/open-notebook-pilot/docker-compose.yml config --quiet
docker compose --env-file /etc/bytelyst/open-notebook-pilot.env -f deployments/open-notebook-pilot/docker-compose.yml up -d

Health checks:

curl -fsS http://127.0.0.1:5055/health
curl -fsS http://127.0.0.1:5055/api/auth/status
curl -fsSI http://127.0.0.1:8502

Use the bearer password from the protected env file for API calls:

curl -fsS -H "Authorization: Bearer <password-from-/etc/bytelyst/open-notebook-pilot.env>" http://127.0.0.1:5055/api/notebooks

Ollama local provider

The compose stack includes an internal Ollama service at http://ollama:11434 for the Open Notebook container. Initial pilot model targets:

• LLM: qwen2.5:0.5b or another small local model that fits current VM headroom.
• Embeddings: nomic-embed-text if pull time/resources allow.

Configure/register models through Open Notebook Settings or the /models API. Cloud providers are allowed only with sanitized comparison data.

Sanitized ingestion and smoke search

Sanitized docs live in /opt/bytelyst/open-notebook-pilot/test-docs. Run:

scripts/open-notebook-pilot/ingest-and-search-smoke.sh

The script creates a pilot notebook, ingests text sources without embeddings, and writes text-search smoke outputs under /opt/bytelyst/open-notebook-pilot/reports/.

Backup and restore test

Backup:

scripts/open-notebook-pilot/backup.sh

Restore-readiness test:

scripts/open-notebook-pilot/restore-test.sh /opt/bytelyst/open-notebook-pilot/backups/<archive>.tar.gz

The restore test extracts to /opt/bytelyst/open-notebook-pilot/restore-test/extracted and verifies the backup contains SurrealDB data, notebook data, and the protected env file. Actual restore should be performed only during planned downtime by stopping the stack and replacing the runtime directories/env from the verified archive.