MarkdownPlusPlus/wiki/Installation.md

Installation & Deployment Guide

This page provides detailed installation, setup, and deployment guides for Markdown Viewer across all supported platforms.

---

Table of Contents

• System Requirements
• Option 1: Docker Container (Recommended)
• Option 2: Docker Compose Setup
• Option 3: Self-Hosted Static Web Server
• Option 4: Neutralinojs Desktop Application
• Air-Gapped & Offline Isolation Configuration

---

System Requirements

Web & Container Deployments

• Modern Web Browsers: Google Chrome 90+, Mozilla Firefox 90+, Microsoft Edge 90+, Apple Safari 15+. Note that PWA and Service Worker features require HTTPS or a localhost origin for security enforcement.
• Docker Daemon: Docker Engine 20.10+ (for Docker container deployment).
• System Resources: Minimum 512 MB RAM, 100 MB disk space.

Desktop Application Compilation

• Operating Systems: Windows 10+ (x64), Ubuntu 20.04+ (x64 / ARM64), macOS 11+ (Universal Apple Silicon/Intel).
• Node.js Runtime Environment: v16.0.0 or later (includes npm package manager).
• System Resources: Minimum 256 MB RAM, 50 MB disk space.

---

Option 1: Docker Container (Recommended)

Deploy the application using the official Docker image hosted on the GitHub Container Registry (GHCR).

Running the Container

Execute the following command to start a detached container that redirects host port 8080 to container port 80:

docker pull ghcr.io/thisis-developer/markdown-viewer:sha-15eafb0
docker run -d \
  --name markdown-viewer \
  -p 8080:80 \
  --restart unless-stopped \
  ghcr.io/thisis-developer/markdown-viewer:sha-15eafb0

Open http://localhost:8080 in your browser.

Adjusting Ports

To map the application to a different port (such as 9000), modify the left side of the -p parameter:

docker pull ghcr.io/thisis-developer/markdown-viewer:sha-15eafb0
docker run -d \
  --name markdown-viewer \
  -p 9000:80 \
  --restart unless-stopped \
  ghcr.io/thisis-developer/markdown-viewer:sha-15eafb0

Image Tags

Tag Name	Production Ready	Target Source Branch	Target Architecture
latest	Yes (Stable Release)	main branch (Release tag)	linux/amd64, linux/arm64
main	No (Development)	main branch (Commit updates)	linux/amd64, linux/arm64
<commit-sha>	Pinned	Specific Git commit hash	linux/amd64, linux/arm64

---

Option 2: Docker Compose Setup

For local deployments and multi-container environments, use Docker Compose.

1. Clone the Codebase

git clone https://github.com/ThisIs-Developer/Markdown-Viewer.git
cd Markdown-Viewer

2. Launch the Application

Start the container using Compose:

docker compose up -d

3. Verify Container Status

Confirm the container is running:

docker compose ps

4. Stop the Container

docker compose down

Default docker-compose.yml Configuration

services:
  markdown-viewer:
    image: ghcr.io/thisis-developer/markdown-viewer:sha-15eafb0
    container_name: markdown-viewer
    ports:
      - "8080:80"
    restart: unless-stopped

To build a local image instead of pulling the published container, update the image field with a build directive:

services:
  markdown-viewer:
    build: .
    container_name: markdown-viewer
    ports:
      - "8080:80"
    restart: unless-stopped

---

Option 3: Self-Hosted Static Web Server

Because Markdown Viewer is a fully client-side application, you can serve it from any static web server to serve index.html on localhost (127.0.0.1) by copying index.html, script.js, preview-worker.js, styles.css, sw.js, and the assets/ folder.

Clone the Repository

git clone https://github.com/ThisIs-Developer/Markdown-Viewer.git
cd Markdown-Viewer

Serving with Python (Built-in Web Server)

Run the following command in the repository root to serve the project on localhost:

python3 -m http.server 8080

Serving with Node.js

Run the following command in the repository root to serve the project on localhost:

npx serve . -p 8080

Once started, the application is accessible at http://localhost:8080 or http://127.0.0.1:8080.

Serving with Nginx

Copy the project assets to Nginx's HTML folder:

cp -r . /usr/share/nginx/html/

[!WARNING] Opening the index.html file directly in a browser via the file:// protocol may fail due to browser security restrictions (CORS) that block Web Workers and Service Workers from running locally. Always serve the files using a local web server.

---

Option 4: Neutralinojs Desktop Application

Markdown Viewer can also run as a native desktop application powered by Neutralinojs.

Downloading Pre-Built Executables

Download the binary for your platform from the GitHub Releases Page:

• Windows: markdown-viewer-win_x64.exe
• Linux: markdown-viewer-linux_x64
• Linux ARM (Raspberry Pi): markdown-viewer-linux_arm64
• macOS (Apple Silicon/Intel): markdown-viewer-mac_universal

Building the Desktop Executable from Source

Follow these steps to build the binaries locally:

1. Navigate to the desktop application folder:

   cd desktop-app
   

2. Install dependencies:

   npm install
   

3. Download Neutralino framework binaries:

   node setup-binaries.js
   

4. Copy files from the project root into the desktop resource folder:

   node prepare.js
   

5. Compile the executable:

   # Build single-file embedded Windows binary
   npm run build
       
   # Build portable distribution zip files for all platforms
   npm run build:portable
   

---

Air-Gapped & Offline Isolation Configuration

By default, the application loads large rendering dependencies (like MathJax and Mermaid) from external CDNs. In secure, offline, or air-gapped environments, these remote scripts will fail to load.

Setting Up a Fully Offline Build:

1. Download the required JavaScript dependencies (see Configuration for URLs) and save them to a local directory (e.g., js/libs/).
2. Update the <script> and <link> tags in index.html to reference your local asset paths.
3. Synchronize the desktop app folder by running node prepare.js.
4. Rebuild your Docker image or desktop application.