Skip to content

Refactor: make ~/anthias install-only — move runtime artifacts to /etc/anthias + /var/lib/anthias #2845

@vpetersson

Description

@vpetersson

Background

bin/install.sh clones the entire Anthias repo to ~/anthias and leaves it there forever. That tree is ~15 MB of git history, source, dockerfiles, ansible, tests, etc. — but very little of it is actually used after the playbook finishes.

Audit of what ~/anthias contributes at runtime / upgrade time:

Path under ~/anthias Used after install? Why
staticfiles/ yes no (after #2846) Bind-mounted into anthias-server as /data/anthias/staticfiles. Container runs collectstatic --clear at startup and WhiteNoise serves from it. So the host dir is just a writable scratch path — the content comes from the container, not the repo. Resolved in #2846: collectstatic now runs at image build, STATIC_ROOT is read-only inside the image, host bind-mount removed.
docker-compose.yml.tmpl yes upgrade_containers.sh runs envsubst over it on every upgrade.
bin/upgrade_containers.sh yes The upgrade entry point.
bin/migrate_legacy_paths.sh yes Called by upgrade_containers.sh.
bin/enable_ssl.sh yes Manual TLS setup.
ansible/, src/, docker/, tests/, static/, webview/, ... no Dead weight. ~95% of the cloned tree.

So the actual runtime/upgrade surface is one compose template, three shell scripts, and one bind-mount target dir. Everything else is install-only.

This came up while reviewing #2842 / #2843, where moving installer_venv to a mktemp -d made the same observation possible: install-time state shouldn't persist. Same logic applies to the cloned repo.

Proposed layout

/etc/anthias/docker-compose.yml.tmpl       (was ~/anthias/docker-compose.yml.tmpl)
/etc/anthias/docker-compose.yml            (rendered each upgrade)
/var/lib/anthias/staticfiles/              (was ~/anthias/staticfiles/)
/usr/local/sbin/anthias-upgrade            (was /usr/local/sbin/upgrade_anthias.sh)
/usr/local/sbin/anthias-upgrade-containers (was ~/anthias/bin/upgrade_containers.sh)

Install-time:

After install, ~/anthias doesn't exist. Operators who want to inspect "what's running" use cat /usr/local/sbin/anthias-upgrade and ~/version.md (or a new anthias --version).

Sub-tasks

  • Drop the staticfiles/ host bind-mount. Done in chore(server): bake collectstatic into image, drop runtime scratch mount #2846: collectstatic now runs at image build (docker/Dockerfile.server.j2), STATIC_ROOT lives inside the read-only image layer (/usr/src/app/staticfiles), and the bind-mount + the runtime invocation are gone. Operators can rm -rf ~/anthias/staticfiles after upgrading.
  • Move runtime shell scripts to /usr/local/sbin/. upgrade_containers.sh and migrate_legacy_paths.sh should live in a system path, not in a user-owned git tree. Keep /usr/local/sbin/upgrade_anthias.sh (the install.sh re-download) as the upgrade entry point.
  • Move docker-compose.yml.tmpl to /etc/anthias/. The rendered docker-compose.yml lives next to it. Update the upgrade script's compose-file path accordingly.
  • Make clone_repo ephemeral. mktemp -d for the install-time tree, EXIT trap to clean up. Aligns the architecture with the post-fix(install): tmpdir installer_venv on Bookworm; drop getmac dep #2843 installer_venv flow.
  • Migration for existing installs. bin/migrate_legacy_paths.sh already handles ~/screenly~/anthias; add a phase that lifts artifacts out of ~/anthias to their new homes, leave a back-compat symlink for one release cycle. We just shipped the screenly→anthias rename in 3c96b541, so this would be the second path-migration generation in flight at once — needs careful handling.
  • Update install/upgrade docs. Hugo site under docs/ references ~/anthias paths; sweep them.

Why this isn't part of #2843

  • [BUG] Installer script throw error on Pi5 64bit Bookworm Raspberry Pi OS #2842 / the forum thread is an active install failure on Bookworm — the surgical --python + tmpdir fix needs to land first and get to users.
  • We just shipped the screenly→anthias rename; layering another path migration on top of that means existing devices run two migrations simultaneously and we ship two compat-symlink generations at once. User-facing disruption compounds.
  • The new architecture is straightforward; the migration for existing devices is the hard part, and warrants its own design pass and review cycle.

Acceptance criteria

After this work, on a fresh install:

  • ~/anthias does not exist (no symlink either, after the migration cycle).
  • bin/install.sh does not leave any persistent state in $HOME other than ~/.anthias (data) and ~/anthias_assets (uploads).
  • upgrade_containers.sh (or its successor) reads/writes only /etc/anthias/ and /var/lib/anthias/.
  • Existing devices on the legacy layout migrate cleanly via migrate_legacy_paths.sh and keep working through one release cycle of back-compat symlinks.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions