shared-sites

Shared content across keyman.com sites and centralized management of website launch and configuration.

Centralized management of keyman.com sites

The local build.sh script allows you to clone, build, start, stop, and test all keyman.com sites with a single command.

The repositories are assumed to be in subfolders of the parent folder for this repo, for example, the following folder layout is suggested:

/.../projects/keyman/
  sites/
    api.keyman.com/
    keyman.com/
    ...
    shared-sites/
    website-local-proxy/

To see the full list of commands and repositories, run:

./build.sh --help

Some common commands are:

./build.sh clone      # Clone websites from GitHub into subfolders of parent folder
./build.sh pull       # Switch to master and pull latest changes to websites, DELETES MERGED BRANCHES
./build.sh configure  # Configure websites
./build.sh clean      # Clean websites
./build.sh build      # Build docker images
./build.sh start      # Start Docker containers
./build.sh stop       # Stop Docker containers
./build.sh test       # Test websites

These commands can be combined, e.g.

./build.sh configure,build,start,test

And can be limited to specific repos, e.g.:

./build.sh build,start:keyman.com,keymanweb.com

Shared content

_common/

All shared server-side scripts should be placed in this folder.

The files in this folder and its subfolders are downloaded by build.sh on keyman.com sites into the /_common folder on the site.

The /_common/assets folder is a clone of the top-level /assets folder with corresponding hashed filenames for cache-busting purposes. Do not modify this folder directly (see build.sh for details).

Do not refer to files in the /_common/assets folder directly. Instead, use the PHP Assets class (/_common/Assets.php) to refer to the files.

assets/

The files on this folder are the source files for client-side content -- images, scripts, stylesheets, and the like. /_common/assets.

bootstrap.inc.sh

This script is downloaded from the GitHub repo by the build.sh script keyman.com sites under the /resource folder. It is not run on this site.

.bootstrap-registry

This file is automatically generated by build.sh. Any changes to it should be committed.

This file is used by keyman.com sites, both when downloading shared files (from the build.sh bootstrapping), and in the Assets class (/_common/Assets.php) to reference client-side assets.

Infrastructure files

build.sh

This script must be run whenever changes are made to files shared to keyman.com sites. It rebuilds the /_common/assets folder and creates the .bootstrap-registry file.

This script is not the same as the build.sh script on keyman.com sites.

The command to run is:

./build.sh build-files

Distribution of changes

Preparing changes

1. Asset files should be placed in /assets. PHP scripts should be placed in /_common. (Do not make changes in /_common/assets, as these files will be repopulated by build.sh.)
2. Run build.sh after changing any files under /_common or /assets, in order to rebuild .bootstrap-registry and repopulate /_common/assets.
3. Commit all changes to the repository, including the generated files in /_common/assets.

Testing changes

1. Open a pull request on a new branch. In build.sh on a keyman.com site, create a new branch, and locate the BOOTSTRAP_VERSION line in build.sh. Set this to the name of the new branch, e.g.

   readonly BOOTSTRAP_VERSION=chore/move-sentry-js-to-common

2. With this change in place, you can test the changes locally by deleting resources/.bootstrap-version on the site, and running:

   ./build.sh stop start

   This will download and rebuild the bootstrapped files.

Deployment

1. Finally, once the PR on shared-sites is approved and merged, the changes on the main branch will need to be tagged with a release, e.g. v0.17, and the keyman.com site BOOTSTRAP_VERSION references should be updated to refer to the new tag instead of the PR branch. Then each site that needs the changes will need a PR with the updated BOOTSTRAP_VERSION, e.g.

   readonly BOOTSTRAP_VERSION=v0.17

Important

Make sure you don't merge a PR on a keyman.com site that points to a branch rather than a tag. Once the branch goes away, subsequent deployments will fail.