diff --git a/README.md b/README.md index 582782b19..5bd0ec156 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,16 @@ -# Development +# help.keyman.com + +This is the source for the website https://help.keyman.com/. This site runs on +Apache in a Docker container. ## Documentation sources Many of the pages on this site are deployed from other repositories and should be edited in the source repository rather than here: -* From https://github.com/keymanapp/keyboards: - * /keyboard -* From https://github.com/keymanapp/keyman (see [resources/build/help-keyman-com.sh](https://github.com/keymanapp/keyman/blob/master/resources/build/help-keyman-com.sh)): +* From https://github.com/keymanapp/keyboards (deployed when PRs are merged): + * /keyboard/ +* From https://github.com/keymanapp/keyman (see [resources/build/help-keyman-com.sh]): * /products/android/ * /products/iphone-and-ipad/ * /products/linux/ @@ -20,43 +23,101 @@ be edited in the source repository rather than here: * /developer/engine/windows/ * /developer/core/ -## How to run help.keyman.com locally with Apache on Docker +## Other Keyman websites -Previously, the site was run in IIS, but is now migrated to Apache. The Docker image is configured to host the site that can be accessed at http://localhost:8055. +* **[api.keyman.com]** - database backend for Keyman websites +* **[help.keyman.com]** - documentation home for Keyman +* **[keyman.com]** - Keyman home +* **[keymanweb.com]** - KeymanWeb online keyboard +* **[s.keyman.com]** - static Javascript, font, and related resources +* **[website-local-proxy]** - run all Keyman sites on localhost on the same port -If you have [website-local-proxy](https://github.com/keymanapp/website-local-proxy) running, the help site is available at -http://help.keyman.com.localhost. +## How to run help.keyman.com locally -### Pre-requisites +When run locally, this site can be accessed at http://localhost:8055 or +http://help.keyman.com.localhost:8055. -#### All host machines +**Recommended:** Use [website-local-proxy] to run multiple keyman.com sites +all from the same port (default port 80). -The host machine needs the following: -* [Git](https://git-scm.com/downloads) -* Bash (on Windows, you can use Git Bash that comes with [Git](https://git-scm.com/download/win)) -* [Docker Desktop](https://docs.docker.com/get-docker/) +**Recommended:** Use [shared-sites] to control startup and shutdown of all +keyman.com sites together. -#### Additional steps -On Windows host machines, do one of these two options: -* [Enable Hyper-V on Windows 11](https://techcommunity.microsoft.com/t5/educator-developer-blog/step-by-step-enabling-hyper-v-for-use-on-windows-11/ba-p/3745905) -* [WSL2](https://ubuntu.com/tutorials/install-ubuntu-on-wsl2-on-windows-10#1-overview) +### Prerequisites -### Builder actions +The host machine needs the following apps installed: +* [Git] +* Bash 5.x (on Windows, you can use Git Bash that comes with [Git]) +* [Docker Desktop] -#### Stop the Docker container -1. Run `./build.sh stop` +
+ Configuration of Docker on Windows + + On Windows machines, you can setup Docker in two different ways, either of + which should work: + * [Enable Hyper-V on Windows 11](https://techcommunity.microsoft.com/t5/educator-developer-blog/step-by-step-enabling-hyper-v-for-use-on-windows-11/ba-p/3745905) + * [WSL2](https://ubuntu.com/tutorials/install-ubuntu-on-wsl2-on-windows-10#1-overview) + +
+ +### Actions #### Build the Docker image -1. Run `./build.sh build`. + +The first time you want to start up the site, or if there have been Docker +configuration changes, you will need to rebuild the Docker images. Start a bash +shell, and from this folder, run: + +```sh +./build.sh build +``` #### Start the Docker container -1. Run `./build.sh start --debug`. -After this, you can access the help.keyman site at http://localhost:8055 +To start up the website, in bash, run: + +```sh +./build.sh start --debug +``` + +Once the container starts, you can access the help.keyman.com site at +http://localhost:8055 or http://help.keyman.com.localhost:8055 + +#### Stop the Docker container + +In bash, run: + +```sh +./build.sh stop +``` #### Remove the Docker container and image -1. Run `./build.sh clean`. + +In bash, run: + +```sh +./build.sh clean +``` #### Running tests -Checks for broken links -1. Run `./build.sh test` + +To check for broken links and .php file conformance, when the site is running, +in bash, run: + +```sh +./build.sh test +``` + +[resources/build/help-keyman-com.sh]: https://github.com/keymanapp/keyman/blob/master/resources/build/help-keyman-com.sh +[Git]: https://git-scm.com/downloads +[Docker Desktop]: https://docs.docker.com/get-docker/ +[shared sites]: https://github.com/keymanapp/shared-sites +[api.keyman.com]: https://github.com/keymanapp/api.keyman.com +[help.keyman.com]: https://github.com/keymanapp/help.keyman.com +[keyman.com]: https://github.com/keymanapp/keyman.com +[keymanweb.com]: https://github.com/keymanapp/keymanweb.com +[s.keyman.com]: https://github.com/keymanapp/s.keyman.com +[website-local-proxy]: https://github.com/keymanapp/website-local-proxy +[shared-sites]: https://github.com/keymanapp/shared-sites +[enable Hyper-V]: https://techcommunity.microsoft.com/t5/educator-developer-blog/step-by-step-enabling-hyper-v-for-use-on-windows-11/ba-p/3745905 +[enable WSL2]: https://ubuntu.com/tutorials/install-ubuntu-on-wsl2-on-windows-10#1-overview diff --git a/_includes/includes/head.php b/_includes/includes/head.php index b49dadd0f..e401e8a73 100644 --- a/_includes/includes/head.php +++ b/_includes/includes/head.php @@ -58,7 +58,9 @@