Merge pull request #134 from epics-containers/august-update

gilesknap · web-flow · commit 575635208be0 · 2024-08-05T13:22:48.000+01:00
August update - review Essential Concepts and Intro pages
diff --git a/docs/explanations/introduction.md b/docs/explanations/introduction.md
diff --git a/docs/index.md b/docs/index.md
@@ -56,7 +56,7 @@ Update for February 2024
 The tutorials have now been updated. Recent changes include:
 
 - epics-containers-cli has been renamed to edge-containers-cli. It now supports the deployment of general services as well as IOCs. It still has the entrypoint `ec` but the namespace `ioc` has been dropped and its functions are now in the root (e.g. `ec ioc deploy` is now `ec deploy`).
-- Improved CI for {any}`ec-services-repo`s and generic IOCs repos.
+- Improved CI for {any}`services-repo`s and generic IOCs repos.
 - copier template based creation of new beamline, accelerator and generic IOC repos.
   - This provides greatly improved ability to adopt updates to the template into your own repositories.
 
diff --git a/docs/overview.md b/docs/overview.md
@@ -18,7 +18,8 @@ There are 5 themes to this strategy:
   Source, container and helm repositories manage all of the above assets.
   No shared file systems required.
 
-:Continuous Integration / Delivery:
-  Source repositories automatically build containers and helm charts
-  delivering them to OCI registries.
+:Continuous Integration / Deployment:
+  Source repositories automatically build containers and helm charts,
+  delivering them to OCI registries. Services repositories automatically deploy
+  IOCs to Kubernetes clusters.
 ```
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
@@ -16,7 +16,7 @@ The CLI is just a thin wrapper around the underlying tools that do the real work
 :git: the git version control system client
 ```
 
-`ec` is useful because it saves typing and provides a consistent interface when working on multiple {any}`ec-services-repo` s. This is because it uses the environment setup by the beamline repo's `environment.sh` script. See {any}`environment`.
+`ec` is useful because it saves typing and provides a consistent interface when working on multiple {any}`services-repo` s. This is because it uses the environment setup by the beamline repo's `environment.sh` script. See {any}`environment`.
 
 To see the available commands, run `ec --help`.
 
diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md
@@ -1,15 +1,20 @@
 
 # Glossary
 
-(ec-services-repo)=
-## ec-services repository
+(services-repo)=
+## services repository
 
-A repository that contains the definitions for a group of IOC and service instances that are deployed in a Kubernetes cluster. The grouping of instances is up to the facility. At DLS the instances are grouped by beamline for beamline IOCs. Accelerator IOC groupings are by location or by technical domain as appropriate.
+A repository that contains the definitions for a group of IOCs instances and other services. The grouping of instances is up to the facility. At DLS the instances are grouped by beamline for beamline IOCs. Accelerator IOC groupings by technical domain as appropriate.
+
+epics-containers supports two kinds of services repositories:
+
+- **Kubernetes** services repositories. These are for deployment into a Kubernetes cluster. Each repositoriy contains a set of **Helm Charts** all of which will deploy into a single namespace in a single Kubernetes Cluster.
+- **Local Machine** services repositories. These are for deployment to a local machine using docker-compose. Each repository contains a set *compose.yaml* files that describe how to deploy a set of services to the local machine. These could potentially be used for production at a facility which does not use Kuberentes, but are primarily for development, testing and the earlier tutorials in this documenttation.
 
 (edge-containers-cli)=
 ## edge-containers-cli
 
-A Python command line tool for the developer that runs *outside* of containers. It provides features for deploying and managing service and IOC instances within an [](ec-services-repo).
+A Python command line tool for the developer that runs *outside* of containers. It provides simple features for and monitoring and managing and IOC instances within a [](services-repo).
 
 So named 'edge' containers because these services all run close to the hardware. Uses the command line entry point `ec`.
 
diff --git a/docs/tutorials/create_beamline.md b/docs/tutorials/create_beamline.md
@@ -2,7 +2,7 @@
 
 # Create a Beamline Repository
 
-In this tutorial we will create a new {any}`ec-services-repo`.
+In this tutorial we will create a new {any}`services-repo`.
 
 All IOC Instances that we deploy will be grouped into repositories that define a set of IOC and service instances. Typically each beamline would have its own repository and the accelerator would be split by location or technical area.
 
diff --git a/docs/tutorials/dev_container.md b/docs/tutorials/dev_container.md
@@ -11,7 +11,7 @@ frequency of change but increasing complexity):
 ### Changing the IOC instance
 
 This means making changes to the IOC instance folders
-which appear in the `iocs` folder of an {any}`ec-services-repo`. e.g.:
+which appear in the `iocs` folder of an {any}`services-repo`. e.g.:
 
 - changing the EPICS DB (or the `ibek` files that generate it)
 - altering the IOC boot script (or the `ibek` files that generate it)
diff --git a/docs/tutorials/intro.md b/docs/tutorials/intro.md
@@ -13,10 +13,12 @@ some background in the following topics.
 ================================================================    ================
 **An introduction to containers**                                   https://www.docker.com/resources/what-container/
 **Managing containers on a workstation: introduction to docker**    https://docs.docker.com/get-started/overview/
+**Introduction to docker compose**                                  https://docs.docker.com/compose/
 **Podman, a recommended docker alternative**                        https://docs.podman.io/en/latest/Introduction.html
 **Orchestrating containers in a cluster with Kubernetes**           https://kubernetes.io/docs/concepts/overview/
 **Managing packages in a Kubernetes Cluster with Helm**             https://helm.sh/docs/intro/quickstart/
 **Introduction to EPICS**                                           https://docs.epics-controls.org/en/latest/guides/EPICS_Intro.html
+**Argo CD continuous delpoyment for Kubernetes**                    https://argo-cd.readthedocs.io/en/stable/
 ================================================================    ================
 ```
 
