Docs/local setup instructions by RonaldRonnie · Pull Request #306 · waldronlab/BugSigDB

RonaldRonnie · 2025-12-12T17:22:59Z

Add docs/LOCAL_SETUP.md with step-by-step instructions for running BugSigDB locally
Update README.md to reference the new local setup documentation
Configure compose.yml for local setup without Traefik:
- Add port mapping to varnish service (localhost:8081)
- Comment out network sections for local development
- Make MW_SITE_SERVER configurable via environment variable
- Add MW_DB_INSTALLDB_PASS for database initialization
- Update MW_ADMIN_PASS to use environment variable
Document troubleshooting steps for common setup issues
Include instructions for both empty database and production backup scenarios
Add notes about required environment variables (MW_ADMIN_PASS, MW_DB_INSTALLDB_PASS)

This addresses issue #261 by providing comprehensive documentation for local setup."

- Add comprehensive LOCAL_SETUP.md guide covering: - Setup with and without Traefik - Database initialization with and without backups - Secrets configuration - Common troubleshooting issues (Semantic MediaWiki maintenance screen, missing images, etc.) - Instructions for updating images from Google Cloud Storage - Common maintenance tasks and commands - Update README.md to reference the new local setup documentation This addresses issue #261 by documenting the complete process for running BugSigDB locally, including all troubleshooting steps discovered during testing.

… for local development - Add docs/LOCAL_SETUP.md with step-by-step instructions for running BugSigDB locally - Update README.md to reference the new local setup documentation - Configure compose.yml for local setup without Traefik: - Add port mapping to varnish service (localhost:8081) - Comment out network sections for local development - Make MW_SITE_SERVER configurable via environment variable - Add MW_DB_INSTALLDB_PASS for database initialization - Update MW_ADMIN_PASS to use environment variable - Document troubleshooting steps for common setup issues - Include instructions for both empty database and production backup scenarios - Add notes about required environment variables (MW_ADMIN_PASS, MW_DB_INSTALLDB_PASS) This addresses issue #261 by providing comprehensive documentation for local setup.

RonaldRonnie · 2025-12-12T17:26:48Z

Hi @jwokaty . This looks to be the final one to be tested

jwokaty · 2025-12-15T21:23:52Z

@RonaldRonnie Can #305 be closed (assuming that one is not needed)?

RonaldRonnie · 2025-12-16T03:42:07Z

Sure @jwokaty. We can close #305

…

On Tue, 16 Dec 2025 at 12:24 AM, jwokaty ***@***.***> wrote: *jwokaty* left a comment (waldronlab/BugSigDB#306) <#306 (comment)> @RonaldRonnie <https://github.com/RonaldRonnie> Can #305 <#305> be closed (assuming that one is not needed)? — Reply to this email directly, view it on GitHub <#306 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BBVREPY2LYY3EGG4XH3FMPL4B4RH3AVCNFSM6AAAAACO36DYVCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTMNJXGY3DSMRQGI> . You are receiving this because you were mentioned.Message ID: ***@***.***>

jwokaty

@RonaldRonnie Thanks for your PR. It's very thorough, which I like in documentation.
Please see the inline comments. I've also tried to include the ones made by Ike (tosfos) on the old PR.

I agree with Ike that it would be better to make a local compose to override settings rather than edit the compose.yaml (as mistakes happen). This should change your instructions but greatly simplify them for the end user. Similarly, it might be helpful to also have a corresponding local env.

compose.yml

docs/LOCAL_SETUP.md

…g compose.yml - Create compose.local.yml for local development without Traefik - Update documentation to use docker compose -f compose.yml -f compose.local.yml - Move Secrets Configuration section before first docker compose up - Remove DNS record configuration step (not needed for localtest.me) - Update all docker compose commands to specify local vs Traefik setup - Clarify that MW_DB_INSTALLDB_PASS is already configured in compose.yml

RonaldRonnie · 2025-12-20T18:17:18Z

Hi @jwokaty @tosfos . Been able to update the PR. Could you please make a review of it again

jwokaty · 2025-12-22T19:49:05Z

Thanks @RonaldRonnie. I need to follow the instructions to finish the review. I will try to finish this week.

RonaldRonnie · 2025-12-27T18:38:02Z

Thank you
I am available for any changes needed

compose.yml

DanielWTQ · 2026-01-01T01:16:05Z

compose.yml

-        networks:
-            - default
-            - traefik-public
+        #networks:


please leave the network configuration, you can override it in the compose.local.yml file. You can se how I do that for my own personal website setup which also uses traefik at https://github.com/DanielEScherzer/website-content/blob/main/docker-compose.local.yml - adding networks: !reset [] to an individual service will revert the addition of traefik-public, and adding networks: !reset [] to the overall file will remove the dependence on that netwok

DanielWTQ · 2026-01-01T01:16:19Z

compose.yml

+        #    - traefik-public
        depends_on:
            - web
+        ports:


like with the network changes, this should be done via a compose.local.yml override

this port change was added to the compose.local.yml override, but wasn't removed from here

DanielWTQ · 2026-01-01T01:18:09Z

docs/LOCAL_SETUP.md

+   cp database.sql ./__initdb/
+   ```
+
+   **Important:** The database file must be placed in the `__initdb/` directory before running `docker compose -f compose.yml -f compose.local.yml up -d --no-start` (for local setup without Traefik) or `docker compose up -d --no-start` (for setup with Traefik).


for all of the various docker compose commands with -f for multiple files, you may want to instead suggest using https://docs.docker.com/compose/how-tos/environment-variables/envvars/#compose_file to list the files in the .env configuration instead of needing to include them each time in the command line

This would also mean you don't have to give two different commands for the with and without traefik versions

DanielWTQ · 2026-01-01T01:23:19Z

docs/LOCAL_SETUP.md

+docker compose up -d db
+```
+
+# Access the web container (use -f flags if using local setup)


here and for the next few lines the formatting is off, these don't all need to be section headings (e.g. for docker compose exec web bash) and should be code blocks (for the instructions to create a database manually)

docs/LOCAL_SETUP.md

tosfos · 2026-01-01T19:10:23Z

Hi @jwokaty @tosfos . Been able to update the PR. Could you please make a review of it again

The above review is from WikiWorks.

RonaldRonnie · 2026-02-08T13:40:20Z

hhi @jwokaty , apologies for missing this. let me make the necessary updates to it

RonaldRonnie · 2026-02-10T17:08:56Z

hi @jwokaty @tosfos @DanielWTQ can you please take a review of the changes that i have made here

DanielWTQ

looking really good - the compose.yml port issue is something that will conflict with WikiWorks, the other two inline notes are just suggestions

DanielWTQ · 2026-02-11T05:43:50Z

compose.yml

+        #    - traefik-public
        depends_on:
            - web
+        ports:


this port change was added to the compose.local.yml override, but wasn't removed from here

DanielWTQ · 2026-02-11T05:45:51Z

compose.local.yml

+# - Traefik-specific networks are removed for local development
+
+services:
+    varnish:


If the current compose.local.yml works for you, that is great, but I'm surprised that you didn't need to remove the other references to the traefik-public service, e.g.

varnish: networks: !reset [] matomo: networks: !reset []

DanielWTQ · 2026-02-11T05:48:09Z

docs/LOCAL_SETUP.md

+   cd /path/to/bugsigdb.org
+
+   # Create symlink for environment file
+   ln -s .env.localtest.me .env


since .env.localtest.me is not a file that already exists, maybe this should just suggest copying the example env file?

RonaldRonnie · 2026-02-11T06:00:23Z

let fix this @DanielWTQ ASAP

DanielWTQ · 2026-02-11T21:55:41Z

let fix this @DanielWTQ ASAP

Just to confirm, are you asking that I (on behalf of WikiWorks) make the fixing that I suggested? Or are you going to make the fixes and I just review them?

RonaldRonnie added 2 commits December 10, 2025 19:58

RonaldRonnie requested a review from jwokaty December 12, 2025 17:25

jwokaty requested changes Dec 19, 2025

View reviewed changes

compose.yml Show resolved Hide resolved

docs/LOCAL_SETUP.md Outdated Show resolved Hide resolved

docs/LOCAL_SETUP.md Outdated Show resolved Hide resolved

DanielWTQ requested changes Jan 1, 2026

View reviewed changes

Updates to the local setup

e4cf41b

RonaldRonnie requested review from DanielWTQ and jwokaty February 10, 2026 17:07

DanielWTQ requested changes Feb 11, 2026

View reviewed changes

Conversation

RonaldRonnie commented Dec 12, 2025

Uh oh!

RonaldRonnie commented Dec 12, 2025

Uh oh!

jwokaty commented Dec 15, 2025

Uh oh!

RonaldRonnie commented Dec 16, 2025 via email • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jwokaty left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

RonaldRonnie commented Dec 20, 2025

Uh oh!

jwokaty commented Dec 22, 2025

Uh oh!

RonaldRonnie commented Dec 27, 2025

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

tosfos commented Jan 1, 2026

Uh oh!

RonaldRonnie commented Feb 8, 2026

Uh oh!

RonaldRonnie commented Feb 10, 2026

Uh oh!

DanielWTQ left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RonaldRonnie commented Feb 11, 2026

Uh oh!

DanielWTQ commented Feb 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

RonaldRonnie commented Dec 16, 2025 via email •

edited

Loading

jwokaty left a comment •

edited

Loading