kafka-site
kafka-site copied to clipboard
apache
KAFKA-13882 Docker to preview docs locally
I've added a Dockerfile and handy script to run documentation locally with 1 command.
It should reduce friction for docs contribution.
I dont think we can do the same on https://github.com/apache/kafka/ itself, please correct me if I'm wrong
When I run this locally, I can only access pages under Docs, for anything else I get 404.
Is it expected? I would be nice to preview the complete website.
Woops, might be a regression, sorry, let me check, I will move this into draft in the mean time
I agree, it is better to make it work for the whole site
Hi @mimaison sorry for the back and forth, after some fiddling, I realize the problem is that when requesting localhost:8080/path, httpd tries to find a file namedpath, which does not exists, and what we really want is to resolve path to path.html in project root.
I solved this by adding a rewrite rule in .htaccess file, but I don't know how is it solved in the real website deployment, is .htaccess actually used in production?
Hi @mimaison , if you get a chance, can you review this again? I've addressed the issue you pointed out, thanks!
@mjsax The reason I did not merge is because I don't understand why when testing locally we need changes to the .htaccess file that don't seem necessary on the website. See the few comments starting from https://github.com/apache/kafka-site/pull/410#issuecomment-1126118797. Do you have an idea why this may be the case?
I just checkout the PR locally and it worked for me -- did you update your local copy after the latest changes?
Hi @mjsax and @mimaison
After merging with master, I think the change in htaccess is no longer needed, I just tested it. I've removed them
In the meanwhile I redid the same exact same thing here :P https://github.com/lucasbru/kafka-site-docker
@mjsax My point is that when testing locally without the .htaccess changes, all pages other than localhost:8080/documentation/ fail to load. For example http://localhost:8080/quickstart returns a 404.
I see that @qingwei91 removed the .htaccess changes in the last commit and I confirmed the issue happens again. I'm a bit scared of touching the .htaccess file as I don't want to break the real website.
@mimaison , really sorry, I forgotten to check quick start. I've added it back now, guess I need to figure out why that's required here but not in the actual deployment ...
Hi @mimaison , another way I can think of is to avoid using .htaccess in the docker, and inject all config required in httpd.conf instead.
https://github.com/apache/kafka-site/pull/410/commits/4d7397f17d10e64d3fadf4e8722e492bdf131fba
I am not sure if this is better since we now have duplicated config
I also wonder if .htaccess is actually used in the actual deployment, as it requires modifying httpd.conf
Ah sorry. Seems I miss-understood your comment @mimaison. -- I am not an expert in this domain and don't know why we need the change to htaccess nor what the actually impact is... :(
@mimaison are you happy with the latest changes which don't touch the .htaccess? While I think the duplication is not ideal, this change would make it easier docs contributors.
Dropped by to request an update to https://cwiki.apache.org/confluence/display/KAFKA/Setup+Kafka+Website+on+Local+Apache+Server and https://cwiki.apache.org/confluence/display/KAFKA/Contributing+Website+Documentation+Changes (the latter is linked from https://kafka.apache.org/contributing.html ) after this PR is merged.
@tombentley It would have been nice to understand the .htaccess inconsistency but the duplication is minor and this PR really simplifies testing the website so I'm happy to merge it.
@qingwei91 Can you integrate the change Tom suggested?
Hi @mimaison , sure, I've incorporated the change. Would be nice to merge this if everything is ok