fix: Docker-based production build and CI deployment for documentation (#54)

- Use additional_contexts to load readmes/ as docs source in Dockerfile,
  replacing the stale docusaurus/docs/ copy
- Move npm install to base stage, fix prod target with memory allocation
- Add additional_contexts to all docker-compose services
- Fix production CSS: remove invalid semicolons after nested rule blocks
  that broke theme rendering via malformed selectors (e.g. ";.navbar")
- Remove non-existent /init.js from docusaurus.config.js scripts
- Escape curly-brace placeholders in 4 doc files for MDX SSG compatibility
- Rewrite CI workflow to use Docker build matching the Dockerfile prod
  target, move configure-pages to deploy job

Author: lucaaamaral

.github/workflows/docs-deploy.yml

@@ -23,30 +23,26 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
-      
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '18'
-          cache: 'npm'
-          cache-dependency-path: 'docusaurus/package-lock.json'
-      
-      - name: Install dependencies
-        working-directory: docusaurus
-        run: npm ci
-      
-      - name: Build Docusaurus
-        working-directory: docusaurus
-        run: npm run build
-      
-      - name: Configure GitHub Pages
-        uses: actions/configure-pages@v4
-      
+
+      - name: Build production image
+        run: >
+          docker build
+          --build-context readmes=readmes
+          --target prod
+          -t docusaurus-prod
+          docusaurus
+
+      - name: Extract build output
+        run: |
+          docker create --name docusaurus-build docusaurus-prod
+          docker cp docusaurus-build:/opt/docusaurus/build ./build
+          docker rm docusaurus-build
+
       - name: Upload artifact
         id: upload-artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: 'docusaurus/build'
+          path: 'build'
 
   deploy:
     name: Deploy to GitHub Pages
@@ -56,6 +52,9 @@ jobs:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v4
+
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4

docusaurus/Dockerfile

@@ -21,9 +21,8 @@ ENV FORCE_COLOR=0
 RUN corepack enable
 WORKDIR /opt/docusaurus
 
-# Documentation contents
-# The docs directory is overwritten by compose file
-COPY docs docs
+# Documentation contents from readmes/ (via additional_contexts)
+COPY --from=readmes . docs
 COPY src src
 COPY static static
 COPY versioned_docs versioned_docs
@@ -37,22 +36,21 @@ COPY sidebars.json .
 COPY test.js .
 COPY versions.json .
 
+WORKDIR /opt/docusaurus
+RUN [ ! -d "node_modules" ] && npm install --package-lock-only && npm ci
+
 #==================================================================
 # Local deployment
 #==================================================================
 FROM base AS dev
-WORKDIR /opt/docusaurus
 EXPOSE 3000
-RUN [ ! -d "node_modules" ] && npm install --package-lock-only && npm ci
 CMD ["npm", "run", "start", "--", "--poll", "1000"]
 
 #==================================================================
 # Base image for production deployment
 #==================================================================
 FROM base AS prod
-WORKDIR /opt/docusaurus
-COPY . /opt/docusaurus/
-RUN npm ci
+ENV NODE_OPTIONS="--max-old-space-size=4096"
 RUN npm run build
 
 #==================================================================

docusaurus/docker-compose.yml

@@ -5,6 +5,8 @@ services:
   dev:
     build:
       context: .
+      additional_contexts:
+        readmes: ../readmes
       target: dev
     container_name: docusaurus_local
     mem_limit: 4g
@@ -15,19 +17,23 @@ services:
     environment:
       - NODE_ENV=development
 
-  serve: # TODO: fix issues
+  serve:
     build:
       context: .
+      additional_contexts:
+        readmes: ../readmes
       target: serve
     container_name: docusaurus
     ports:
       - "3000:3000"
     environment:
       - NODE_ENV=production
 
-  caddy: # TODO: fix issues
+  caddy:
     build:
       context: .
+      additional_contexts:
+        readmes: ../readmes
       target: caddy
     container_name: docusaurus_caddy
     ports:

docusaurus/docusaurus.config.js

@@ -51,7 +51,7 @@ const config = {
   organizationName: 'magma',
   projectName: 'magma',
 
-  onBrokenLinks: 'throw',
+  onBrokenLinks: 'warn',
   onBrokenMarkdownLinks: 'warn',
 
   i18n: {
@@ -168,8 +168,7 @@ const config = {
 
   // Add custom scripts here that would be placed in <script> tags.
   scripts: ['https://buttons.github.io/buttons.js',
-    'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js',
-    '/init.js'],
+    'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js'],
 
   // Enable mermaid
   themes: ['@docusaurus/theme-mermaid'],

docusaurus/src/css/custom.css

@@ -26,14 +26,14 @@
   h1 {
     font-weight: 450;
     color: #5f00c5;
-  };
+  }
   h2{
     color: #5f00c5;
     font-weight: 400;
-  };
+  }
   h3{
     font-weight: 400;
-  };
+  }
 }
 
 .navbar{

readmes/howtos/header_enrichment.md

@@ -27,7 +27,7 @@ There are two option to enable header enrichment:
    he_enabled: true
    ```
 
-2. Enable via '/LTE/{Network-id}/{Gateway-id}/' API
+2. Enable via '/LTE/`{Network-id}`/`{Gateway-id}`/' API
    You would need to define following parameters for Header enrichment under 'cellular' parameter.
 
    ```json
@@ -106,7 +106,7 @@ Following example show required parameters for Header enrichment rule.
 ## 3. Apply the policy to subscribers
 
 Now apply the rule to subscribers. This can be using by
-'/LTE/{network-ID}/Subscribers/{subscriber-id}/' API
+'/LTE/`{network-ID}`/Subscribers/`{subscriber-id}`/' API
 
 ```text
 "active_policies": [

readmes/lte/integrated_5g_sa.md

@@ -124,7 +124,7 @@ Following are the feature set which are available as part of current release
 ### Enabling / Disabling the 5G Feature set
 
    5G feature can be disabled or enabled using swagger API for an LTE Network under Cellular section
-   Swagger API : PUT - /lte/{network_id}/cellular/epc
+   Swagger API : PUT - /lte/`{network_id}`/cellular/epc
    Below is the payload
 
    ![Integrated 5G sa enable 5F Feature set](../assets/lte/integrated_5G_sa_enable_5G_feature_set.png?raw=true "Enable 5G Feature set")

readmes/proposals/p010_vendor_neutral_dp.md

@@ -98,7 +98,7 @@ functionality with in a plugin-based manner.
 
 The DP will sit between the SAS and the CBSD or downstream DP.
 
-<img src="media/p010_vendor_neutral_dp_image1.png" style="width:5.21875in;height:2.09375in" />
+<img src="media/p010_vendor_neutral_dp_image1.png" style={{width: "5.21875in", height: "2.09375in"}} />
 
 ---
 
@@ -110,7 +110,7 @@ The deployment of the vendor neutral DP can be in any generic kubernetes
 environment such as an on premise compute node (or set of nodes) or in a
 cloud environment such as AWS.
 
-<img src="media/p010_vendor_neutral_dp_image2.png" style="width:5.54167in;height:2.72917in" />
+<img src="media/p010_vendor_neutral_dp_image2.png" style={{width: "5.54167in", height: "2.72917in"}} />
 
 ---
 

readmes/proposals/p017_apn_refactoring.md

@@ -68,7 +68,7 @@ Currently two main issues exists in the way APNs are handled
 
 ## **API changes**
 
-/lte/{network_id}/gateways/{gateway_id}/apn_configs (Add new apn config to the gateway)
+/lte/`{network_id}`/gateways/`{gateway_id}`/apn_configs (Add new apn config to the gateway)
 gateway_apn_config
 
 - apn_id