First commit

.gitignore

@@ -0,0 +1,15 @@
+.asciidoctor
+.cache
+?
+
+# Antora files
+_public
+_archive
+
+# IDEs - Temporary
+.vscode
+
+# Autogenerated STEM files during PDF generation
+stem-*.svg
+diagram-*.svg
+

.gitlab-ci.yml

@@ -0,0 +1,47 @@
+variables:
+  PROJECT_NAME: vshn-application-catalog
+  MASTER_SEARCH_IMAGE: vshn/embedded-search-engine:1.3
+  MAIN_IMAGE: registry.appuio.ch/vshn-application-catalog/vshn-application-catalog-main:latest
+  SEARCH_IMAGE: registry.appuio.ch/vshn-application-catalog/vshn-application-catalog-search:latest
+
+stages:
+  - build
+  - deploy
+
+.build-docker:
+  stage: build
+  image: docker:stable
+  services:
+    - docker:dind
+  tags:
+    - dockerbuild
+  script:
+    - docker login -u gitlab-ci -p ${APPUIO_REGISTRY_TOKEN} registry.appuio.ch
+    - docker pull $MAIN_IMAGE || true
+    - docker build --cache-from $MAIN_IMAGE -t $MAIN_IMAGE -f deployment/main/Dockerfile .
+    - if [ ${CI_COMMIT_REF_NAME} == "master" ]; then docker push $MAIN_IMAGE; fi
+    - docker pull $MASTER_SEARCH_IMAGE || true
+    - docker build --cache-from $SEARCH_IMAGE -t $SEARCH_IMAGE -f deployment/search/Dockerfile .
+    - if [ ${CI_COMMIT_REF_NAME} == "master" ]; then docker push $SEARCH_IMAGE; fi
+
+develop:build:
+  extends: .build-docker
+  except:
+    - master
+
+master:build:
+  extends: .build-docker
+  only:
+    - master
+
+master:deploy:
+  stage: deploy
+  image: docker.io/appuio/oc:v3.11
+  environment:
+    name: production
+    url: https://application-catalog.vshn.ch
+  script:
+    - oc -n ${PROJECT_NAME} apply -f deployment/
+    - oc -n ${PROJECT_NAME} rollout latest dc/vshn-application-catalog
+  only:
+    - master

CHANGELOG.adoc

@@ -0,0 +1,9 @@
+= CHANGELOG
+
+== Version 1.0
+
+* Project created by Tobias Brunner <[email protected]>>
+* First version
+
+TODO: Remember to update this file regularly
+

Makefile

@@ -0,0 +1,67 @@
+pages   := $(shell find . -type f -name '*.adoc')
+out_dir := ./_public
+
+docker_cmd  ?= docker
+docker_opts ?= --rm --tty --user "$$(id -u)"
+
+antora_cmd  ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}":/antora vshn/antora:2.3.3
+antora_opts ?= --cache-dir=.cache/antora
+
+asciidoctor_cmd  ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}":/documents/ asciidoctor/docker-asciidoctor asciidoctor
+asciidoctor_pdf_cmd  ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}":/documents/ vshn/asciidoctor-pdf:1.5.3 --attribute toclevels=1
+asciidoctor_epub3_cmd  ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}":/documents/ vshn/asciidoctor-epub3:1.4.1 --attribute toclevels=1
+asciidoctor_opts ?= --destination-dir=$(out_dir)
+asciidoctor_kindle_opts ?= --attribute ebook-format=kf8
+
+vale_cmd ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}"/docs/modules/ROOT/pages:/pages vshn/vale:2.6.1 --minAlertLevel=error /pages
+hunspell_cmd ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}":/spell vshn/hunspell:1.7.0 -d en,vshn -l -H _public/**/*.html
+htmltest_cmd ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}"/_public:/test wjdp/htmltest:v0.12.0
+preview_cmd ?= $(docker_cmd) run --rm --publish 35729:35729 --publish 2020:2020 --volume "${PWD}":/preview/antora vshn/antora-preview:2.3.4 --antora=docs --style=vshn
+
+.PHONY: all
+all: html pdf
+documents: pdf manpage kindle epub
+
+# This will clean the Antora Artifacts, not the npm artifacts
+.PHONY: clean
+clean:
+	rm -rf $(out_dir) '?' .cache
+
+.PHONY: check
+check:
+	$(vale_cmd) && cd docs && ./check_orphans.py
+
+.PHONY: syntax
+syntax: html
+	$(hunspell_cmd)
+
+.PHONY: htmltest
+htmltest: html pdf epub kindle manpage
+	$(htmltest_cmd)
+
+.PHONY: preview
+preview:
+	$(preview_cmd)
+
+.PHONY: html pdf manpage epub kindle
+html:    $(out_dir)/index.html
+pdf:     $(out_dir)/application-catalog.pdf
+manpage: $(out_dir)/application-catalog.1
+epub:    $(out_dir)/application-catalog.epub
+kindle:  $(out_dir)/application-catalog-kf8.epub
+
+$(out_dir)/index.html: playbook.yml $(pages)
+	$(antora_cmd) $(antora_opts) $<
+
+$(out_dir)/%.1: docs/%.adoc $(pages)
+	$(asciidoctor_cmd) --backend=manpage --attribute doctype=manpage $(asciidoctor_opts) $<
+
+$(out_dir)/%.pdf: docs/%.adoc $(pages)
+	$(asciidoctor_pdf_cmd) $(asciidoctor_opts) $<
+
+$(out_dir)/%.epub: docs/%.adoc $(pages)
+	$(asciidoctor_epub3_cmd) $(asciidoctor_opts) $<
+
+$(out_dir)/%-kf8.epub: docs/%.adoc $(pages)
+	$(asciidoctor_epub3_cmd) $(asciidoctor_kindle_opts) $(asciidoctor_opts) $<
+

README.adoc

@@ -0,0 +1,47 @@
+= VSHN Application Catalog
+
+This is an https://antora.org/[Antora] documentation website, available at https://application-catalog.docs.vshn.ch.
+
+== Basic Antora Setup
+
+* The documentation pages are stored in the `docs/modules/ROOT/pages` folder.
+* Images are stored in the `docs/modules/ROOT/assets/images` folder.
+* E-book specific files are located in the `docs/ebook` folder, including the https://www.gimp.org/[Gimp] template of the cover.
+
+== Different Kinds of Antora Websites
+
+There are two possible Antora projects:
+
+* Those including both a `playbook.yml` and `docs/antora.yml` files; and
+* Those only including one of them and not the other.
+
+The file `docs/antora.yml` defines a documentation component including several modules. It specifies the name and entry point of a component.
+
+On the other hand, the file `playbook.yml` is used to coalesce various documentation components into one website. It specifies the build order and the style to apply to the final website.
+
+If your project only requires to be documented, but does _not_ take the responsibility for the build process of the documentation, you can remove the `.gitlab-ci.yml`, `Makefile`, and `playbook.yml` files.
+
+On the other hand, projects in charge of documentation building do not always include documentation themselves; in those cases the `docs` folder can be safely deleted, only leaving the `playbook.yml` file.
+
+== Usage
+
+. `make preview` to launch a "live preview" version of the documentation.
+. `make html` to create the Antora website in the `_public` subfolder.
+. `make pdf epub kindle manpage` to create the corresponding e-books in the `_public` subfolder.
+. `make clean` to remove all build products.
+
+== Docker
+
+You can create a Docker image out of this project:
+
+[source,bash]
+----
+$ docker build -t application-catalog -f deployment/main/Dockerfile .
+$ docker run --rm --detach --publish 8080:8080 application-catalog
+----
+
+The project includes sample YAML files for a suitable Kubernetes deployment.
+
+== GitLab
+
+This project includes a ready-to-use `.gitlab-ci.yml` file for GitLab integration.

deployment/deployment.yaml

@@ -0,0 +1,50 @@
+apiVersion: v1
+kind: DeploymentConfig
+metadata:
+  name: vshn-application-catalog
+  labels:
+    app: vshn-application-catalog
+spec:
+  replicas: 1
+  template:
+    metadata:
+      labels:
+        app: vshn-application-catalog
+    spec:
+      containers:
+        - name: vshn-application-catalog-main
+          image: docker-registry.default.svc:5000/vshn-application-catalog/vshn-application-catalog-main:latest
+          imagePullPolicy: Always
+          readinessProbe:
+            httpGet:
+              path: "/index.html"
+              port: 8080
+            periodSeconds: 60
+          livenessProbe:
+            httpGet:
+              path: "/index.html"
+              port: 8080
+            periodSeconds: 60
+            initialDelaySeconds: 5
+          ports:
+          - name: http
+            containerPort: 8080
+            protocol: TCP
+        - name: vshn-application-catalog-search
+          image: docker-registry.default.svc:5000/vshn-application-catalog/vshn-application-catalog-search:latest
+          imagePullPolicy: Always
+          readinessProbe:
+            httpGet:
+              path: "/search?q=readinessProbe"
+              port: 3000
+            periodSeconds: 60
+          livenessProbe:
+            httpGet:
+              path: "/search?q=livenessProbe"
+              port: 3000
+            periodSeconds: 60
+            initialDelaySeconds: 5
+          ports:
+          - name: http
+            containerPort: 3000
+            protocol: TCP

deployment/main/Dockerfile

@@ -0,0 +1,50 @@
+# ---------- STEP 1 ----------
+# Build the documentation in web format
+FROM vshn/antora:2.3.3 AS antora
+
+WORKDIR /build
+COPY . /build
+RUN make html antora_cmd=antora antora_opts=--fetch
+
+# ---------- STEP 2 ----------
+# Build the documentation in manpage format
+FROM asciidoctor/docker-asciidoctor AS asciidoctor
+
+# The base image uses `/documents` as workdir, but has also declared this a
+# volume. This results in files written there to be lost in following steps.
+WORKDIR /build
+COPY . /build
+RUN make manpage asciidoctor_cmd=asciidoctor
+
+# ---------- STEP 3 ----------
+# Build the documentation in PDF
+FROM vshn/asciidoctor-pdf:1.5.3 AS asciidoctor-pdf
+
+# The base image uses `/documents` as workdir, but has also declared this a
+# volume. This results in files written there to be lost in following steps.
+WORKDIR /build
+COPY . /build
+RUN generate-vshn-pdf docs/application-catalog.adoc
+
+# ---------- STEP 4 ----------
+# Build the documentation in PDF
+FROM vshn/asciidoctor-epub3:1.4.1 AS asciidoctor-epub3
+
+# The base image uses `/documents` as workdir, but has also declared this a
+# volume. This results in files written there to be lost in following steps.
+WORKDIR /build
+COPY . /build
+RUN generate-vshn-epub3 docs/application-catalog.adoc --attribute !ebook-validate
+RUN generate-vshn-epub3 docs/application-catalog.adoc --attribute ebook-format=kf8 --attribute !ebook-validate --out-file=docs/application-catalog.mobi
+
+# ---------- STEP 5 ----------
+# Docker image only containing nginx and the freshly built documentation
+FROM vshn/nginx:1.18.0
+
+# Finally, copy the contents of the documentation to be served
+COPY --from=antora /build/_public /usr/share/nginx/html
+COPY --from=asciidoctor ["/build/_public/application-catalog.1", "/usr/share/nginx/html/"]
+COPY --from=asciidoctor-pdf ["/build/docs/application-catalog.pdf", "/usr/share/nginx/html/"]
+COPY --from=asciidoctor-epub3 ["/build/docs/application-catalog.epub", "/usr/share/nginx/html/"]
+COPY --from=asciidoctor-epub3 ["/build/docs/application-catalog.mobi", "/usr/share/nginx/html/"]
+

deployment/route.yaml

@@ -0,0 +1,18 @@
+apiVersion: route.openshift.io/v1
+kind: Route
+metadata:
+  name: vshn-application-catalog
+  labels:
+    app: vshn-application-catalog
+  annotations:
+    kubernetes.io/tls-acme: "true"
+spec:
+  host: application-catalog.appuioapp.ch
+  port:
+    targetPort: http
+  tls:
+    insecureEdgeTerminationPolicy: Redirect
+    termination: edge
+  to:
+    kind: Service
+    name: vshn-application-catalog

deployment/search/Dockerfile

@@ -0,0 +1,20 @@
+# ---------- STEP 1 ----------
+# Index the project files
+FROM vshn/antora-indexer-cli:1.6 as indexer
+
+WORKDIR /build
+COPY . /build
+
+RUN \
+    mkdir /index && \
+    antora-indexer --antora /build/docs --write files --output /index/files.json && \
+    antora-indexer --antora /build/docs --write index --output /index/lunr.json
+
+# ---------- STEP 2 ----------
+# Docker image only containing the search engine and the freshly built index
+FROM vshn/embedded-search-engine:1.3
+
+# Copy the index of the search engine
+COPY --from=indexer /index/files.json /site/index/files.json
+COPY --from=indexer /index/lunr.json /site/index/lunr.json
+

deployment/service.yaml

@@ -0,0 +1,15 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: vshn-application-catalog
+  labels:
+    app: vshn-application-catalog
+spec:
+  ports:
+    - name: http
+      port: 8080
+      protocol: TCP
+      targetPort: http
+  selector:
+    app: vshn-application-catalog
+  type: ClusterIP

docs/antora.yml

@@ -0,0 +1,6 @@
+name: ac
+title: VSHN Application Catalog
+version: master
+start_page: ROOT:index.adoc
+nav:
+- modules/ROOT/nav.adoc