joakimp/mempalace-toolkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

contrib: devbox-aware scheduler templates (host-side, docker exec)

Browse Source 
On hosts running a long-lived opencode-devbox (or equivalent)
container, mempalace-session lives INSIDE the container, not on
the host. The existing contrib/* templates install a scheduler on
the machine that runs the tool; for the devbox case the scheduler
has to live on the host and reach into the container via
'docker exec'. This was noted in passing in contrib/README.md but
no templates were actually shipped for it.

Adds parallel *-devbox templates for systemd and cron:

contrib/systemd/mempalace-session-devbox.service
  - Type=oneshot, same 2h TimeoutStartSec + low Nice as the direct
    variant.
  - Two Environment knobs (CONTAINER, CONTAINER_USER) default to
    opencode-devbox/developer, overrideable via
    'systemctl --user edit'.
  - ExecCondition checks 'docker ps --filter name= --filter
    status=running' so the unit no-ops cleanly when the container
    is currently down. systemd reports this as a successful
    'condition failed' state — no alert noise across dev cycles
    of teardown/rebuild.
  - ExecStart is plain /usr/bin/docker exec with no shell; systemd
    does the env-var expansion.
  - Stdout/stderr go to journalctl --user -u <unit> (nothing to
    redirect, since docker exec surfaces container output to the
    calling process).

contrib/systemd/mempalace-session-devbox.timer
  - Mon 03:00 Persistent=true RandomizedDelaySec=30m, mirrors the
    direct timer.

contrib/cron/mempalace-session-devbox.cron
  - Equivalent shell-wrapped form for hosts using cron instead of
    systemd. 'docker ps | grep -q .' short-circuits if the container
    isn't running. Log goes to $HOME/.cache/mempalace-session/
    cron-devbox.log on the HOST (outside the container) so it's
    inspectable without dropping into the devbox.

contrib/README.md:
  - Replaces the two-paragraph 'Running inside a container' note
    with a proper section: preconditions, install recipes for both
    the systemd and cron devbox variants, verify/uninstall commands,
    customization via 'systemctl --user edit', behaviour when the
    container is down.
  - Chooser table gains a dedicated row pointing devbox users at
    the *-devbox templates, and mentions the systemd vs cron pick
    for that case.
  - New 'When to pick devbox variants vs direct ones' table covers
    the rare both-installed case (host mempalace AND in-container
    mempalace see separate palaces — they don't cross-pollinate).

Top-level README.md 'Keeping it fresh' subsection gains a quick-start
block for the devbox variant alongside the existing Linux/macOS
quick-starts.

Tested: all four systemd units parse cleanly as INI via
configparser (sections + key=value pairs); validated file sizes
and locations match the layout described in docs. Runtime
validation (systemctl --user enable; actual docker exec) requires
a host with docker + an opencode-devbox container up — deferred
to the user's Mac/Linux boxes.
This commit is contained in:
Joakim Persson
2026-04-30 14:09:15 +00:00
parent 4dcd2959ec
commit 46bcce5a67
5 changed files with 204 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
contrib/README.md
+100 -10
View File
@@ -184,25 +184,115 @@ crontab -e # remove the mempalace-session line by hand
| Situation | Pick |
|---|---|
| Desktop / laptop, modern systemd-based Linux distro | systemd user timer |
| macOS (any recent version) | launchd user agent |
| Long-running Linux devbox or server, wants "Persistent=true" catch-up | systemd user timer |
| BSD, Alpine, or Linux distro without systemd | cron |
| You already have a cron-based job scheduler on the box | cron |
| Desktop / laptop, mempalace installed directly on the host, modern systemd-based Linux | `systemd/mempalace-session.{service,timer}` |
| macOS (any recent version), mempalace on the host | `launchd/se.jordbo.mempalace-session.plist` |
| Long-running Linux devbox or server, mempalace on the host | `systemd/mempalace-session.{service,timer}` |
| **opencode-devbox (or similar) container with mempalace *inside* it** | **`systemd/mempalace-session-devbox.{service,timer}`** (preferred) or `cron/mempalace-session-devbox.cron` (simpler) |
| BSD, Alpine, or Linux distro without systemd | `cron/mempalace-session.cron` |
| You already have a cron-based job scheduler on the box | any `cron/*.cron` template |
| You want logs in `journalctl` (Linux) or Console.app (macOS) rather than a file | systemd user timer / launchd |
If you're not sure: **systemd on Linux, launchd on macOS, cron only when neither is available**. All three wrap the same `mempalace-session` command — the difference is purely in *how* the box remembers to run it.
If you're not sure: **systemd on Linux, launchd on macOS, cron only when neither is available. Use the `-devbox` variant when mempalace lives inside a long-running container rather than on the host.** All templates wrap the same `mempalace-session` command — the difference is purely in *where* the scheduler lives and whether it needs to `docker exec` into a container to reach the tool.
---
## Running inside a container (devbox)
Inside a Docker-based devbox, neither systemd nor cron typically runs by default. Two options:
If you run opencode inside a long-lived container like [opencode-devbox](https://gitea.jordbo.se/joakimp/opencode-devbox), neither systemd nor cron is running inside that container — they're host-level services. The correct pattern is **host-side scheduling that `docker exec`s into the running container**. The `*-devbox` templates in `contrib/systemd/` and `contrib/cron/` implement exactly this.
1. **Schedule on the host, not the container** — have the host run `docker exec -u <user> <container> mempalace-session` on a timer. The container must be long-running (not per-invocation) for this to work.
2. **Run a systemd-in-container setup** — viable but usually not worth the complexity for this alone.
Preconditions:
For most devbox users, a simple weekly manual run via `mempalace-session` (or a host-side cron that shells into the container) is the pragmatic choice. The tool is cheap enough that skipping a week costs nothing — dedup will catch up on the next run.
- **Long-lived container.** `docker compose up -d` with `restart: unless-stopped` (or equivalent). If the container is ephemeral (per-invocation), this pattern doesn't apply.
- **`mempalace-session` is already installed inside the container.** opencode-devbox bakes it in via `mempalace-toolkit`, so a running devbox already satisfies this.
- **Host user can talk to docker.** Member of the `docker` group on Linux, or Docker Desktop running under the current login session on macOS.
- **Canonical container name is `opencode-devbox`.** If you renamed it via `container_name:` or docker-compose project naming, adjust `CONTAINER` in the template.
Both devbox templates guard against "container currently stopped" — they no-op silently if `docker ps` shows no running container with the expected name. That makes the timer safe to leave enabled across dev cycles where you tear the container down and bring it back up.
### systemd user timer (host-side, devbox variant)
```bash
# Install
mkdir -p ~/.config/systemd/user
cp contrib/systemd/mempalace-session-devbox.service ~/.config/systemd/user/
cp contrib/systemd/mempalace-session-devbox.timer ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now mempalace-session-devbox.timer
# Keep the timer running across logout (typical on dev hosts)
sudo loginctl enable-linger "$USER"
```
**Customize container name / user** (if you don't use the defaults):
```bash
systemctl --user edit mempalace-session-devbox.service
# In the override that opens, set:
# [Service]
# Environment=CONTAINER=my-devbox-name
# Environment=CONTAINER_USER=my-user
```
Or edit the shipped service file in place before copying.
**Verify:**
```bash
systemctl --user list-timers mempalace-session-devbox.timer
systemctl --user status mempalace-session-devbox.service
journalctl --user -u mempalace-session-devbox --since today
# Force a run right now (while the container is up)
systemctl --user start mempalace-session-devbox.service
```
**Behaviour when the container is down:** `ExecCondition` fails, service is marked "condition failed" (considered a successful no-op by systemd), no alert noise. Bring the container back up and the next scheduled fire will run normally.
**Uninstall:**
```bash
systemctl --user disable --now mempalace-session-devbox.timer
rm ~/.config/systemd/user/mempalace-session-devbox.{service,timer}
systemctl --user daemon-reload
```
### cron (host-side, devbox variant)
```bash
# Read the template — it has CONTAINER / CONTAINER_USER at the top.
# Adjust if your setup differs from opencode-devbox defaults.
cat contrib/cron/mempalace-session-devbox.cron
# Install (preserves existing crontab entries)
(crontab -l 2>/dev/null; cat contrib/cron/mempalace-session-devbox.cron) | crontab -
# Ensure the log directory exists
mkdir -p ~/.cache/mempalace-session
# Verify
crontab -l | grep mempalace-session-devbox
tail -f ~/.cache/mempalace-session/cron-devbox.log
```
**Uninstall:**
```bash
crontab -e # remove the mempalace-session-devbox line by hand
```
### When to pick devbox variants vs direct ones
| Setup | Templates to use |
|---|---|
| mempalace installed directly on the host (no devbox) | `mempalace-session.{service,timer}`, `mempalace-session.cron`, `se.jordbo.mempalace-session.plist` |
| opencode-devbox container is where opencode + mempalace live | `mempalace-session-devbox.{service,timer}`, `mempalace-session-devbox.cron` |
| Both (rare — mempalace on host AND inside a separate devbox) | Install both; they write to separate palaces. |
The in-container mempalace sees only the container's opencode.db and palace (via named volumes). The host's mempalace, if installed, sees only the host's. Two parallel palaces don't cross-pollinate — decide where you want the source of truth to live and schedule accordingly.
### Alternative not documented here
"Run systemd inside the container" is technically viable (systemd-in-docker images exist) but adds non-trivial complexity for the sake of a once-weekly batch job. The host-scheduled approach above is equivalent in outcome and much simpler. Skip systemd-in-container unless you already have other reasons to need it.
---