docs: Updates README with local run clarifications #797
Conversation
|
|
||
| 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: |
There was a problem hiding this comment.
| 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: |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Yeah, good point. I feel I am still missing some clarity in the local/private vs server/public discussion.
|
|
||
| However, for testing purposes WBS Deploy can be run locally on a server 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. |
There was a problem hiding this comment.
set
WIKIBASE_PUBLIC_URLandQUICKSTATEMENTS_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?
There was a problem hiding this comment.
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.
|
|
||
| * 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. | ||
| * 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. |
There was a problem hiding this comment.
Why is this? Is the reason here that the certs on WIKIBASE_PUBLIC_HOST are invalid?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
I think we could explain that invalid certs are one of the reasons because we talk about them already.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Couldn't this be fixed with docker network hostname aliases?
There was a problem hiding this comment.
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.
|
Will this be covered in this larger scope docs PR? Let's close it if so. My intention here was simply to make a spot to ground, digest, and continue the various MatterMost threads which were happening on this topic, and I think this change did that well enough. I don't however feel attached to the particulars here beyond it being, hopefully, a helpful record of conclusions we made in making sense of this in MatterMost. |
No description provided.