SwimmPair Web Application

SwimmPair is a web application for managing swimming competitions in the Czech Republic. Application model describes administrative objects, such as cups, clubs, users etc. The main goal is to automate administrative work formerly achived via Excel spreadsheets and provide decent archivation history.

Preview of SwimmPair - public page of Cup w/ available & paired Users.

Web Application Structure Overview

Our web application consists of these main parts:

• public part - www,
• private admin - www/admin,
• app model - www/model,
• mysql database procedures used by the model,
• tests - execute phpunit on www/tests/Unit/* (automatically run in GitHub Actions workflow).

Other stuff that comes with our project in this repo:

• Doxyfile - for HTML docummentation (http://docu-swimmpair.stkl.cz),
• Doxyfile2 - for PDF docummentation (_doc/pdf/refman.pdf),
• docker-compose.yaml - for my local development,
• 2 database scripts (_db/*) - 1 w/ basic data & 1 w/ set of demonstration data,
• workflow (.github/workflows/main.yaml) w/ a job test,
• Dockerfile - for building pullable image of SwimmPair application.

Web Application Data Flow Architecture Overview

Application flow is realized by accessing application page and calling manager functionality (folder www/model), that wrapps database calls and returns results as PHP objects.

Public and private part have PHP form-actions and Ajax endpoints for achieving functionality via. appropriate manager calls and storing payloads sent to them via HTTP POST.

Containerized Local Development

SwimmPair is shipped for production as Docker image. It can be run locally by docker-compose, starting SwimmPair - volume for www_php_1 being www folder + MySQL, Adminer, and Redis containers.

Docker desktop docker-compose up -d of SwimmPair application

Dockerization - Production & Deployment Notes

Bundling PHP files into Docker image with base PHP/Apache image is defined by Dockerfile.

FROM thecodingmachine/php:7.4-v4-apache
COPY --chown=docker . /var/www/html

Dockerhub is default and public namespace for pulling all images - our image can be tagged as stepanklos/swimmpair and therefore be accessible publicly by this name.

Build & Push Docker image of SwimmPair, tagged as stepanklos/swimmpair.

docker build -t stepanklos/swimmpair .
docker push stepanklos/swimmpair

Bundled application image doesn't come with database and adminer/phpmyadmin or Redis. We advise production on cloud provider with database/redis services or use self-hosted database/redis solution storing in Persistent Storage accessed via Persistent Volume Claim.

Installing MySQL Database like mysql-deployment or Redis like redis-deployment into Kubernetes cluster shouldn't be a problem.

SwimmPair Misc.

Running instances

• Visit swimmpair.stkl.cz - development version of the application with dummy data.

Database scripts

• Schema w/ very slim data - _db/1_create_proc_schema_init_data.sql
• Schema full of data - _db/1b_create_proc_schema_all_data.sql

Documentation Doxygen HTML & PDF

Docker image for http://docu.swimmpair.cz and PDF file.

Documentation Doxygen HTML

> www: doxygen Doxyfile
> www: cd _doc/html
> www/_doc/html: docker build -t stepanklos/docu-swimmpair .
> www/_doc_html: docker push stepanklos/docu-swimmpair

Documentation Doxygen PDF

> www: doxygen Doxyfile2
> www: cd _doc/latex
> www/_doc/latex: make
> www/_doc/latex: cd ..
> www/_doc: mkdir -p pdf
> www/_doc: cp latex/refman.pdf pdf/

It is necessary to have installed Doxygen whereabouts and LaTeX w/ pdflatex.

Try it out!

git clone https://github.com/KlosStepan/SwimmPair-Www
docker-compose up --detach 
mysql -h ${DATABASE_HOST} -u ${DATABASE_USER} --password=${DATABASE_PASS} < ./_db/1_create_proc_schema_init_data.sql

SwimmPair Production in DOKS

Several production options in container cloud service providers are possible, be it ECS or EKS in Amazon AWS, some AKS alternative in Microsoft Azure, or self-hosted Kubernetes/Rancher/OpenShift/VMware Tanzu.

We use DigitalOcean Kubernetes because it suits us the best (despite being a little bit pricy ~$40/m).

It is advised to run SwimmPair based on these K8s notes as follows:

• Application: Service + Deployment utilizing stepanklos/swimmpair.
• MySQL DB:
  • either Public Service - Service + Deployment + PVC -> PV,
  • or https://www.digitalocean.com/pricing/managed-databases.
• Database Client: command line / Adminer Deployment / administration dashboard of chosen cloud provider.

Consider 2 Node Cluster and running one replica on each node. Reference swimmpair-service Service from Ingress for cluster routing to access swimmpair Deployment with spawned 2 Pods of up-to-date Replica Set.

Kubernetes Service + Deployment for SwimmPair application

Configuration file app-swimmpair.yaml:

apiVersion: v1
kind: Service
metadata:
  name: swimmpair-service
spec:
  type: ClusterIP
  ports:
  - port: 80
    targetPort: 80
  selector:
    app: swimmpair
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: swimmpair
spec:
  replicas: 2
  selector:
    matchLabels:
      app: swimmpair
  template:
    metadata:
      labels:
        app: swimmpair
    spec:
      containers:
      - name: swimmpair
        image: stepanklos/swimmpair:latest
        securityContext:
          allowPrivilegeEscalation: true
        ports:
        - containerPort: 80
        env:
        - name: MESSAGE
          value: Hello from swimmpair Deployment!
        - name: DATABASE_HOST
          value: 'mysql-service'
        - name: DATABASE_USER
          value: 'user'
        - name: DATABASE_PASS
          value: 'password'
        - name: DATABASE_NAME
          value: 'db'    

Ingress settings snippet for SwimmPair application

Ingress, add SwimmPair to config section rules: in the kubernetes-ingress.yaml as following snippet:

  - host: "swimmpair.stkl.cz"
    http:
      paths:
      - pathType: Prefix
        path: "/"
        backend:
          service:
            name: swimmpair-service
            port:
              number: 80

Run by applying configs via kubectl on the K8s cluster

Finally, apply SwimmPair app config and reapply Ingress config as noted

kubectl apply -f app-swimmpair.yaml
kubectl apply -f kubernetes-ingress-config.yaml

to achieve desired state of running our application in the Kubernetes Cluster.