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

docs: Updates README with local run clarifications #797

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
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:

Copy link
Contributor Author

@lorenjohnson lorenjohnson Nov 7, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Ha, I went back and forth on that as well. I concluded that "server" makes sense as the system is implicitly operating in the role of a server when running Docker images, and we use that word in other places in the doc (except in the intro paragraph). This could maybe should be normalised across the doc and I would be equally happy with "system", but wasn't taking that on here.

Copy link
Contributor

Choose a reason for hiding this comment

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

Yeah, good point. I feel I am still missing some clarity in the local/private vs server/public discussion.


* 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

@lorenjohnson lorenjohnson Nov 7, 2024 •
edited
Loading

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 so presumably (according to @tarrow if I got what he said correctly) the requests from server to server fail, 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.

Copy link
Contributor

Choose a reason for hiding this comment

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

I think we could explain that invalid certs are one of the reasons because we talk about them already.

Copy link
Contributor Author

@lorenjohnson lorenjohnson Nov 7, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Really # 2 is the crux though. If you ran a local DNS which the Docker services knew about then theoretically things would be fine, except the certs wouldn't generate correctly through Let's Encrypt as that path requires Internet DNS entries.

Copy link
Contributor

Choose a reason for hiding this comment

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

Couldn't this be fixed with docker network hostname aliases?

Copy link
Contributor Author

@lorenjohnson lorenjohnson Nov 7, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Re. docker names: I getcha, but I don't think so currently as they still won't be accessible by Let's Encrypt and the services access each other through the proxy only.

Again though the attempt here is to document the current state of things and what we know how to support now, as what was there was unclear and causing some confusion for at least a couple users. Not trying to fix or develop anything new.

Looking forward, if the truly local only scenario proves critical, we will need at least to provide guidance for generating local certs (or non-https) without relying on Let's Encrypt.


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