manual updates

manual/appendix/developers.tex

@@ -5,7 +5,7 @@ \chapter{\cxoneflow Developer Information}
 will be for using Ubuntu and VSCode. If you have different development tooling you'd like
 to use, you'll need to adapt these instructions to fit your tooling.
 
-The target version of Python is currently 3.12.  Using versions prior to 3.12 will likely result in
+\noindent\\The target version of Python is currently 3.12.  Using versions prior to 3.12 will likely result in
 runtime errors.
 
 \section{Secrets}
@@ -14,9 +14,9 @@ \section{Secrets}
 
 \noindent\\In general, it is a bad idea to commit secrets to the repository.  The \texttt{.gitignore} file is configured
 to ignore folders named \texttt{secrets} and YAML files in the root of the code directory.  This 
-can be circumvented or other files containing secrets can be inadvertently commited.
+can be circumvented or other files containing secrets can be inadvertently committed.
 
-\noindent\\If you've commited secrets but not pushed to the public GitHub repository, you can edit the commit history
+\noindent\\If you've committed secrets but not pushed to the public GitHub repository, you can edit the commit history
 or merge your clean code into a new clone.  If you've pushed a secret into the public repository, please notify
 the other maintainers so the impact can be assessed.
 

manual/appendix/systemd_service.tex

@@ -0,0 +1,93 @@
+\chapter{Running \cxoneflow as a \texttt{systemd} Service}
+
+
+Running \cxoneflow as a \texttt{systemd} service on Linux is one method that
+will allow the container to be started automatically when the hosting system
+is rebooted.  The \texttt{systemd} service can then be used to start and stop the
+\cxoneflow services.  This section details an example configuration that can be adapted
+to your environment.
+
+
+\section{Obtain and Store Files}
+
+In the directory \texttt{/opt/cxoneflow}, collect the configuration YAML, PEM encoded SSL certificate, PEM encoded SSL certificate private key,
+and any secret\footnote{If planning to map secrets to the container using other methods, 
+writing the files is not required.} files referenced in the configuration YAML.  The following
+ownership and permissions files are suggested:
+
+\begin{itemize}
+    \item Set the ownership to \texttt{root:docker} with the command \texttt{chown -R root:docker /opt/cxoneflow}
+    \item Set the permissions of \texttt{/opt/cxoneflow} using the command \texttt{chmod 750 /opt/cxoneflow}
+    \item Set the permissions of the files in \texttt{/opt/cxoneflow} using the command
+    \texttt{chmod -R 740 /opt/cxoneflow/*}
+\end{itemize}
+
+
+\section{Container Creation}
+
+Creating a reusable container with the name \textbf{cxoneflow} can be done with the following
+command:
+
+\begin{code}{Container Creation Command}{}{}
+docker create --rm --name "cxoneflow" -p 443:8443 --env-file runtime.env \
+  -v /path/to/cert.pem:/opt/cxone/certs/mycert.pem \
+  -v /path/to/private.key.pem:/opt/cxone/certs/my.private.key.pem \
+  -v /path/to/config.yaml:/opt/cxone/config.yaml \
+  -v /path/to/secrets:/run/secrets \
+  ghcr.io/checkmarx-ts/cxone/cxone-flow:latest
+\end{code}
+
+\noindent\\The command creates a container with the following properties:
+
+\begin{itemize}
+    \item The container with the name \textbf{cxoneflow} is created.
+    \item The \texttt{----rm} automatically removes the container named \textbf{cxoneflow} if
+    it exists.
+    \item Port 443 is mapped to port 8443 of the container to support secure communication with
+    the \cxoneflow endpoint.
+    \item Runtime environment variables (as described in Section \ref{sec:runtime-config}) 
+    located in the file \texttt{runtime.env} are injected into the container's environment.
+    \item Maps the following files from the local \texttt{/path/to/} path to files for the SSL
+    certificate, configuration YAML, and secrets
+    \footnote{This is assuming the secrets are not already mapped to the container using other methods.}.
+\end{itemize}
+
+\noindent\\It is suggested that the command is incorporated into a shell script so it may be
+invoked to recreate the container during a version upgrade.
+
+\section{Service Definition}
+
+A \texttt{systemd} service definition should be created using a file named, for example,
+\\\texttt{/opt/cxoneflow/cxoneflow.service}.  The service definition should have contents
+similar to the following:
+
+\begin{code}{/opt/cxoneflow/cxoneflow.service}{}{}
+[Unit]
+Description=CxOneFlow container
+Requires=docker.service
+After=docker.service
+
+[Service]
+Restart=always
+ExecStart=/usr/bin/docker start -a cxoneflow
+ExecStop=/usr/bin/docker stop cxoneflow
+Type=exec
+
+[Install]
+WantedBy=default.target
+
+\end{code}
+
+\noindent\\The service definition allows \texttt{systemd} to manage the start
+and stop of the \cxoneflow service in response to system startup and shutdown.
+
+
+\section{Enable and Start the \cxoneflow Service}
+
+The following commands will enable the service and start \cxoneflow:
+
+\begin{code}{}{}{}
+sudo systemctl enable /opt/cxoneflow/cxoneflow.service
+sudo systemctl start cxoneflow
+\end{code}
+

manual/appendix/troubleshooting.tex

@@ -0,0 +1,25 @@
+\chapter{Troubleshooting}
+
+If \cxoneflow does not appear to be operating as expected, the following
+troubleshooting steps may help to understand the reason:
+
+\begin{itemize}
+    \item The environment variable \texttt{LOG\_LEVEL} can be set to \texttt{DEBUG}
+    to emit trace information as \cxoneflow is running.
+
+    \item Navigate to the \texttt{ping} endpoint in your browser to see the 
+    \texttt{pong} response using: \texttt{http://<server>/ping}
+
+    \item The \cxoneflow logs are streamed to the container's stdout.  It can be
+    viewed by running the container interactively or using a command such as
+    \texttt{docker logs -f <container name>}
+
+    \item Nginx and Gunicorn logs can be found in \texttt{/var/log} on the container
+    image.  A shell on the container can be opened using a command such as
+    \texttt{docker exec -it <container name> bash}
+
+\end{itemize}
+
+\noindent\\Exception stack traces emitted in the \cxoneflow logs can generally
+indicate any issues it is encountering.  Many issues are likely to be configuration
+related.

manual/cxone-flow.tex

@@ -79,6 +79,8 @@ \part{Appendices}
 \appendix
 \input{release_notes.tex}
 \input{appendix/endpoint_monikers.tex}
+\input{appendix/systemd_service.tex}
+\input{appendix/troubleshooting.tex}
 \input{appendix/developers.tex}
 
 

manual/operation/yaml_minimal_example.tex

@@ -18,7 +18,7 @@
     \item Using the CheckmarxOne multi-tenant US region API endpoint.
 \end{enumerate}
 
-\begin{code}{Minimal YAML Configuration Example \#1}{[CxOne: oauth]}{[SCM: token auth]}
+\begin{code}{Minimal YAML Configuration Example \#1}{Using BitBucket Data Center}{}
 secret-root-path: /run/secrets
 
 bbdc:
@@ -41,7 +41,7 @@
 \pagebreak
 \noindent\\An alternate minimal example using different authorization options:
 
-\begin{code}{Minimal YAML Configuration Example \#2}{[CxOne: api-key]}{[SCM: basic/ssh auth]}
+\begin{code}{Minimal YAML Configuration Example \#2}{Using BitBucket Data Center}{}
 secret-root-path: /run/secrets
 
 bbdc:
@@ -66,7 +66,7 @@
 \noindent\\An alternate minimal example using for an Azure DevOps Enterprise
 SCM:
 
-\begin{code}{Minimal YAML Configuration Example \#2}{[CxOne: api-key]}{[SCM: basic/ssh auth]}
+\begin{code}{Minimal YAML Configuration Example \#2}{Using Azure DevOps Enterprise}{}
 secret-root-path: /run/secrets
 
 adoe:

manual/scms/adoe.tex

@@ -1,11 +1,11 @@
-\chapter{Azure DevOps Enterprise}
+\chapter{Azure DevOps}
 
 
-\section{About Azure DevOps Enterprise}
+\section{About Azure DevOps Enterprise \& Cloud}
 
-Azure DevOps Enterprise is an on-premise variation of the cloud-hosted Azure DevOps services.  It
-should be noted that the configuration for Azure DevOps Enterprise is not intended to be
-compatible with the cloud-hosted version of Azure DevOps.
+Azure DevOps Enterprise is an on-premise variation of the cloud-hosted Azure DevOps services.
+Both versions are compatible with \cxoneflow and are generically referred to Azure DevOps Enterprise
+throughout this documentation.
 
 \noindent\\The \cxoneflow endpoint \texttt{/adoe} is the handler for all webhook event
 payloads originating from Azure DevOps Enterprise.