Skip to content

Latest commit

 

History

History
143 lines (106 loc) · 5.85 KB

README.md

File metadata and controls

143 lines (106 loc) · 5.85 KB

How to Set Up a Local Web Server for the Keyman Web Pages

Currently, most of the Keyman websites (*.keyman.com, *.keyman-staging.com) are running PHP 7.4 via Apache.

Pre-requisite Installs

On Windows, Docker will need either:

Other Docker Notes

Docker tends to throttle Docker image downloads, so some developer offices may want to set up a proxy server. If the proxy server is set up, carefully edit the JSON file per in Docker Settings -> Docker Engine https://docs.docker.com/registry/recipes/mirror/#configure-the-docker-daemon and click 'Apply & Restart'. Note the example (lingnet) is for running inside the Linguistics Institute (Chiang Mai)

 "registry-mirrors": ["https://docker.io.registry.lingnet/"],
  "insecure-registries" : [
    "docker.io.registry.lingnet",
    "registry.lingnet"
  ]

Using Website-Local-Proxy

Rather than remembering localhost port values below, you can clone and run website-local-proxy.

Refer to the port lookup table to access the local websites at http://*keyman.com.localhost

Builder BASH Script Actions

Stop the Docker container

  1. Run ./build.sh stop

This stops the Docker container for the site.

Build the Docker image

  1. Run ./build.sh build

This downloads and builds the Docker images needed for the site.

Configure

  1. Run ./build.sh configure

This step typically downloads _common/ website files from shared-sites.

Start the Docker container

  1. Run ./build.sh start --debug

This maps the local directory to the the Docker image.

The --debug flag will, among other things:

  • Skip generation of CDN assets (so changes appear without a rebuild) (Some sites have assets in /cdn/dev/ used to generate CDN in /dev/deploy/.)
  • Cause any PHP errors to be displayed to the user (rather than logging them back-end)

For sites that use Composer dependencies, this step also creates a link in the Docker image from /var/www/vendor/ to /var/www/html/vendor. The link file also appears locally.

Port lookup table

After this, you can access the website at the following ports:

Website URL with website-local-proxy running Docker Container Name
keyman.com http://localhost:8053 http://keyman.com.localhost keyman-website
s.keyman.com http://localhost:8054 http://s.keyman.com.localhost s-keyman-website
help.keyman http://localhost:8055 http://help.keyman.com.localhost help-keyman-website
keymanweb.com http://localhost:8057 http://keymanweb.com.localhost web-keyman-website
http://web.keyman.com.localhost
api.keyman.com http://localhost:8058 http://api.keyman.com.localhost api-keyman-com-website

Remove the Docker container and image

  1. Run ./build.sh clean.

Running tests

You might need to install the broken-link-checker first

npm install broken-link-checker

Checks for broken links

  1. Run ./build.sh test

Troubleshooting Errors

You can access PHP errors with

docker logs -f {Docker Container Name}

Refer to Port lookup table above for Docker container names

Kubernetes Deployment

For production, the websites are deployed with Kubernetes.

Note: the following section is outdated as it's replaced with Rancher/Fleet.

How to run help.keyman.com locally with Docker Desktop's Kubernetes singlenode cluster

For testing Kubernetes deployment, there are yaml files under the corresponding website's repo: /resources/kubectl, that cover local developer testing.

Pre-requisites

On the host machine, install Docker, then enable Kubernetes in the settings. Ensure you have built a help-keyman-app Docker image, and either tag it docker.dallas.languagetechnology.org/keyman/help-keyman-app or modify the app-php containers image: value to match you local copy's name.

Deploying to a desktop cluster

To deploy the dev version to the cluster do the following:

  1. Ensure your kubectl context is set to docker-desktop, though the Docker Desktop systray icon or by running:
$> kubectl config use-context docker-desktop
  1. Create a keyman namespace if it does not already exist:
$> kubectl create ns keyman
  1. Apply the configs for the resources and start the pod:
$> kubectl --namespace keyman apply \
       -f resources/kubectl/help-kubectl-dev.yaml \
       -f resources/kubectl/help-kubectl.yaml

Testing the site and /api/deploy webhook endpoint

The site can be reached on http://localhost:30080/ via web browser, and the deploy api is on http://localhost:30900/api/deploy, and can be activated like so:

$> curl -v --request POST \
    -H "Content-Type: application/json" \
    -H "X-Hub-Signature-256: sha256=49af8531106a369bfee369f91dadec597e8ea3992ec2802bbe655be0ece17f15" \
    --data '{"action":"push","ref":"refs/heads/staging"}' \
    http://localhost:30900/api/deploy

This simulates enough of a GitHub webhook push event to pass validation on the responder.

Clean up after testing

To remove the k8s pod and resources, and delete everything do:

$> kubectl --namespace=keyman delete {pod,cm,svc,secret,pvc}/help-keyman-com

Or just delete the pod and keep the resources for further testing:

$> kubectl --namespace=keyman delete pod/help-keyman-com