docs: fix stale versions, log paths, and local dev setup#511
Merged
docs: fix stale versions, log paths, and local dev setup#511
Conversation
lgelauff
changed the title
Documents common Toolforge debugging steps discovered during beta deployment of the image→filerevision migration: - uwsgi log location (/data/project/montage-beta/uwsgi.log) - pip/Python must run inside toolforge webservice shell, not bastion - restart command syntax - how to inspect the SQLite DB without the sqlite3 CLI Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Step 5: use correct `mariadb` command with explicit -h flag and utf8mb4 charset - Step 6: fix db_url format (mysql+pymysql driver, tools.db.svc.wikimedia.cloud host, charset=utf8mb4) - Step 8 (new): add schema initialisation step (create_schema.py for fresh installs, migrate_prod_db.sql for upgrades) - Debugging: add MariaDB connection section, note that -h flag is required (no local socket on bastion) - Debugging: rename SQLite section to clarify it is legacy/dev only Observed during #514 (beta MariaDB setup). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
All Toolforge deployments now use python3.11. The 3.9 references were stale and would cause a venv mismatch for anyone following the docs from scratch. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
node18 is no longer available on Toolforge. node20 works as a drop-in replacement — no issues observed in practice on montage-dev. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
All three deployments (montage, montage-beta, montage-dev) now use /data/project/<project>/logs/ for log files. Added mkdir step to from-scratch instructions and corrected the debugging section note. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The login button triggers OAuth which doesn't work locally. Developers need to navigate to /complete_login directly to establish their session. Verified working locally (redirects to localhost:5173, sets cookie). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Line numbers drift as the file grows. Reference the MAINTAINERS constant by name instead. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Covers contribution workflow, PR expectations, code quality rules, three-environment deployment model, and the requirement to open and discuss an issue before submitting a PR. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
lgelauff
force-pushed
the
docs/beta-debugging-hints
branch
from
01455dc to
707ee29
Compare
Added guidelines for new contributors to provide a screen recording of issues and changes after checking with other maintainers.
mahmoud
approved these changes
Apr 26, 2026
Member
mahmoud
left a comment
mahmoud
left a comment
There was a problem hiding this comment.
Looks good! couple of points about sqlite, but that'll be a separate PR :)
|
|
||
| - Follow existing patterns in the file you're editing | ||
| - Backend: read `montage/rdb.py` before writing queries — column names are authoritative there. Note that `.filter()` and `.order_by()` return new objects — always reassign | ||
| - Backend: write code that works with both MySQL (production) and SQLite (tests) — no MySQL-only syntax |
Member
There was a problem hiding this comment.
Now that Docker support has gotten pretty good, I don't know if sqlite support is strictly necessary, tbh.
Collaborator
Author
There was a problem hiding this comment.
Is that also true locally? I like the simpler approach where possible, but would be nice indeed to split that into a separate PR.
Member
There was a problem hiding this comment.
Yeah docker is just for local, so docker compose would be the best way to get production-like env locally now.
Comment on lines
+199
to
+204
| Note: montage-beta originally used SQLite and the file (`tmp_montage.db`) may still exist alongside the MariaDB setup. It is no longer used by the running service once the config switches to `mysql+pymysql://`. | ||
|
|
||
| There is no `sqlite3` CLI on Toolforge. Use Python instead: | ||
|
|
||
| ```bash | ||
| python3 -c 'import sqlite3; c=sqlite3.connect("/data/project/montage-beta/www/python/src/tmp_montage.db"); print(c.execute("SELECT COUNT(*) FROM entries").fetchone())' |
Member
There was a problem hiding this comment.
if we don't need sqlite, we won't need this caveat :)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
/data/project/<project>/logs/across all three environments (verified on montage-dev, montage-beta, montage-prod)mkdirstep for log directory in from-scratch deployment instructions/complete_logindirectly; the login button triggers OAuth which doesn't work locallyrdb.py#L113link with stable reference toMAINTAINERSconstant🤖 Generated with Claude Code