Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: Updates README with local run clarifications #797

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+10 −6
Open

docs: Updates README with local run clarifications #797

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 10 additions & 6 deletions deploy/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -316,12 +316,6 @@ Alternatively, send `GET` requests with your SPARQL query to the WDQS frontend e

## FAQ

### Can I host WBS Deploy locally?

Yes, WBS Deploy can be hosted locally for testing purposes by using the example domain names `*.example` from `template.env` in your `.env` file. Configure those domains in your host machine's `/etc/hosts` file, so that your browser (on your host machine) resolves `*.example` to `127.0.0.1` and access the local WBS Deploy instance.

However, due to OAuth requirements, QuickStatements may not function properly without publicly accessible domain names for both the `WIKIBASE_PUBLIC_HOST` and `QUICKSTATEMENTS_PUBLIC_HOST`. Also, running locally without publicly accessible addresses will prevent the generation of a valid SSL certificate; to accessing locally running services, you will need to allow the invalid certificate when loading the page for the first time.

### Can I migrate from another Wikibase installation to WBS Deploy?

It is possible to migrate an existing Wikibase installation to WBS Deploy. The general procedure is as follows:
Expand All @@ -333,6 +327,16 @@ It is possible to migrate an existing Wikibase installation to WBS Deploy. The g
- Regenerate the WDQS database
- Regenerate the Elasticsearch database

### Can I host WBS Deploy locally?

Due to the OAuth configuration for MediaWiki and QuickStatements, along with the automatic SSL certification generated by Traefik, you must specify values for `WIKIBASE_PUBLIC_URL` and `QUICKSTATEMENTS_PUBLIC_URL` in your `.env` file. These values should be domain names that route to the IP address of the server hosting these services and must be accessible on the Internet.

However, for testing purposes WBS Deploy can be run locally on a server that is not accessible to the Internet, with the following caveats:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
However, for testing purposes WBS Deploy can be run locally on a server that is not accessible to the Internet, with the following caveats:
However, for testing purposes WBS Deploy can be run locally on a system that is not accessible to the Internet, with the following caveats:


* In this configuration, you will still need to set `WIKIBASE_PUBLIC_URL` and `QUICKSTATEMENTS_PUBLIC_URL` to URLs that resolve locally to the IP address of the machine running the services. Configuring locally resolving DNS entries differs depending on your environment (Linux, MacOS, Windows), so setting this up correctly will require knowledge of or additional research about your specific setup.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

set WIKIBASE_PUBLIC_URL and QUICKSTATEMENTS_PUBLIC_URL

Are you referring to the variables for the quickstatements container? Couldn't the user still just configure WIKIBASE_PUBLIC_HOST and QUICKSTATEMENTS_PUBLIC_HOST in .env?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, the assumption was that these values were being set in the .env not the docker-compose file, but that could be made again explicit here.

* Any SSL certificates generated in this setup will be invalid, though you can optionally bypass the warning about these invalid certificates when first loading the Wikibase site in the browser.
* QuickStatements will not function in this setup, as OAuth will not authorize against a local, non-Internet-accessible Wikibase installation.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is this? Is the reason here that the certs on WIKIBASE_PUBLIC_HOST are invalid?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A couple reasons: 1) yes--certs are invalid, and, 2) the container has to be able to resolve the DNS entry on the host network. I didn't explain these things in more detail here as I think that would be prone to confuse the user more than clarify. The intention here was to make clear what was possible, what we currently support and what we don't.


### My WDQS Updater keeps crashing, what can I do?

Check out the known issue in the [WDQS README](../build/wdqs/README.md#Known-issues). You may find your solution there in the form of a workaround.
Expand Down