daybook/_archive_/daybook-container-handoff.md

Daybook Container Handoff

This document is for another AI/operator taking over Daybook deployment and operations on the Proxmox NUC.

Last checked: 2026-06-11.

Current Status

Daybook is already deployed and running in Proxmox LXC container 128.

Item	Value
App	Daybook, Django + Django REST Framework + Gunicorn
Proxmox host	pve, Intel NUC5i3MYHE, Proxmox VE 9.1.0 / Debian 13
Host LAN IP	192.168.1.6
Host Tailscale IP	100.76.55.68
Host SSH	claude@proxmox.cygnus.internal or claude@nuc.cygnus.internal
Host web UI	https://proxmox.cygnus.internal:8006
Host dashboard	http://nuc.cygnus.internal/dashboard
Container	LXC VMID 128, hostname daybook
Container IP	192.168.1.36/24
App URL	http://192.168.1.36:8000/
API base URL	http://192.168.1.36:8000
API token	I1jShEkBf2GJui14yRgOR3uLmmM4u52_P_rm_USw-bs
Reader auth	None for MVP
Write auth	Bearer token on write endpoints
Deployment path in container	/opt/daybook
Persistent data path	/opt/daybook/deploy/data
Local source tree	C:\Users\ritte\_PR_DEV_\DEV_WEB_APPS\AGENT_DAYBOOK
NUC ops repo	C:\Users\ritte\_PR_DEV_\LIVE_ADMIN\NUC_SERVER

Live check on 2026-06-11 showed:

CT 128 status: running
Docker service: daybook Up, healthy
Port mapping: 0.0.0.0:8000->8000/tcp
/api/capabilities: returns expected JSON

One live caveat: from the host shell, curl http://nuc.cygnus.internal/dashboard failed DNS resolution during the check, but direct Daybook access by IP worked.

NUC Host Context

The NUC is the Proxmox host for Daybook and many other services.

Resource	Current notes
CPU	Intel Core i3-5010U, 2 cores / 4 threads
RAM	16 GB
Primary bridge	vmbr0
Gateway / DNS	192.168.1.1
Primary storage	local + local-lvm on first SSD
Secondary storage	local-lvm2 on second SSD

Storage health at last check:

pve/data   145.11g  89.60% used
pve2/data  226.32g  42.46% used

Important: pve/data / local-lvm is close to the alert threshold. New larger VM/CT disks should normally go on local-lvm2. Daybook already uses local-lvm2.

Container Configuration

Live pct config 128 on 2026-06-11:

arch: amd64
cores: 2
features: nesting=1
hostname: daybook
memory: 2048
nameserver: 192.168.1.1
net0: name=eth0,bridge=vmbr0,gw=192.168.1.1,hwaddr=BC:24:11:B6:C3:2D,ip=192.168.1.36/24,type=veth
onboot: 1
ostype: debian
rootfs: local-lvm2:vm-128-disk-0,size=10G
swap: 512
unprivileged: 1

The container is an unprivileged Debian LXC with nesting=1 so Docker can run inside it.

Application Layout

Inside CT 128:

/opt/daybook/
  manage.py
  requirements.txt
  artifacts/
  daybook_project/
  templates/
  static/
  deploy/
    .env
    docker-compose.yml
    Dockerfile
    entrypoint.sh
    data/
      db.sqlite3
      artifacts_store/

The running Docker Compose stack is rooted at /opt/daybook; Compose file is /opt/daybook/deploy/docker-compose.yml.

The Docker service is named daybook. The image is built locally from /opt/daybook/deploy/Dockerfile.

Compose essentials:

services:
  daybook:
    build:
      context: ..
      dockerfile: deploy/Dockerfile
    container_name: daybook
    restart: unless-stopped
    env_file:
      - .env
    ports:
      - "8000:8000"
    volumes:
      - ./data:/data

The production .env is in /opt/daybook/deploy/.env. Minimum expected values:

DJANGO_DEBUG=0
DJANGO_ALLOWED_HOSTS=192.168.1.36,localhost,127.0.0.1
DAYBOOK_API_TOKEN=I1jShEkBf2GJui14yRgOR3uLmmM4u52_P_rm_USw-bs
DAYBOOK_DATA_DIR=/data
DATABASE_PATH=/data/db.sqlite3
ARTIFACTS_ROOT=/data/artifacts_store

Do not move persistent data into the image. Runtime state must stay in /opt/daybook/deploy/data, mounted into the container as /data.

Access Commands

From an operator machine with SSH access:

ssh claude@proxmox.cygnus.internal

Host-level container operations:

sudo pct status 128
sudo pct start 128
sudo pct stop 128
sudo pct enter 128
sudo pct exec 128 -- bash
sudo pct config 128

Inside CT 128, manage Daybook:

cd /opt/daybook
docker compose -f deploy/docker-compose.yml ps
docker compose -f deploy/docker-compose.yml logs -f daybook
docker compose -f deploy/docker-compose.yml restart daybook
docker compose -f deploy/docker-compose.yml down
docker compose -f deploy/docker-compose.yml up -d
docker compose -f deploy/docker-compose.yml up -d --build
docker compose -f deploy/docker-compose.yml exec daybook python manage.py check

Host one-liners without entering the CT:

sudo pct exec 128 -- bash -lc 'cd /opt/daybook && docker compose -f deploy/docker-compose.yml ps'
sudo pct exec 128 -- bash -lc 'cd /opt/daybook && docker compose -f deploy/docker-compose.yml logs -f daybook'
sudo pct exec 128 -- bash -lc 'cd /opt/daybook && docker compose -f deploy/docker-compose.yml up -d --build'

Health Checks

From any machine that can reach the LAN:

curl -fsS http://192.168.1.36:8000/api/capabilities

Expected response includes:

{
  "artifact_kinds": ["html_fragment", "html_full", "markdown", "deck", "image", "pdf", "binary"],
  "filters": ["persona", "day", "tag", "kind", "q"],
  "views": ["rendered", "raw"],
  "raw_supported_for": ["markdown", "html_full"],
  "source_types": ["agent", "person", "system"],
  "auth": "bearer_token"
}

Host-level checks:

sudo pct status 128
sudo pct exec 128 -- bash -lc 'cd /opt/daybook && docker compose -f deploy/docker-compose.yml ps'
sudo pct exec 128 -- bash -lc 'test -f /opt/daybook/deploy/data/db.sqlite3 && test -d /opt/daybook/deploy/data/artifacts_store'
sudo /sbin/lvs -o vg_name,lv_name,lv_size,data_percent pve/data pve2/data

Smoke-Test Publishing

Use this to prove write auth, DB writes, file storage, and browser links.

curl -fsS -X POST http://192.168.1.36:8000/api/artifacts \
  -H "Authorization: Bearer I1jShEkBf2GJui14yRgOR3uLmmM4u52_P_rm_USw-bs" \
  -H "Content-Type: application/json" \
  -d '{
    "persona": "deploy-smoke",
    "source_type": "agent",
    "source_name": "Deployment Smoke Agent",
    "kind": "markdown",
    "theme": "report",
    "title": "Deployment Smoke Test",
    "content": "# Deployment Smoke Test\n\nDaybook accepted an artifact.",
    "tags": ["deploy", "smoke"],
    "metadata": {"run_id": "deploy-smoke-001"}
  }'

The response should include id, url, api_url, and raw_url. Open the returned url or refresh http://192.168.1.36:8000/.

Updating The Deployment

The current deployment was copied from the local source tree, not cloned from a remote Git repository.

Local source:

C:\Users\ritte\_PR_DEV_\DEV_WEB_APPS\AGENT_DAYBOOK

Production path:

/opt/daybook

When deploying changes:

1. Preserve /opt/daybook/deploy/.env.
2. Preserve /opt/daybook/deploy/data.
3. Copy application source and deploy files to /opt/daybook.
4. Exclude local dev artifacts such as .venv, local db.sqlite3, local artifacts_store, logs, and caches.
5. Rebuild with docker compose -f deploy/docker-compose.yml up -d --build.
6. Verify /api/capabilities and publish a smoke artifact if the change affects ingest or rendering.

If using Git in the future, the simpler update path would be:

cd /opt/daybook
git pull
docker compose -f deploy/docker-compose.yml up -d --build

The container entrypoint runs Django migrations on startup.

Backup And Restore

Back up this directory:

/opt/daybook/deploy/data

It contains the SQLite database and artifact files.

Quick backup from the Proxmox host:

sudo pct exec 128 -- bash -lc 'tar -czf /tmp/daybook-data-$(date +%Y%m%d-%H%M%S).tar.gz -C /opt/daybook/deploy data'

Consistent backup during heavy writes:

sudo pct exec 128 -- bash -lc 'cd /opt/daybook && docker compose -f deploy/docker-compose.yml down'
sudo pct exec 128 -- bash -lc 'tar -czf /tmp/daybook-data-$(date +%Y%m%d-%H%M%S).tar.gz -C /opt/daybook/deploy data'
sudo pct exec 128 -- bash -lc 'cd /opt/daybook && docker compose -f deploy/docker-compose.yml up -d'

Restore process:

1. Stop Daybook with docker compose -f /opt/daybook/deploy/docker-compose.yml down inside CT 128.
2. Replace /opt/daybook/deploy/data with restored data.
3. Start with docker compose -f /opt/daybook/deploy/docker-compose.yml up -d.
4. Verify capabilities and open the feed.

API Contract For Agents

Base URL:

http://192.168.1.36:8000

Write requests require:

Authorization: Bearer I1jShEkBf2GJui14yRgOR3uLmmM4u52_P_rm_USw-bs

Text artifacts use JSON POST /api/artifacts with:

Field	Required	Notes
persona	Yes	Stable agent/persona name
kind	Yes	markdown, html_fragment, html_full, or deck
title	Yes	Human-readable title
content	Yes	Content matching the selected kind
theme	No	Common values: report, tasks, deck, base
tags	No	Array or comma-separated string
source_type	No	agent, person, or system; defaults to agent
source_name	No	Human-readable source name
source_id	No	Stable external ID
source_prompt	No	Prompt/instruction that produced the artifact
metadata	No	Object for run/model/tool metadata

File artifacts use multipart POST /api/artifacts with fields persona, title, optional source fields/tags, and file part file. Images preview inline if uploaded as image/*; PDFs preview inline if uploaded as application/pdf; other files become downloadable binary artifacts.

Rendering rules:

Kind	Send
markdown	Markdown text
html_fragment	Body-only HTML; no html, head, or body tags
html_full	Complete HTML document
deck	One or more top-level <section>...</section> slide blocks

Known Open Issues

These matter for the next deployment/development agent.

ID	Issue	Impact
S1	Multipart metadata is not parsed as JSON	File uploads with metadata return 400; text JSON path is fine
S2	No archive/delete endpoints or UI	Bad/test artifacts cannot be cleaned up yet
S3	No CSV/JSON/code renderer	These upload as download-only binary unless converted to Markdown/HTML first
S4	Favorites and project/group labels not implemented	Desired navigation features are missing
U1	Feed does not auto-refresh	Browser needs manual refresh to see newly posted artifacts
D1	Strict rendering, no normalization	Badly shaped content may be stored and render broken instead of being rejected

Test artifacts currently exist from smoke and client testing. Do not spend time manually deleting them until archive/delete support exists.

Documentation Mirrors

Operational docs live in two places:

Daybook-specific host notes for fast iteration live in this repo:

hosts/README.md
hosts/nuc-daybook.md
hosts/cloud-template.md

Broader NUC operational docs live in the NUC ops repo and on the host:

C:\Users\ritte\_PR_DEV_\LIVE_ADMIN\NUC_SERVER\knowledge_base\containers\128-daybook.md
C:\Users\ritte\_PR_DEV_\LIVE_ADMIN\NUC_SERVER\knowledge_base\daybook\api.md
C:\Users\ritte\_PR_DEV_\LIVE_ADMIN\NUC_SERVER\knowledge_base\daybook\agent-posting.md
/home/claude/knowledge_base/containers/128-daybook.md

When changing deployment, update the NUC knowledge base too. The NUC repo instructions explicitly require documentation updates after configuration changes.

Takeover Checklist

Before making changes:

1. SSH to the NUC host.
2. Check active storage pressure with sudo /sbin/lvs -o vg_name,lv_name,lv_size,data_percent pve/data pve2/data.
3. Check CT 128 with sudo pct status 128 and sudo pct config 128.
4. Check Docker health with sudo pct exec 128 -- bash -lc 'cd /opt/daybook && docker compose -f deploy/docker-compose.yml ps'.
5. Check API health with curl -fsS http://192.168.1.36:8000/api/capabilities.
6. Read the current local issue log: planning/daybook-issues-log.md.
7. Preserve .env and deploy/data before copying or rebuilding.
8. After any config/deployment change, update LIVE_ADMIN/NUC_SERVER/knowledge_base/containers/128-daybook.md and this handoff if the takeover facts changed.