https://github.com/keymanapp/shared-sites
Shared code across keyman.com sites
https://github.com/keymanapp/shared-sites
Last synced: 7 months ago
JSON representation
Shared code across keyman.com sites
- Host: GitHub
- URL: https://github.com/keymanapp/shared-sites
- Owner: keymanapp
- License: mit
- Created: 2023-09-26T09:53:58.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2026-01-18T23:06:08.000Z (7 months ago)
- Last Synced: 2026-01-19T08:43:46.144Z (7 months ago)
- Language: Shell
- Size: 209 KB
- Stars: 0
- Watchers: 4
- Forks: 1
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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:
```sh
./build.sh --help
```
Some common commands are:
```sh
./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.
```sh
./build.sh configure,build,start,test
```
And can be limited to specific repos, e.g.:
```sh
./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`](#buildsh) 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`](#buildsh). 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:
```sh
./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.
```sh
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:
```sh
./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.
```sh
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.