devlab-setup

One command to go from nothing to a running devmid with a disposable Forgejo, a stubbed billing API and HuggingFace, and a sandbox repo it can safely commit to. Nothing touches production.

Quick start

git clone <this repo> && cd devlab-setup
cp real.env.example real.env
$EDITOR real.env          # fill in the five Keycloak values
./setup.sh

That clones devlab, devmid and security-watcher-custom-models as siblings in ./devlab-workspace/, patches the devmid checkout, resolves port conflicts, bootstraps Forgejo, and starts devmid.

Then:

cd devlab-workspace/devlab
export DEVMID_TOKEN='<a real Keycloak access token>'
./scripts/smoke.sh

Options

./setup.sh ~/work/regolo     # workspace somewhere else
./setup.sh --update          # git pull all three repos, then re-run
./setup.sh --reset           # wipe containers and volumes, start over
./setup.sh --no-start        # set up but do not start devmid
./setup.sh --branch feat/x   # that branch of devmid + watcher

Idempotent. Re-running skips finished work and never overwrites real.env, .env, or the sealing keys, so it doubles as a recovery tool when something fails halfway.

Repo URLs are overridable: DEVLAB_GIT, DEVMID_GIT, WATCHER_GIT.

Requirements

git, curl, jq, openssl, python3, and Docker or Podman with compose. Port detection additionally wants ss or lsof; without either the check is skipped and you get compose's own bind error instead.

real.env

Genuine credentials, loaded into the devmid container via env_file after .env.devmid, so it wins over any cluster dump. Only the five Keycloak variables are mandatory — devmid builds SecurityConfig() at module import and raises without them.

Use the real Keycloak. Validating a token is read-only and changes nothing in production, and a fake issuer would reject the token you hand smoke.sh — which is the fastest way to make the lab lie to you.

Do not put DATABASE, any FORGEJO_*, PYTHONPATH, DEVLAB_* or SECURITY_WATCHER_API_TOKEN in it. Compose's environment: block beats every env_file, so those are ignored. That is deliberate for FORGEJO_*: nothing in real.env can point devmid at your production infra repo.

It is not shell. No quotes, no $VAR references — both end up inside the value.

real.env is gitignored. Keep it that way.

What it does to the devmid checkout

Applies the fixes in devlab/patches/, keeping *.bak backups. These are bugs in the repo, unrelated to the lab:

• start-local.sh sets YAML_COMMIT_REPO_OWNER, YAML_COMMIT_REPO and GITHUB_TOKEN, but the code reads FORGEJO_YAML_COMMIT_REPO_OWNER, FORGEJO_YAML_COMMIT_REPO, FORGEJO_TOKEN and FORGEJO_BASE_URL. GitHubRepo.__init__ raises when any is missing, and REPO_HANDLER = GitHubRepo() runs at module scope — so devmid could not import at all. tests/conftest.py sets the new names, which is why the test suite passes while the dev server does not.
• docker-compose.local.yml declared postgres: three times; YAML keeps only the last, silently discarding the rest.
• .env.local gains the four FORGEJO_* names and the sandbox token, so start-local.sh points at the lab's Forgejo too.

Isolation

Each workspace gets its own COMPOSE_PROJECT_NAME, derived from its path. Without it, two labs on one machine both answer to the project name devlab and silently share containers and volumes — which shows up as a bootstrap that looks half-finished ("user already exists") and ports held by nothing.

Testing

smoke.sh is version-agnostic and is the one to run first. It proves devmid boots against the lab database, accepts a real token, has its outbound calls intercepted, and commits a manifest — and reports which folder the manifest landed in. On pre-v3 code expect devmid/ and an un-pinned model URL; both change in v3.

e2e.sh is v3-only. Against v2 it fails on its first assertion because /security/to_scan does not exist yet — that is the test being right, not the lab being broken. For the pre-v3 watcher, set SCAN_PROTOCOL=v1 in devlab/.env first: the signed callback message changed from {salt}:{model_name}:{verdict} to {salt}:{scan_id}:{verdict}:{content_digest}, and the wrong setting makes every callback fail signature verification, which looks like a crypto bug and is not one.

Troubleshooting

docker compose logs -f devmid first.

Symptom	Cause
ALL forgejo envs are required	FORGEJO_* did not reach the container
Missing required Keycloak environment variables	one of the five is empty or quoted — check docker compose exec devmid env | grep KEYCLOAK
No devlab: redirecting in the logs	PYTHONPATH is not finding /devlab; devmid may be calling the real billing API
Forgejo unable to open database file	SQLite path outside a directory the git user owns; ./setup.sh --reset
devmid cannot read the certificates	rootless podman UID shifting: podman unshare chown -R 1000:1000 devlab/sealed