[PR-23781] Migrate docs to Jenkins (#358)

Co-authored-by: Bohdan Zhuravel <[email protected]>

Author: en-ver

.circleci/config.yml

@@ -6,10 +6,12 @@ executors:
       - auth:
           username: $DOCKERHUB_USERNAME
           password: $DOCKERHUB_ACCESS_TOKEN
-        image: cimg/python:3.12
+        image: cimg/python:3.13
+        environment:
+          ENVIRONMENT: production
 
 orbs:
-  python: circleci/python@2.1.1
+  python: circleci/python@3.0.0
 
 jobs:
   build:
@@ -18,21 +20,15 @@ jobs:
     steps:
       - checkout
 
-      - python/install-packages:
-          app-dir: ~/project
+      - python/install-packages
 
       - run:
           name: Build documentation
-          command: sphinx-build -nW -b html -d build/doctrees source build/html
+          command: sphinx-build -nW -b dirhtml -d build/doctrees source build/html
 
 workflows:
   workflow:
     jobs:
       - build:
           context:
             - org-global
-          filters:
-            branches:
-              ignore:
-                - gh-pages
-                - /.*-gh-pages/

.env.template

@@ -0,0 +1,10 @@
+# The port to use to populate the documentation on your local machine or server
+LOCAL_PORT=8080
+
+# Possible values: development, staging, production
+ENVIRONMENT=development
+
+# Base urls used for the canonical urls compilation
+DEVELOPMENT_HOST=localhost
+STAGING_HOST=staging-docs.talkable.com
+PRODUCTION_HOST=docs.talkable.com

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,9 +1,5 @@
 <!--- Provide a general summary of your changes in the Title above -->
 
-## Demo
-<!--- Please provide a link to a demo -->
-https://deploy-preview-{{id}}--talkable-docs.netlify.app/
-
 ## Related Stories
 <!--- If this pull request is related to JIRA story, please link to the story here -->
 [![](http://proxies.talkable.com/talkable/PR-1234)](https://talkable.atlassian.net/browse/PR-1234)

.gitignore

@@ -1,7 +1,19 @@
+# IDE
+.idea
+.vscode
+
+# Local
+*.log
+.env
+
+# Sphinx
+_build
+
+# Python
+.venv
+__pycache__
+
+# Ruby
 /build
 /.bundle
 Gemfile.lock
-source/_static/test
-.pivotalrc
-.idea
-*.log

.ruby-gemset

@@ -0,0 +1,14 @@
+FROM python:3.13-alpine3.21
+
+# Install dependencies
+WORKDIR /docs
+ADD requirements.txt /docs
+RUN python3 -m pip install -r requirements.txt
+
+CMD if [ "$ENVIRONMENT" = "development" ]; then \
+        echo "Running Sphinx in Development mode"; \
+        sphinx-autobuild -b dirhtml /docs/source /docs/_build; \
+    else \
+        echo "Running Sphinx in Staging/Production mode"; \
+        sphinx-build -b dirhtml /docs/source /docs/_build; \
+    fi

.ruby-version

@@ -0,0 +1,93 @@
+## Overview
+
+The Talkable documentation stack is a containerized system that uses Docker to simplify deployment and management. It is designed to generate, serve, and manage static documentation across multiple environments, such as staging and production.
+
+## Key Features
+
+1. **Containerized Components**:
+   
+   - **Nginx**: Handles HTTP requests, serves static HTML files, manages URL redirection, and dynamically serves environment-specific `robots.txt` files.
+   - **Sphinx Autobuilder**: Generates static HTML files from source documentation and stores them in a persistent volume shared with Nginx.
+
+2. **Environment-Specific Behavior**:
+   
+   - Configured via a `.env` file for flexibility.
+   - Supports dynamic environment-specific behavior, such as serving different `robots.txt` files based on the `ENVIRONMENT` variable.
+
+3. **Efficient Architecture**:
+   
+   - Deployed on Amazon AWS Virtual Private Servers (VPS) with an AWS load balancer directing user traffic to the appropriate environment.
+   - Sphinx generates content on a persistent volume that Nginx serves directly.
+
+## Deployment Process
+
+### Prerequisites
+
+- Ensure Docker and Docker Compose are installed on the target VPS.
+- Clone the repository containing the stack configuration.
+
+### Steps
+
+1. **Clone the Repository**:
+   
+   ```bash
+   git clone [email protected]:talkable/talkable-docs.git
+   ```
+
+2. **Switch to the Appropriate Branch**:
+   
+   - Use the `master` branch for production.
+   
+      ```bash
+      git checkout master
+      ```
+   
+   - Use the `staging` branch for staging.
+   
+      ```bash
+      git checkout staging
+      ```
+
+3. **Create and Configure the `.env` File**:
+   
+   - Copy `.env.template` to `.env`:
+   
+     ```bash
+     cp .env.template .env
+     ```
+   
+   - Update the following variables:
+  
+     - **`ENVIRONMENT`**: Set to `development`, `staging`, or `production`.
+     - **`LOCAL_PORT`**: Adjust if the default port (`8080`) is already in use.
+     - Leave `_HOST` variables unchanged unless domain names for staging or production servers are updated.
+
+4. **Deploy the Stack**:
+   
+   ```bash
+   docker compose up -d --build
+   ```
+
+## Environment-Specific Configuration
+
+### Handling `robots.txt`
+
+- The repository includes separate `robots.txt` files for each environment.
+- The correct file is dynamically selected based on the `ENVIRONMENT` variable and mapped to the container:
+  
+  ```yaml
+  volumes:
+    - ./nginx/robots/${ENVIRONMENT}.txt:/var/www/robots.txt
+  ```
+
+- Nginx serves the file at `/var/www/robots.txt` in response to `robots.txt` requests.
+
+## Persistent Data Sharing
+
+- **Static HTML Files**:
+  - Generated by Sphinx and stored in a shared volume.
+  - Served by Nginx without regeneration.
+
+- **Volume Management**:
+  - Shared volumes allow seamless access and updates between containers.
+  - Ensures efficient and consistent behavior across environments.