[installer] Update docs, comments, pw (#3391)

Dockerfile

@@ -9,9 +9,9 @@
 # User guide build environment
 FROM python:3.12.5-slim-bookworm AS user_guide_builder
 
-ENV PYTHONDONTWRITEBYTECODE 1
-ENV PYTHONUNBUFFERED 1
-ENV PIP_NO_CACHE_DIR 1
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV PIP_NO_CACHE_DIR=1
 
 WORKDIR /app
 
@@ -40,9 +40,9 @@ FROM nginx:1.27
 
 WORKDIR /app
 
-ENV HOST_DIR /usr/share/nginx
-ENV USER_GUIDE_HOST_DIR ${HOST_DIR}/user_guide
-ENV FRONTEND_HOST_DIR ${HOST_DIR}/html
+ENV HOST_DIR=/usr/share/nginx
+ENV USER_GUIDE_HOST_DIR=${HOST_DIR}/user_guide
+ENV FRONTEND_HOST_DIR=${HOST_DIR}/html
 
 RUN mkdir /etc/nginx/templates
 RUN mkdir /etc/nginx/page_templates

README.md

@@ -990,17 +990,6 @@ Notes:
    [AWS CLI Command Reference (s3)](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3/index.html)
    for documentation on how to use the command line to list and to manage the backup objects.
 
-#### Create a New Admin User (Production)
-
-Task: create a new user who is a site administrator
-
-Run:
-
-```bash
-# Run from the `deploy` directory in the project on the host machine
-ansible-playbook playbook_admin_user.yaml --limit <target_name> -u sillsdev -K
-```
-
 #### Delete a Project
 
 Task: Delete a project

deploy/Dockerfile

@@ -23,8 +23,8 @@ RUN curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/s
   ./get_helm.sh && \
   rm kubectl get_helm.sh
 
-ENV HOME /root
-ENV PATH ${PATH}:${HOME}/scripts
+ENV HOME=/root
+ENV PATH=${PATH}:${HOME}/scripts
 
 COPY requirements.txt ${HOME}
 RUN pip3 install -r ${HOME}/requirements.txt

deploy/ansible/group_vars/nuc/main.yml

@@ -1,5 +1,5 @@
 ---
-#################################################
+################################################
 # Group specific configuration items
 #
 # Group: nuc
@@ -27,7 +27,7 @@ k8s_user: sillsdev
 install_ip_viewer: yes
 install_combinectl: yes
 
-#######################################
+################################################
 # Ingress configuration
 ingress_namespace: ingress-nginx
 
@@ -48,10 +48,10 @@ eth_optional: yes
 ################################################
 has_wifi: yes
 ap_domain: thecombine.app
-ap_ssid: "{{ansible_hostname}}_ap"
-ap_passphrase: "Combine2020"
+ap_ssid: "{{ ansible_hostname }}_ap"
+ap_passphrase: "thecombine_pw"
 ap_gateway: "10.10.10.1"
-ap_hostname: "{{ansible_hostname}}"
+ap_hostname: "{{ ansible_hostname }}"
 
 ################################################
 # hardware monitoring settings

deploy/ansible/host_vars/localhost/main.yml

@@ -43,7 +43,7 @@ eth_optional: yes
 has_wifi: yes
 ap_domain: thecombine.app
 ap_ssid: "thecombine_ap"
-ap_passphrase: "Combine2020"
+ap_passphrase: "thecombine_pw"
 ap_gateway: "10.10.10.1"
 ap_hostname: "local"
 test_wifi: false

deploy/scripts/build.py

@@ -28,6 +28,7 @@
 from enum_types import JobStatus
 from sem_dom_import import generate_semantic_domains
 from streamfile import StreamFile
+from utils import init_logging
 
 
 @dataclass(frozen=True)
@@ -91,8 +92,8 @@ def check_jobs(self) -> JobStatus:
         """
         Check if all jobs in the queue have completed.
 
-        If the current job has finished, and there are more jobs to run, it will start the next
-        job.
+        If the current job has finished, and there are more jobs to run,
+        it will start the next job.
         """
         if self.status != JobStatus.RUNNING:
             return self.status
@@ -113,8 +114,7 @@ def check_jobs(self) -> JobStatus:
                 self.status = JobStatus.ERROR
                 return self.status
             self.curr_job = None
-        # start the next job.  If there are no more jobs to run, we have
-        # finished successfully
+        # Start the next job; if there are no more to run, we have finished successfully
         if not self.start_next():
             self.status = JobStatus.SUCCESS
         return self.status
@@ -149,8 +149,7 @@ def no_op() -> None:
     pass
 
 
-# Create a dictionary to look up the build spec from
-# a component name
+# Create a dictionary to look up the build spec from a component name
 build_specs: Dict[str, BuildSpec] = {
     "backend": BuildSpec(project_dir / "Backend", "backend", no_op, no_op),
     "database": BuildSpec(project_dir / "database", "database", build_semantic_domains, no_op),
@@ -223,14 +222,14 @@ def parse_args() -> Namespace:
         action="store_true",
         help="Always attempt to pull a newer version of an image used in the build.",
     )
-    parser.add_argument(
+    logging_group = parser.add_mutually_exclusive_group()
+    logging_group.add_argument(
         "--quiet",
         "-q",
         action="store_true",
         help="Run the docker build commands with '--quiet' instead of '--progress plain'.",
     )
-    group = parser.add_mutually_exclusive_group()
-    group.add_argument(
+    logging_group.add_argument(
         "--debug",
         "-d",
         action="store_true",
@@ -242,16 +241,7 @@ def parse_args() -> Namespace:
 def main() -> None:
     """Build the Docker images for The Combine."""
     args = parse_args()
-
-    # Setup the logging level.  The command output will be printed on stdout/stderr
-    # independent of the logging facility
-    if args.debug:
-        log_level = logging.DEBUG
-    elif args.quiet:
-        log_level = logging.WARNING
-    else:
-        log_level = logging.INFO
-    logging.basicConfig(format="%(levelname)s:%(message)s", level=log_level)
+    init_logging(args)
 
     # Setup required build engine - docker or nerdctl
     container_cli = os.getenv("CONTAINER_CLI", "docker")
@@ -269,6 +259,7 @@ def main() -> None:
     # Setup build options
     if args.quiet:
         build_cmd += ["--quiet"]
+        push_cmd += ["--quiet"]
     else:
         build_cmd += ["--progress", "plain"]
     if args.no_cache:
@@ -296,17 +287,14 @@ def main() -> None:
         logging.debug(f"Adding job {build_cmd + job_opts}")
         job_set[component].add_job(Job(build_cmd + job_opts, spec.dir))
         if args.repo is not None:
-            if args.quiet:
-                push_args = ["--quiet"]
-            else:
-                push_args = []
-            job_set[component].add_job(Job(push_cmd + push_args + [image_name], None))
+            logging.debug(f"Adding job {push_cmd + [image_name]}")
+            job_set[component].add_job(Job(push_cmd + [image_name], None))
         logging.info(f"Building component {component}")
 
     # Run jobs in parallel - one job per component
     build_returncode = 0
     while True:
-        # loop through the running jobs until there is no more work left
+        # Loop through the running jobs until there is no more work left
         running_jobs = False
         for component in job_set:
             if job_set[component].check_jobs() == JobStatus.RUNNING:

deploy/scripts/helm_utils.py

@@ -43,9 +43,9 @@ def create_secrets(
     return secrets_written
 
 
-def get_installed_charts(helm_opts: List[str], helm_namespace: str) -> List[str]:
+def get_installed_charts(helm_cmd: List[str], helm_namespace: str) -> List[str]:
     """Create a list of the helm charts that are already installed on the target."""
-    lookup_results = run_cmd(["helm"] + helm_opts + ["list", "-n", helm_namespace, "-o", "yaml"])
+    lookup_results = run_cmd(helm_cmd + ["list", "-n", helm_namespace, "-o", "yaml"])
     chart_info: List[Dict[str, str]] = yaml.safe_load(lookup_results.stdout)
     chart_list: List[str] = []
     for chart in chart_info:

deploy/scripts/install-combine.sh

@@ -1,19 +1,18 @@
 #! /usr/bin/env bash
 set -eo pipefail
 
-################################################################################
+#########################################################################################
 #
-# install-combine.sh is intended to install the Combine on an Ubuntu-based Linux
-# Laptop.  Its usage is defined in the readme file that accompanies the packaged
-# installer, ./installer/README.md (or ./installer/README.pdf).
+# install-combine.sh is intended to install the Combine on an Ubuntu-based Linux machine.
+# It should only be executed directly by developers. For general users, it is packaged in
+# a stand-alone installer (see ./installer/README.md or ./installer/README.pdf).
 #
-# Note that 2 additional options are available that are not documented in the 
-# readme file.  These are intended to only be used for debugging and under the
-# guidance of a support engineer.  They are:
+# The options for this script and for the packaged installer are the same. Note that 2
+# additional debugging options are available that aren't documented in the readme file:
 #   - single-step - run the next "step" in the installation process and stop.
-#   - start-at <step-name> - start at the step named <step-name> and run to 
-#     completion.
-#################################################################################
+#   - start-at <step-name> - start at the step named <step-name> and run to completion.
+#
+#########################################################################################
 
 # Warning and Error reporting functions
 warning () {
@@ -34,7 +33,7 @@ set-combine-env () {
     # Collect values from user
     read -p "Enter AWS_ACCESS_KEY_ID: " AWS_ACCESS_KEY_ID
     read -p "Enter AWS_SECRET_ACCESS_KEY: " AWS_SECRET_ACCESS_KEY
-    # write collected values and static values to config file
+    # Write collected values and static values to config file
     cat <<.EOF > ${CONFIG_DIR}/env
     export COMBINE_JWT_SECRET_KEY="${COMBINE_JWT_SECRET_KEY}"
     export AWS_DEFAULT_REGION="us-east-1"
@@ -46,8 +45,7 @@ set-combine-env () {
   source ${CONFIG_DIR}/env
 }
 
-# Create the virtual environment needed by the Python installation
-# scripts
+# Create the virtual environment needed by the Python installation scripts
 create-python-venv () {
   cd $DEPLOY_DIR
   # Install required packages
@@ -64,8 +62,7 @@ create-python-venv () {
   python -m piptools sync requirements.txt
 }
 
-# Install Kubernetes engine and other supporting
-# software
+# Install Kubernetes engine and other supporting software
 install-kubernetes () {
   # Let the user know what to expect
   cat << .EOM
@@ -105,8 +102,7 @@ set-k3s-env () {
   fi
 }
 
-# Install the public charts used by The Combine, specifically, cert-manager
-# and nginx-ingress-controller
+# Install the public charts used by The Combine
 install-base-charts () {
   set-k3s-env
   #####
@@ -145,13 +141,12 @@ install-the-combine () {
   deactivate
 }
 
-# Wait until all the combine deployments are "Running"
+# Wait until all The Combine deployments are "Running"
 wait-for-combine () {
-  # Wait for all combine deployments to be up
+  # Wait for all The Combine deployments to be up
   while true ; do
     combine_status=`kubectl -n thecombine get deployments`
-    # assert the The Combine is up; if any components are not up,
-    # set it to false
+    # Assert The Combine is up; if any components are not up, set it to false
     combine_up=true
     for deployment in frontend backend database maintenance ; do
       deployment_status=$(echo ${combine_status} | grep "${deployment}" | sed "s/^.*\([0-9]\)\/1.*/\1/")
@@ -168,8 +163,7 @@ wait-for-combine () {
   done
 }
 
-# Set the next value for STATE and record it in
-# the STATE_FILE
+# Set the next value for STATE and record it in the STATE_FILE
 next-state () {
   STATE=$1
   if [[ "${STATE}" == "Done" && -f "${STATE_FILE}" ]] ; then
@@ -179,8 +173,7 @@ next-state () {
   fi
 }
 
-# Verify that the required network devices have been setup
-# for Kubernetes cluster
+# Verify that the required network devices have been setup for Kubernetes cluster
 wait-for-k8s-interfaces () {
   echo "Waiting for k8s interfaces"
   for interface in $@ ; do
@@ -273,14 +266,13 @@ while [ "$STATE" != "Done" ] ; do
       next-state "Base-charts"
       if [ -f /var/run/reboot-required ] ; then
         echo -e "***** Restart required *****\n"
-        echo -e "Rerun combine installer after the system has been restarted.\n"
+        echo -e "Rerun The Combine installer after the system has been restarted.\n"
         read -p "Restart now? (Y/n) " RESTART
         if [[ -z $RESTART || $RESTART =~ ^[yY].* ]] ; then
           sudo reboot
         else
-          # We don't call next-state because we don't want the $STATE_FILE
-          # removed - we want the install script to resume with the recorded
-          # state.
+          # We don't call next-state because we don't want the $STATE_FILE removed;
+          # we want the install script to resume with the recorded state.
           STATE=Done
         fi
       fi
@@ -303,19 +295,20 @@ while [ "$STATE" != "Done" ] ; do
       fi
       ;;
     Wait-for-combine)
-      # Wait until all the combine deployments are up
-      echo "Waiting for The Combine components to download."
+      # Wait until all The Combine deployments are up
+      echo "Waiting for The Combine components to download and setup."
       echo "This may take some time depending on your Internet connection."
       echo "Press Ctrl-C to interrupt."
       wait-for-combine
+      echo "The Combine was successfully setup!"
       next-state "Shutdown-combine"
       ;;
     Shutdown-combine)
       # If not being installed as a server,
       if [[ $IS_SERVER != 1 ]] ; then
-        # Shut down the combine services
+        # Shut down The Combine services
         combinectl stop
-        # Disable combine services from starting at boot time
+        # Disable The Combine services from starting at boot time
         sudo systemctl disable create_ap
         sudo systemctl disable k3s
       fi