Hack on the backend¶
Run your stack against a checkout of Soliplex itself instead of the pinned
release, so an edit to the backend source restarts the server the way an edit
to your own package or under backend/environment/ already does. This builds on the core walkthroughs
— First steps through
Add a custom tool — so have a stack you have brought
up at least once.
Prerequisites¶
- A generated stack, up and working (the three core tutorials).
-
A
soliplex-templateskill build of v0.16 or later — that release introduced both thesrc/project layout andsrc_projects.py— and recent enough to watch every project on the path: itssrc_projects.py listshows awatchedcolumn. Ask your agent to upgrade it, or: -
A stack in the v0.16
src/project layout. If you generated yours by following an earlier version of these tutorials, convert it first — see Move to thesrc/project layout. This is not optional, and nothing will stop you: an older stack hasPYTHONPATH: /app/src, whichsrc_projects.pyhappily appends to, leaving the mount point itself an import root.src/is then asys.pathentry, so the checkout's repo root joinssoliplex.__path__ahead of the real package —soliplex.alembicandsoliplex.testsbecome importable, and the package you meant to edit is the second portion, not the first.listis the cheap pre-flight check; run it before step 1:A converted stack names each project and shows your own marked
*and on the path. An unconverted one gives itself away with a(no such directory) /app/src yesrow. -
A stack whose own project is not named
soliplex. Its project directory would besrc/soliplex/— exactly where the checkout goes. The generator defaults tosoliplex-dojofor this reason; if you named yourssoliplex, generate a fresh one for this walkthrough.
1. Clone Soliplex into src/¶
Every entry under a stack's src/ is a project directory, and the checkout
becomes a sibling of your own project. Ask your agent to "clone the soliplex
backend into this stack's src/". The skill runs:
That does three things: clones the repo to src/soliplex/, appends
/app/src/soliplex/src to the backend's PYTHONPATH in docker-compose.yml,
and adds a matching --reload-dirs=/app/src/soliplex/src to the backend's
serve command. It reports what it did:
cloned https://github.com/soliplex/soliplex into src/soliplex
added: /app/src/soliplex/src
dependencies: every runtime dependency src/soliplex declares is already
in the backend image.
reload: watching /app/src/soliplex/src ('--reload-dirs')
Every project on the backend's path is watched the same way, your own package
from the start, so nothing here is specific to Soliplex. On an older stack it
also settles the reload mode: --reload=both becomes --reload=config, since
the checkout's --reload-dirs now does what both added; --reload=python
stays, being what turns reload on without watching the config, and the script
notes that --reload=config would work as well.
Nothing is needed for git: .gitignore already ignores everything under src/
except the stack's own project, so the checkout stays part of its own repo.
2. Restart the backend¶
Editing docker-compose.yml is a compose change, which --reload=config does
not pick up:
3. Confirm the checkout is what's running¶
PYTHONPATH is searched before site-packages, so the checkout's modules win
over the installed release. Check it from inside the container with the
soliplex-dev service, which mirrors the backend's PYTHONPATH exactly:
docker compose run --rm soliplex-dev \
/app/.venv/bin/python -c "import soliplex; print(soliplex.__path__)"
soliplex is a namespace package, so those two directories merge rather
than one shadowing the other: every module the checkout has wins, and the
installed release fills the gaps. Two consequences worth knowing —
- a module the checkout deletes or renames stays importable from the installed copy, so a clean-looking run may still be executing old code;
- nothing was installed, so the distribution metadata still reports the pinned
version. Anything that reads it —
pip list, the admin/v1/installation/versionsview — shows the release, not the checkout.
4. Watch an edit take effect¶
Follow the backend's log in one terminal:
Then edit any module under src/soliplex/src/soliplex/ on the host. The
reloader, watching the checkout through its --reload-dirs, notices the change
and restarts the server, and the next request runs your edited code — no
rebuild, no docker compose up.
The mount is read-only for the backend and the container runs as the
PUID:PGID from .env, so edit on the host; the backend only reads.
5. Run backend tasks against the stack¶
soliplex-dev is a one-shot task runner (held out of docker compose up by
profiles: ["devmode"]) built on the backend's image, with the stack's config,
secrets and databases — and src/ mounted read-write. Validate the
installation the backend actually serves:
A checkout of main is usually ahead of the pinned release, so its database
schema may be too. The backend applies the checkout's revisions itself when it
restarts, since it migrates on startup; to apply them first, where you can see
them, run soliplex-cli database in the same environment:
(database status in place of upgrade reports without changing anything.)
soliplex-dev also carries every src/ project's dev dependency group, so
the checkout's own test suite runs against the backend's versions. Cloning it
added its group to soliplex-dev/requirements-dev.txt; rebuild, then run it
from the checkout's root:
docker compose build soliplex-dev
docker compose run --rm --no-deps -w /app/src/soliplex soliplex-dev \
/app/.venv/bin/python -m pytest
A dev requirement that needs a different version of something the image has
fails that build, the same conflict step 6 describes, met in the dev group.
Generate new revisions with alembic itself, from the checkout's own root
(alembic writes into versions/ and prepends . to sys.path, so the -w
matters):
docker compose run --rm -w /app/src/soliplex soliplex-dev \
/app/.venv/bin/alembic -x soliplex.installation_path=/environment \
revision --autogenerate -m "add a column"
6. When you need a rebuild¶
PYTHONPATH makes source importable; it does not install anything. If the
checkout imports a distribution the backend image lacks, the import fails at
runtime and docker compose up -d backend will not fix it. clone/add
check each requirement the checkout declares inside the backend image, and
report it as satisfied, MISSING (not installed), or CONFLICT
(installed, at a version the checkout rejects); without Docker, or before the
image is built, they say they could not check.
A missing distribution goes in backend/requirements.txt, then
A conflict cannot be fixed that way: the build freezes the image's own versions
as constraints, and fails rather than move one. A checkout of main that has
moved a dependency ahead of the latest release is the usual case. In order of
preference:
- adapt the checkout to the image's versions — relax its requirement, and port any code that needs the newer one; you cloned it to work on it;
- pick a soliplex image tag (the
FROMline inbackend/Dockerfile) whose release has versions it accepts; - customize
backend/Dockerfile.
See Backend image & dependencies.
The check covers the checkout's direct requirements only. To catch a problem deeper in its tree, import it in the backend's environment:
An ImportError names what the image lacks or has at the wrong version; see
Checking it in the backend's environment.
7. Going back to the release¶
Take the checkout off the import path and the watch list — it leaves the clone itself untouched:
Then docker compose up -d backend. At any point, src_projects.py list shows
which projects are under src/, which are on the path, and which are watched.
Where next¶
The same mechanism works for any repo, not just Soliplex — a library you depend on, a tool you are patching — hot reload included. See Custom Python package for that, and Next steps for the other walkthroughs.