Docs/local setup instructions #306

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.

jwokaty · 2025-12-19T16:37:50Z

compose.yml

Let's not edit the compose.yml. As @tosfos suggested #305 (comment), let's make a compose.local.yml to override settings as he suggested.

Maybe this is what we should do: https://docs.docker.com/compose/how-tos/multiple-compose-files/extends/.

This document needs to go back to the original.

Having just set up the wiki again locally for something else, some of the changes in this file are indeed needed (adding MW_DB_INSTALLDB_PASS and fixing MW_ADMIN_PASS) and others are fine (MW_SITE_SERVER), I left notes inline about the changes that will conflict with how WikiTeq uses this repo

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

DanielWTQ · 2026-01-01T01:14:13Z

compose.yml

Having just set up the wiki again locally for something else, some of the changes in this file are indeed needed (adding MW_DB_INSTALLDB_PASS and fixing MW_ADMIN_PASS) and others are fine (MW_SITE_SERVER), I left notes inline about the changes that will conflict with how WikiTeq uses this repo

DanielWTQ · 2026-01-01T01:14:42Z

compose.yml

            - MW_RECAPTCHA_SECRET_KEY=${MW_RECAPTCHA_SECRET_KEY:-}
            - MW_ADMIN_USER=admin
-            - MW_ADMIN_PASSWORD
+            - MW_ADMIN_PASS=${MW_ADMIN_PASS:-anyotherpassword}


good catch, you will also want to update .env.example with the correct name

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

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)

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

docs/LOCAL_SETUP.md

+
+# Start all containers (use compose.local.yml for local setup without Traefik)
+docker compose -f compose.yml -f compose.local.yml up -d
+```


unclear if this is meant to start or end a code block, but it makes the entire networking options section show as a code block

DanielWTQ · 2026-01-01T01:25:58Z

docs/LOCAL_SETUP.md

+
+# Download images directory (this will download to current directory)
+gcloud storage cp --recursive gs://backups.bugsigdb.org/images .
+```


another unmatched ```

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 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

DanielWTQ requested changes Jan 1, 2026

View reviewed changes

Docs/local setup instructions #306

Are you sure you want to change the base?

Docs/local setup instructions #306

Uh oh!

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!

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!

RonaldRonnie commented Dec 20, 2025

Uh oh!

jwokaty commented Dec 22, 2025

Uh oh!

RonaldRonnie commented Dec 27, 2025

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!

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!

tosfos commented Jan 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

RonaldRonnie commented Dec 16, 2025 via email •

edited

Loading

jwokaty left a comment •

edited

Loading