Feat: Initial Setup & Kubernetes Infrastructure for Mariana Deep (Internal Docs)

src/internal-docs/.env.example

@@ -0,0 +1,43 @@
+# -------------------------------------------------------------------------
+# BookStack Environment Configuration
+# -------------------------------------------------------------------------
+# Copy this file to `.env` before running `docker compose up -d`.
+# Do not commit the `.env` file to version control.
+# -------------------------------------------------------------------------
+
+# The base URL of your BookStack installation.
+# Must include the protocol (http:// or https://)
+APP_URL=http://localhost:6875
+
+# The name of the application (Shows in the header and emails)
+APP_NAME="Mariana Deep"
+
+# Disable public access to enforce authentication for all pages
+# Set to 'true' if you want anonymous users to read documentation
+APP_PUBLIC=false
+
+# Application Key (Required for sessions and encryption)
+# Generate a new one for production using: docker run --rm --entrypoint /bin/bash lscr.io/linuxserver/bookstack:latest appkey
+APP_KEY=
+
+# -------------------------------------------------------------------------
+# Database Configuration
+# -------------------------------------------------------------------------
+# Ensure these match the values used in docker-compose.yml.
+DB_HOST=bookstack_db
+DB_DATABASE=bookstackapp
+DB_USER=bookstack
+DB_PASSWORD=your_secure_db_password
+DB_ROOT_PASSWORD=your_secure_root_password
+
+# -------------------------------------------------------------------------
+# Mail Settings (Optional but recommended for user invitations/resets)
+# -------------------------------------------------------------------------
+# MAIL_DRIVER=smtp
+# MAIL_HOST=smtp.mailtrap.io
+# MAIL_PORT=2525
+# MAIL_USERNAME=null
+# MAIL_PASSWORD=null
+# MAIL_ENCRYPTION=null
+# MAIL_FROM=docs@yourdomain.com
+# MAIL_FROM_NAME="Internal Docs"

src/internal-docs/.gitignore

@@ -0,0 +1,9 @@
+# Ignore environment variables file
+.env
+
+# Ignore Docker volumes for BookStack application state (uploads, themes, etc.)
+config/
+
+# Ignore Docker volumes for MariaDB database files
+db_data/
+db_data_v2/

src/internal-docs/README.md

@@ -0,0 +1,99 @@
+# Mariana Deep - Internal Documentation
+
+This repository contains the containerized environment and Kubernetes Helm charts for **Mariana Deep**, AirQo's internal documentation platform powered by [BookStack](https://www.bookstackapp.com/).
+
+## Table of Contents
+- [Local Setup & Testing](#local-setup--testing)
+- [Kubernetes Deployment](#kubernetes-deployment)
+- [Creating & Editing Documentation](#creating--editing-documentation)
+- [Information Architecture](#information-architecture-product-focused)
+- [Contributing Guidelines](#contributing-guidelines)
+- [Security & Data Persistence](#security--data-persistence)
+
+## Local Setup & Testing
+
+To spin up the documentation platform locally for testing or local development:
+
+1. **Configure the Environment**
+   Duplicate the provided example environment file:
+
+   *macOS / Linux:*
+   ```bash
+   cp .env.example .env
+   ```
+   *Windows (Command Prompt / PowerShell):*
+   ```cmd
+   copy .env.example .env
+   ```
+
+2. **Start the Containers**
+   Use Docker Compose to build and start the environment in the background:
+   ```bash
+   docker compose up -d
+   ```
+
+3. **Access the Application**
+   Wait approximately 20 seconds for database migrations to complete.
+   Open your browser and navigate to `http://localhost:6875`.
+   *(Default credentials on first run: `admin@admin.com` / `password`)*
+
+## Kubernetes Deployment
+
+The project uses Helm charts located in the `k8s/` directory to deploy to our production cluster.
+
+### Environments
+- **Production**: Accessible at `https://platform.airqo.net/mariana`
+
+### Deployment Commands
+To deploy or upgrade the cluster, run the following Helm commands from the root of this project:
+
+**Production:**
+```bash
+helm upgrade --install airqo-internal-docs k8s/ -f k8s/values-prod.yaml -n production
+```
+
+## Creating & Editing Documentation
+
+BookStack features an intuitive WYSIWYG editor, making it incredibly easy for any technical contributor to document features, APIs, and runbooks without fighting markdown syntax (though Markdown is fully supported!).
+
+### How to Create Content
+1. **Navigate to the appropriate Book**: Look at the Information Architecture below to find exactly where your document belongs.
+2. **Add a Chapter or Page**: Click the "New Page" or "New Chapter" button in the right sidebar menu.
+3. **Use the Editor**: Write your documentation. You can drag-and-drop images directly into the editor. If you prefer raw markdown, you can switch the editor type in your user settings.
+4. **Link Internal Content**: Use the "Link" button to easily search and interlink to other existing internal documents.
+
+### Best Practices for Documentation
+- **Keep it Concise**: Use bullet points, clear headings, and avoid massive walls of text. Scannability is key.
+- **Keep it Updated**: The Boy Scout Rule applies—if you change a system's behavior, update its documentation in the exact same sprint.
+- **Use Code Blocks**: When documenting CLI commands, scripts, or JSON payloads, use properly formatted code blocks.
+- **Tagging**: Use tags on your pages (e.g., `api`, `deprecated`, `v2`) to make them highly searchable across the platform.
+
+## Information Architecture (Product-Focused)
+
+We organize all of our documentation using a **Product-focused approach**. Whether it's a mobile app, a microservice, or a data pipeline, every major initiative is treated as a Product. Strictly adhere to the following hierarchy:
+
+1. **Shelves (High-Level Domains)**: Groups related products under a larger domain or suite.
+   *(Examples: AirQo Platform, Data Pipelines, Mobile Apps, Infrastructure)*
+2. **Books (The Products)**: Represents a specific Product, Microservice, or distinct Tool.
+   *(Examples: Netmanager, Beacon, AirQo API, Ingestion Pipeline)*
+3. **Chapters (Major Components)**: Groups related documentation topics within a specific Product.
+   *(Examples: Architecture, API Reference, Deployment Guides, Runbooks)*
+4. **Pages (Specific Documents)**: The granular, individual pieces of documentation.
+   *(Examples: Authentication Flow Diagram, GET /v1/devices, How to run the calibration script)*
+
+**Example Flow:**
+`Shelves (AirQo Platform) -> Book (Netmanager) -> Chapter (API Reference) -> Page (Authentication Endpoint)`
+
+## Contributing Guidelines
+
+We encourage all engineers to actively contribute to Mariana Deep. If you see something wrong, fix it!
+
+- **Typos and Minor Fixes**: Fix them immediately using the BookStack web interface. No review needed.
+- **Major Architectural Documentation**: Draft the documentation in a Page and request a review (via Slack or email link) from the Lead Engineer of that specific product before finalizing.
+- **Infrastructure Changes**: If you are modifying the Helm charts or Docker Compose configurations in this repository, please create a feature branch, test locally using Docker Compose, and open a standard Pull Request on GitHub.
+
+## Security & Data Persistence
+
+- **Public Access**: Explicitly disabled (`APP_PUBLIC=false`). Unauthenticated users cannot view any pages and will be immediately redirected to the login screen.
+- **User Management**: Open registration is disabled. Administrators manually provision access.
+- **Data Persistence**: In Kubernetes, Persistent Volume Claims (PVCs) ensure uploaded images and database state survive pod restarts. Locally, BookStack configuration and uploads are stored in the bind-mounted `./config` directory, while database data persists in the Docker-managed `bookstack_db_data` volume.

src/internal-docs/docker-compose.yml

@@ -0,0 +1,52 @@
+version: "3.8"
+
+services:
+  bookstack:
+    image: lscr.io/linuxserver/bookstack:24.05.2
+    container_name: bookstack
+    environment:
+      - PUID=1000
+      - PGID=1000
+      - TZ=UTC
+      - APP_NAME=${APP_NAME:-"Mariana Deep"}
+      - APP_URL=${APP_URL:-http://localhost:6875}
+      - APP_KEY=${APP_KEY:-}
+      - DB_HOST=bookstack_db
+      - DB_PORT=3306
+      - DB_USER=${DB_USER:-bookstack}
+      - DB_PASS=${DB_PASSWORD:-bookstack_secure_password}
+      - DB_DATABASE=${DB_DATABASE:-bookstackapp}
+      # Security & Access Control phase settings:
+      - APP_PUBLIC=${APP_PUBLIC:-false} # Disable public viewing by default
+    volumes:
+      - ./config:/config
+    ports:
+      - "6875:80"
+    restart: unless-stopped
+    depends_on:
+      - bookstack_db
+    networks:
+      - internal-docs-network
+
+  bookstack_db:
+    image: mariadb:10.6
+    container_name: bookstack_db
+    environment:
+      - TZ=UTC
+      - MYSQL_ROOT_PASSWORD=${DB_ROOT_PASSWORD:-root_secure_password}
+      - MYSQL_DATABASE=${DB_DATABASE:-bookstackapp}
+      - MYSQL_USER=${DB_USER:-bookstack}
+      - MYSQL_PASSWORD=${DB_PASSWORD:-bookstack_secure_password}
+    volumes:
+      - bookstack_db_data:/var/lib/mysql
+    restart: unless-stopped
+    networks:
+      - internal-docs-network
+
+networks:
+  internal-docs-network:
+    name: internal-docs-network
+    driver: bridge
+
+volumes:
+  bookstack_db_data:

src/internal-docs/k8s/Chart.yaml

@@ -0,0 +1,10 @@
+apiVersion: v2
+appVersion: "24.05.2"
+description: AirQo Internal Docs (Mariana Deep) Helm Chart
+name: airqo-internal-docs
+home: https://airqo.net
+version: 0.1.0
+maintainers:
+  - name: AirQo
+    email: support@airqo.net
+    url: https://airqo.net

src/internal-docs/k8s/templates/_helpers.tpl

@@ -0,0 +1,49 @@
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "internal-docs.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Create a default fully qualified app name.
+*/}}
+{{- define "internal-docs.fullname" -}}
+{{- if .Values.fullnameOverride }}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- $name := default .Chart.Name .Values.nameOverride }}
+{{- if contains $name .Release.Name }}
+{{- .Release.Name | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
+{{- end }}
+{{- end }}
+{{- end }}
+
+{{/*
+Create chart name and version as used by the chart label.
+*/}}
+{{- define "internal-docs.chart" -}}
+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Common labels
+*/}}
+{{- define "internal-docs.labels" -}}
+helm.sh/chart: {{ include "internal-docs.chart" . }}
+{{ include "internal-docs.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}
+
+{{/*
+Selector labels
+*/}}
+{{- define "internal-docs.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "internal-docs.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}

src/internal-docs/k8s/templates/configmap.yaml

@@ -0,0 +1,19 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ .Values.app.configmap }}
+  namespace: {{ .Values.app.namespace }}
+  labels:
+    {{- include "internal-docs.labels" . | nindent 4 }}
+data:
+  # BookStack Specific
+  APP_NAME: {{ .Values.env.APP_NAME | quote }}
+  APP_PUBLIC: {{ .Values.env.APP_PUBLIC | quote }}
+
+  # Shared Database Configuration (Used by BookStack container)
+  DB_USER: {{ .Values.env.DB_USER | quote }}
+  DB_DATABASE: {{ .Values.env.DB_DATABASE | quote }}
+
+  # MariaDB Specific (Used by MariaDB container)
+  MYSQL_USER: {{ .Values.env.DB_USER | quote }}
+  MYSQL_DATABASE: {{ .Values.env.DB_DATABASE | quote }}

src/internal-docs/k8s/templates/deployment-app.yaml

@@ -0,0 +1,60 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ .Values.app.name }}
+  namespace: {{ .Values.app.namespace }}
+  labels:
+    {{- include "internal-docs.labels" . | nindent 4 }}
+spec:
+  replicas: {{ .Values.replicaCount }}
+  selector:
+    matchLabels:
+      app: {{ .Values.app.label }}
+  template:
+    metadata:
+      labels:
+        app: {{ .Values.app.label }}
+    spec:
+      {{- with .Values.imagePullSecrets }}
+      imagePullSecrets:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      containers:
+        - name: {{ .Values.app.label }}
+          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
+          imagePullPolicy: {{ .Values.image.pullPolicy }}
+          ports:
+            - name: http
+              containerPort: {{ .Values.service.targetPort }}
+              protocol: TCP
+          env:
+            - name: DB_HOST
+              value: {{ .Values.dbApp.name }}
+            - name: APP_URL
+              value: {{ .Values.app.url | quote }}
+          envFrom:
+            - configMapRef:
+                name: {{ .Values.app.configmap }}
+            - secretRef:
+                name: {{ .Values.app.configmap }}-secret
+          volumeMounts:
+            - name: bookstack-config
+              mountPath: /config
+          resources:
+            {{- toYaml .Values.resources | nindent 12 }}
+      volumes:
+        - name: bookstack-config
+          persistentVolumeClaim:
+            claimName: {{ .Values.app.name }}-pvc
+      {{- with .Values.nodeSelector }}
+      nodeSelector:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.affinity }}
+      affinity:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.tolerations }}
+      tolerations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}