# Windows macOS and Linux

The same V2 source builds on a machine with Node.js 24 or newer, npm and Git. The main differences are installation, terminal syntax and private-directory permissions. This guide keeps those differences explicit so a Bash command is not mistaken for PowerShell and a local preview is not mistaken for a production service.

Use Node.js downloads and Git downloads for current official platform guidance. Choose an installer/build matching your operating system and CPU architecture. Do not assume an older distribution’s default Node package satisfies V2.

# Check the terminal, not only the installation screen

Open a fresh terminal after installing tools and run:

node --version
npm --version
git --version

Node should print v24 or a newer supported version. npm and Git should print versions without a command-not-found error. If the version is wrong, check which executable this terminal uses. Installing a new Node release can leave an older executable earlier in PATH.

You need write access to the chosen project folder. Installing dependencies in an unwritable location and compensating with administrator/root npm commands is not the intended workflow. Create a new directory in your own workspace first.

These are shell operations, not MarkStack configuration fields. Quote paths containing spaces; do not translate Unix chmod into a Windows security claim.

# Windows with PowerShell

Install Node using an appropriate official Windows installer or your approved version manager, and install Git for Windows. Close/reopen PowerShell after installation. In a directory where you may create a new checkout:

node --version
npm --version
git --version
git clone https://github.com/KineticEnforcer/MarkStackV2.git
Set-Location MarkStackV2
npm ci
npm test
npm run build
npm run serve

If PowerShell blocks npm.ps1, use npm.cmd for npm commands instead:

npm.cmd ci
npm.cmd test
npm.cmd run build
npm.cmd run serve

Do not disable the system-wide execution policy merely to follow this guide. A normal Command Prompt is another place to run ordinary Git/npm commands, but its directory/environment syntax is different from PowerShell. The Bash install script does not run as PowerShell syntax.

For a different preview port in this PowerShell session:

$env:MARKSTACK_PREVIEW_PORT = '3100'
npm.cmd run serve

Stop the server with Ctrl+C. The environment setting remains in that session; remove it deliberately if you want the default again:

Remove-Item Env:MARKSTACK_PREVIEW_PORT

A local private editor store can be selected with:

New-Item -ItemType Directory -Path "$HOME\private-markstack" -Force
$env:MARKSTACK_USERS_FILE = "$HOME\private-markstack\users.json"
npm.cmd run editor:create-admin -- --user admin
npm.cmd run editor

Restrict Windows directory permissions using your normal account/organization controls. Creating a directory is not proof that only the intended account can read it. Keep it outside static/, dist/ and any public web root.

# macOS with Terminal

Install a supported Node release and Git using official or organization-approved instructions. A version manager is acceptable when it actually selects Node 24+ in the terminal that runs the project. Open a new Terminal window, check versions, then:

git clone https://github.com/KineticEnforcer/MarkStackV2.git
cd MarkStackV2
npm ci
npm test
npm run build
npm run serve

Use pwd when you are unsure which checkout you are in. Do not install over an existing project folder or remove content to make a clone command succeed. Choose another target name or inspect the existing checkout.

For an alternate preview port in a Unix-style shell, a one-command setting is:

MARKSTACK_PREVIEW_PORT=3100 npm run serve

For private editor data used by several commands in the same session:

mkdir -p "$HOME/private-markstack"
chmod 700 "$HOME/private-markstack"
export MARKSTACK_USERS_FILE="$HOME/private-markstack/users.json"
npm run editor:create-admin -- --user admin
npm run editor

The hidden password prompt is part of account creation. Do not add a password argument to the command. A new shell does not automatically inherit settings from another terminal window.

# Linux

Install Node.js 24+ and Git using current official instructions or your approved package/version manager. Distribution package names and versions vary, so this guide does not prescribe one universal apt/dnf command that may install the wrong release.

Run the same clone/install/test/build/preview sequence as macOS in a normal writable workspace. Check command -v node, command -v npm and command -v git when a version does not match expectations. A shell version manager may not be available inside systemd; production service files need an actual supported executable path.

The Linux team service guide is a separate service setup. It is unnecessary for a local static reader. First prove the project runs interactively, then plan a dedicated service account, writable/private paths and HTTPS if a team editor is needed.

# Inspect the same result on every platform

Preview normally prints http://127.0.0.1:3000. Open it on the machine running the server. Loopback refers to that machine, not to a colleague’s laptop. Use an HTTP-served URL rather than opening files directly.

Check a home page, deep route, search result, copy button, theme and local image. Add the First site example, rebuild and verify /guides/hello/. A successful command exit is useful evidence, but the browser result is the actual reader check.

# Diagnose before repeating commands

• Command not found: Likely check: New terminal/PATH/tool installation; Do not do this blindly: Reinstall every tool without checking PATH
• Old Node version: Likely check: Selected executable/version-manager shell; Do not do this blindly: Assume installer success changed every process
• Permission denied: Likely check: Project and private-data ownership/access; Do not do this blindly: Run all project tools as root/admin
• Port in use: Likely check: Existing listener and deliberate new port; Do not do this blindly: Start multiple indistinguishable servers
• Git asks for access: Likely check: Repository visibility/account authentication; Do not do this blindly: Put a token/password in a public command

Linux Node.js 24.21.0 dependency/test/build and local account procedures were exercised here. Windows/macOS installers and shell sequences are instructions, not a claim of running those operating systems. When seeking help, include the actual OS, Node version, command and non-secret error text.