Update READMEs and User Guide (#4297)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: imnasnainaec

README.md

@@ -128,7 +128,7 @@ A rapid word collection tool. See the [User Guide](https://sillsdev.github.io/Th
      - If manually installing from the FFmpeg website, install both `ffmpeg` and `ffprobe`
 
 9. [dotnet-reportgenerator](https://github.com/danielpalme/ReportGenerator)
-   `dotnet tool update --global dotnet-reportgenerator-globaltool --version 5.0.4`
+   `dotnet tool update --global dotnet-reportgenerator-globaltool`
 10. [nuget-license](https://github.com/sensslen/nuget-license) `dotnet tool update --global nuget-license`
 11. Tools for generating the self installer (Linux only):
     - [makeself](https://makeself.io/) - a tool to make self-extracting archives in Unix
@@ -156,6 +156,8 @@ A rapid word collection tool. See the [User Guide](https://sillsdev.github.io/Th
 
 2. Run `npm start` from the project directory to install dependencies and start the project.
 
+   > Note: To install frontend dependencies separately, use `npm run i` — not `npm install` or `npm i`.
+
 3. Consult our [C#](docs/style_guide/c_sharp_style_guide.md) and [TypeScript](docs/style_guide/ts_style_guide.md) style
    guides for best coding practices in this project.
 
@@ -278,8 +280,8 @@ In the project directory, you can run:
 
 #### `npm start`
 
-> Note: To avoid browser tabs from being opened automatically every time the frontend is launched, set
-> [`BROWSER=none`](https://create-react-app.dev/docs/advanced-configuration/) environment variable.
+> Note: To avoid browser tabs from being opened automatically every time the frontend is launched, set the
+> `BROWSER=none` environment variable (Parcel's `--open` flag controls browser opening).
 
 Installs the necessary packages and runs the app in the development mode.
 
@@ -307,7 +309,7 @@ The build is minified and the filenames include the hashes.
 
 Your app is ready to be deployed!
 
-See the section about [deployment](https://facebook.github.io/create-react-app/docs/deployment) for more information.
+The project uses Parcel and outputs to the `dist/` folder.
 
 #### `npm run build:analyze`
 
@@ -326,7 +328,7 @@ First, you must install the Java Runtime Environment (JRE) 8 or newer as mention
 
 - For Windows: Install [OpenJDK](https://www.microsoft.com/openjdk)
 - For Ubuntu: `sudo apt install default-jre`
-- For macOS: `brew install adoptopenjdk`
+- For macOS: `brew install --cask temurin`
 
 After that, run the following script in your Python virtual environment to regenerate the frontend OpenAPI bindings in
 place:
@@ -355,8 +357,7 @@ npm run test-backend -- --filter FullyQualifiedName~Backend.Tests.Models.Project
 
 #### `npm run test-frontend`
 
-Launches the test runners in the interactive watch mode. See the section about
-[running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information.
+Launches the test runners in the interactive watch mode. Tests run via Jest (`scripts/jestTest.js`).
 
 To run a subset of tests, pass in the name of a partial file path to filter:
 
@@ -485,8 +486,8 @@ The dictionary files for spell-check functionality in _The Combine_ are split in
 sake of devices with limited bandwidth. There are scripts for generating these files in `public/dictionaries/` and
 `src/resources/dictionaries/`; files in this directory should _not_ be manually edited.
 
-The bash script `scripts/fetch_wordlists.sh` is used to fetch dictionary files for a given language (e.g., `es`) from
-the [LibreOffice dictionaries](https://github.com/LibreOffice/dictionaries) and convert them to raw wordlists (e.g.,
+The bash script `scripts/fetch_wordlist.sh` is used to fetch dictionary files for a given language (e.g., `es`) from the
+[LibreOffice dictionaries](https://github.com/LibreOffice/dictionaries) and convert them to raw wordlists (e.g.,
 `src/resources/dictionaries/es.txt`). Execute the script with no arguments for its usage details. Any language not
 currently supported can be manually added as a case in this script.
 
@@ -931,7 +932,7 @@ Combine_ is set up as five deployments:
 - backend
 - database
 - maintenance
-- otel/opentelemetry-collector
+- otel-opentelemetry-collector
 
 Each deployment definition is used to create a _pod_ that runs the docker image.
 
@@ -944,7 +945,7 @@ database                          1/1     1            1           3h41m
 maintenance                       1/1     1            1           3h41m
 backend                           1/1     1            1           3h41m
 frontend                          1/1     1            1           3h41m
-otel/opentelemetry-collector      1/1     1            1           3h46m
+otel-opentelemetry-collector      1/1     1            1           3h46m
 ```
 
 Similarly, you can view the state of the pods:
@@ -957,7 +958,7 @@ install-fonts-fvrb4                                 0/1     Completed   0
 maintenance-85644b9c76-55pz8                        1/1     Running     0               130m
 backend-69b77c46c5-8dqlv                            1/1     Running     0               130m
 frontend-c94c5747c-pz6cc                            1/1     Running     0               60m
-otel/opentelemetry-collector-5cd6b9c867-6j5zb       1/1     Running     0               4h03m
+otel-opentelemetry-collector-5cd6b9c867-6j5zb       1/1     Running     0               4h03m
 ```
 
 Use the `logs` command to view the log file of a pod; you can specify the pod name listed in the output of the

docs/deploy/README.md

@@ -77,6 +77,18 @@ The host tools required to install _The Combine_ on a QA or Production server ar
 [Install Kubernetes Tools](https://github.com/sillsdev/TheCombine#install-kubernetes-tools) in the project README.md
 file.
 
+The table below summarizes the key differences between the QA and Production deployments.
+
+| Aspect                    | QA                                    | Production                                               |
+| ------------------------- | ------------------------------------- | -------------------------------------------------------- |
+| Kubernetes cluster        | `LTOPS_K8S_STAGING_CONTEXT`           | `LTOPS_K8S_PRODUCTION_CONTEXT`                           |
+| Server name               | `qa-kube.thecombine.app`              | `thecombine.app`                                         |
+| Image registry            | Private ECR, with IAM refresh CronJob | Public ECR (`public.ecr.aws/thecombine`), no pull secret |
+| `aws-login` subchart      | Enabled                               | Disabled                                                 |
+| `cert-proxy-server` chart | Not deployed                          | Deployed in `combine-cert-proxy` namespace               |
+| Backup CronJob            | Not scheduled                         | Daily                                                    |
+| Font-update CronJob       | Not scheduled                         | Weekly                                                   |
+
 #### Steps to Install on a QA/Production Server
 
 To install _The Combine_ on one of these systems, follow the steps in
@@ -250,7 +262,7 @@ The `setup_target.py` script will do the following:
 - Copy your SSH public key to the NUC
 
 Note that if an SSH key exists, you will have the option to overwrite it or skip the key generation. When your SSH key
-is copied to the NUC, it will copy the default key, `${HOME}/.ssh/id_rsa.pub`.
+is copied to the NUC, `ssh-copy-id` is used to copy the default SSH public key.
 
 ## Install Kubernetes Engine on Target
 
@@ -409,10 +421,9 @@ Notes:
 - When the `./setup_combine.py` script is used to install _The Combine_ on a NUC, it will install the fonts required for
   Arabic, English, French, Portuguese, and Spanish. If additional fonts will be required, call the `setup_combine.py`
   commands with the `--langs` option. Use the `--help` option to see the argument syntax.
-- The database image contains a script that will initialize the `SemanticDomains` and the `SemanticDomainTree`
-  collections on _first use_ of the database. The script will not be run automatically when the database is restarted or
-  updated. If the Semantic Domain data are updated, for example, adding a new language, then the script needs to be
-  rerun manually:
+- The database pod has a `postStart` lifecycle hook that runs `update-semantic-domains.sh` automatically on every pod
+  start, but only imports data if the `SemanticDomainTree` or `SemanticDomains` collections are empty. If the Semantic
+  Domain data are updated, for example, adding a new language, then the script needs to be rerun manually:
 
   ```console
   kubectl -n thecombine exec deployment/database -- /opt/thecombine/update-semantic-domains.sh
@@ -461,19 +472,19 @@ Notes:
 
 ### Checking Certificate Expiration
 
-The `check_cert.py` will print the expiration timestamp for _The Combine's_ TLS certificate.
+The `check_certs.py` will print the expiration timestamp for _The Combine's_ TLS certificate.
 
 If using the Docker image, [open the Docker image terminal](#open-docker-image-terminal) and run:
 
 ```console
-python3 ~/scripts/check_cert.py -n thecombine
+python3 ~/scripts/check_certs.py -n thecombine
 ```
 
 If using local tools, open a terminal window and run:
 
 ```console
 cd <COMBINE>/deploy/scripts
-./check_cert.py -n thecombine
+./check_certs.py -n thecombine
 ```
 
 The `-n thecombine` option may be omitted if the default namespace for the kubeconfig file has been set to `thecombine`

docs/deploy/kubernetes_design/README.md

@@ -46,11 +46,11 @@ repository.
 
 #### Additional Backend Resources
 
-| Resource           | Kind                  | Description                                                                                                                                                                   |
-| ------------------ | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| env-backend        | ConfigMap             | `env-backend` defines the runtime configuration for backend services.                                                                                                         |
-| env-backend-secret | Secret                | `env-backend-secret` defines the sensitive runtime configuration items for the backend services                                                                               |
-| backend-data       | PersistentVolumeClaim | `backend-data` defines the persistent storage requirements for the backend services. The persistent storage is used for the backend files stored in `/home/app/.CombineFiles` |
+| Resource            | Kind                  | Description                                                                                                                                                                   |
+| ------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| env-backend         | ConfigMap             | `env-backend` defines the runtime configuration for backend services.                                                                                                         |
+| env-backend-secrets | Secret                | `env-backend-secrets` defines the sensitive runtime configuration items for the backend services                                                                              |
+| backend-data        | PersistentVolumeClaim | `backend-data` defines the persistent storage requirements for the backend services. The persistent storage is used for the backend files stored in `/home/app/.CombineFiles` |
 
 ### Database Deployment
 
@@ -81,8 +81,8 @@ backup/restore _The Combine_ data, remove projects, add a user to a project, and
 #### `combine_maint` Image
 
 The `combine_maint` container image is stored in AWS ECR. It provides a number of utility and administrative functions
-and is used in multiple scenarios. `combine_maint` is built off of `sillsdev/aws-kubectl` and has the following
-features:
+and is used in multiple scenarios. `combine_maint` is built off of `public.ecr.aws/thecombine/aws-kubectl` and has the
+following features:
 
 - _aws-cli ver. 2_ - version 2 of the AWS Command Line Interface (from `sillsdev/aws-kubectl`)
 - _kubectl_ - a command line tool used by maintenance scripts to manage Kubernetes resources (from
@@ -100,6 +100,8 @@ features:
   - `update_cert.py` - a script to be used by the cert proxy clients on the NUCs. `update_cert.py` will update a TLS
     certificate if the NUC is connected to the internet and if the certificate is ready for renewal. If these conditions
     are met, it will update the certificate from AWS S3 storage.
+  - `get_fonts.py` - generates font support data for SIL fonts used in the language picker. Runs weekly via the
+    `update-fonts` CronJob.
 
 ### Daily Backup CronJob
 
@@ -157,7 +159,7 @@ server. To solve this problem, there are two additional functions that are added
   will generate the TLS Secrets for each of the configured NUCs and then push the secrets to an AWS S3 bucket where they
   can be retrieved by the NUCs
 - _Cert Proxy Client_ runs on each NUC in the `thecombine` namespace. Like the _AWS Login_, there is a one-time job,
-  `update-cert-oneshot`, and a cron job, `update-cert-cron` that keep the TLS secret up to date when the NUC has
+  `update-cert-oneshot`, and a cron job, `update-cert-cronjob` that keep the TLS secret up to date when the NUC has
   internet access.
 
 ### Cert Proxy Server
@@ -194,13 +196,13 @@ The design of the _Cert Proxy Client_ is shown in the following diagram:
 
 The _Cert Proxy Client_ uses the following resources to update the NUCs SSL Certificate from AWS S3 storage:
 
-| Resource                | Kind      | Description                                                                                                                                                                                                                                                     |
-| ----------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| update-cert-oneshot     | Job       | A one-time job to create/update the TLS secret when the Cluster is created or updated. The job uses the `combine_maint` image and runs the `update_cert.py` script. (see the [combine_maint Image](#combine_maint-image) section)                               |
-| update-cert-cron        | CronJob   | Performs the same task as `update-cert-oneshot` on a regular schedule.                                                                                                                                                                                          |
-| env-cert-proxy          | ConfigMap | `env-cert-proxy` defines the configuration environment variables for the `update-cert-oneshot` and `update-cert-cron`. They include the location of the AWS S3 bucket where the certificates are stored as well as details about the certificate to be checked. |
-| aws-s3-credentials      | Secret    | `aws-s3-credentials` defines the access accounts and credentials to access the configures AWS S3 resources.                                                                                                                                                     |
-| nuc1-thecombine-app-tls | Secret    | `nuc1-thecombine-app-tls` is a `kubernetes.io/tls` secret that is created by `update-cert-oneshot` and `update-cert-cron` from the data stored in the AWS S3 bucket.                                                                                            |
+| Resource                | Kind      | Description                                                                                                                                                                                                                                                        |
+| ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| update-cert-oneshot     | Job       | A one-time job to create/update the TLS secret when the Cluster is created or updated. The job uses the `combine_maint` image and runs the `update_cert.py` script. (see the [combine_maint Image](#combine_maint-image) section)                                  |
+| update-cert-cronjob     | CronJob   | Performs the same task as `update-cert-oneshot` on a regular schedule.                                                                                                                                                                                             |
+| env-cert-proxy          | ConfigMap | `env-cert-proxy` defines the configuration environment variables for the `update-cert-oneshot` and `update-cert-cronjob`. They include the location of the AWS S3 bucket where the certificates are stored as well as details about the certificate to be checked. |
+| aws-s3-credentials      | Secret    | `aws-s3-credentials` defines the access accounts and credentials to access the configures AWS S3 resources.                                                                                                                                                        |
+| nuc1-thecombine-app-tls | Secret    | `nuc1-thecombine-app-tls` is a `kubernetes.io/tls` secret that is created by `update-cert-oneshot` and `update-cert-cronjob` from the data stored in the AWS S3 bucket.                                                                                            |
 
 ## Service Accounts
 
@@ -212,18 +214,16 @@ listed here use the default service account for the namespace where they run.
 The `account-ecr-login` account is used by the `ecr-cred-helper` and `ecr-cred-helper-cron` resources. The
 `account-ecr-login` has the following access to Kubernetes resources:
 
-| Resources                             | Abilities                                       |
-| ------------------------------------- | ----------------------------------------------- |
-| pods, pods/attach                     | list, get, watch, create, update, patch         |
-| secrets, jobs, cronjobs, namespaces\* | list, get, watch, create, update, patch, delete |
-| serviceaccounts                       | list, get, update, patch                        |
-
-[*] - abilities to access `namespaces` are not allowed on the Production server.
+| Resources               | Abilities                                       |
+| ----------------------- | ----------------------------------------------- |
+| pods, pods/attach       | list, get, watch, create, update, patch         |
+| secrets, jobs, cronjobs | list, get, watch, create, update, patch, delete |
+| serviceaccounts         | list, get, update, patch                        |
 
 ### Service Account: `account-maintenance`
 
 The `account-maintenance` account is used by the `maintenance`, `daily-backup`, `update-cert-oneshot`,
-`update-cert-cron` resources. The `account-maintenance` has the following access to Kubernetes resources:
+`update-cert-cronjob` resources. The `account-maintenance` has the following access to Kubernetes resources:
 
 | Resource        | Permissions                                     |
 | --------------- | ----------------------------------------------- |