[gimp-web/oscp] README: add infos about OpenShift in a README file.

[Jehan <jehanp src gnome org>]

commit 0f53d03b08a6f3658f0a4ca52fbe679d8e9d1bd9
Author: Jehan <jehan girinstud io>
Date:   Fri Feb 25 14:08:24 2022 +0100

    README: add infos about OpenShift in a README file.
    
    This platform has so many stuff that it's quite hard to navigate without
    being a full-time sysadmin. Hopefully this will help anyone else to not
    go through the hurdle of understanding the system tiny pieces at once.
    
    And it should also help myself next time I need to look at
    fixing/improving our websites' publication scripts!

 README | 115 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 115 insertions(+)
---
diff --git a/README b/README
new file mode 100644
index 00000000..344cc773
--- /dev/null
+++ b/README
@@ -0,0 +1,115 @@
+# Managing the oscp branch
+
+This branch is where we keep all the OpenShift scripts. These are the
+Docker files and other scripts used to run our various websites
+(www.gimp.org, docs.gimp.org, testing websites, etc.) as containers.
+
+## Permissions
+
+It has special permissions and even when you have push rights on the
+`gimp-web` repository, you may not have push rights on this branch. If
+you believe you should, ask GIMP maintainers, then if they confirm,
+request permission to the GNOME Infrastructure team by opening a report
+on: https://gitlab.gnome.org/Infrastructure/Infrastructure/
+
+## Basics
+
+Each website scripts are under a folder with the website domain. The
+`Dockerfile` in particular is the construction file of the container.
+You select some base image, and some commands to run at creation, for
+instance the commands to build the website.
+
+OpenShift has a web GUI at: https://openshift.gnome.org:8443/
+
+In there, select the "GIMP Websites", then in the menu `Builds >
+Builds`, you can inspect the last builds for every website and debug
+problems for instance. You can also trigger new builds manually with the
+"Start Build" button.
+
+Note that every website should have a `testing.` version. Any oscp
+change we do should first be done on the testing version. There it's
+alright if we break things (it's made for this). Only port the changes
+to the main websites once you figured things out on testing.
+
+## Going further
+
+Some builds are more complicated than others, this is the case for the
+documentation website (built out of `gimp-help` repository).
+
+You will notice 2 `Dockerfile` there:
+
+- `testing.docs.gimp.org/httpd/Dockerfile`: this is what runs the httpd
+  web server.
+- `testing.docs.gimp.org/docs_build/Dockerfile`: this is what sets up
+  the build of the documentation. Yet apparently it does not even build
+  said documentation in there. It only updates the `entrypoint.sh` file,
+  it doesn't run it (maybe because the documentation build takes too
+  much time?).
+
+The `entrypoint.sh` is actually run as a cron job run daily at midnight
+(server time, which I think is UTC).
+
+You can see runnings jobs in `Application > Pods` on the web GUI.
+Nevertheless I still haven't figured out if we can see settings of jobs,
+how to manually run them and more on the web GUI. This is where the `oc`
+CLI tool comes in.
+
+You may install it from:
+
+- your distribution package if it has any. For instance in Fedora, it's
+  available in package `origin-clients`.
+- As a go static binary at: https://github.com/openshift/oc
+
+Now here is a process to view, run and follow jobs from terminal:
+
+- In the web GUI, on the top-right corner of the page, click your name,
+  then "Copy Login Command".
+- Paste the command which is now in your clipboard in terminal. This
+  command will look something like:
+
+```
+oc login https://openshift.gnome.org:8443 --token=<some-unique-token>
+```
+
+- You are now connected from this terminal with a unique temporary
+  token (do not share the token with anyone else, it is a token allowing
+  to do many stuff on our websites which only an admin is allowed to).
+- With the command `oc get all` (it may take a few seconds to load, be
+  patient), you will get many information on pods, services, routes,
+  etc. In particular, you will notice that 2 `cronjob` are listed, one
+  is suspended. The active one is
+  `cronjob.batch/testing-docs-regenerate`. This is what builds the docs.
+- To trigger this job manually without waiting midnight UTC, run this
+  command:
+
+```
+oc create job --from=cronjob.batch/testing-docs-regenerate <some-unique-name>
+```
+
+  Replace `<some-unique-name>` obviously. A good naming would be using
+  the job name, yours (to identify callers), the date, and an
+  incrementing number if you run the job several times in the day. For
+  instance:
+
+```
+oc create job --from=cronjob.batch/testing-docs-regenerate regenerate-manual-2022-02-25-jehan-1
+```
+
+- You can now see and follow your job (and its logs) in the web GUI in
+  `Application > Pods`.
+  You can also follow the logs by terminal with:
+
+```
+oc get pods
+```
+
+  This will give you the job run name, which will be the job name you
+  created with some string appended. For instance, in my case it was
+  `regenerate-manual-2022-02-25-jehan-1-qj2wm`. Use this fuller name to
+  refer to your job and request the logs:
+
+```
+oc logs -f regenerate-manual-2022-02-25-jehan-1-qj2wm
+```
+
+  More commands may be available if you look at `oc` help docs.