🐳 MdExplorer in Docker

Una singola immagine Docker (~1 GB) che fa girare MdExplorer su macOS, Linux e Windows senza installazione nativa, senza dipendenze .NET, senza configurazioni di sistema. Apri il browser e lo usi come una web app locale.

Image
ghcr.io/salaroglio/mdexplorer
Tag
latest · 0.1.1-preview
Dimensione
~1 GB
Porta
127.0.0.1:5000
Auth
Solo loopback (no LAN)
Licenza
AGPL-3.0
⚠️ Versione preview. Questa immagine Docker è alla sua prima iterazione pubblica. Funzionano: indexing, knowledge graph, Git, PlantUML, export, "apri in VS Code" con redirect host-side. Da sistemare: integrazione clipboard browser, alcuni casi di edit esterno con bind-mount Windows, qualche flusso di credenziali Git.

🍎 Avvio rapido — macOS macOS

Prerequisito: Docker Desktop per Mac installato e in esecuzione.

Apri il Terminale ed esegui questi comandi:

# Crea la cartella e scarica i due file di setup
mkdir mdexplorer && cd mdexplorer
curl -O https://www.mdexplorer.net/docker/docker-compose.yml
curl -O https://www.mdexplorer.net/docker/start.sh
chmod +x start.sh

# Avvia (apre automaticamente il browser quando MDE è pronto)
./start.sh

Al primo avvio Docker scarica l'immagine (~1 GB) e il container impiega pochi secondi per inizializzare il database. Lo script aspetta che MdExplorer risponda e poi apre Safari/Chrome su http://127.0.0.1:5000/client2/index.html.

📁 Dove finiscono i tuoi file: i progetti markdown vivono in mdexplorer/workspace/ sul tuo Mac. Puoi editarli sia da MdExplorer (nel browser) sia con VS Code, BBEdit o qualsiasi altro editor — il FileSystemWatcher rileva i cambiamenti esterni.

Comandi utili

# Fermare il container (mantiene i dati)
docker compose down

# Riavviare
./start.sh

# Aggiornare alla versione più recente
docker compose pull && docker compose up -d

# Vedere i log in tempo reale
docker compose logs -f

🐧 Avvio rapido — Linux Linux

Procedura identica a macOS. Lo script start.sh rileva automaticamente l'OS e usa xdg-open per il browser.

mkdir mdexplorer && cd mdexplorer
curl -O https://www.mdexplorer.net/docker/docker-compose.yml
curl -O https://www.mdexplorer.net/docker/start.sh
chmod +x start.sh
./start.sh

🪟 Avvio rapido — Windows Windows

Prerequisito: Docker Desktop per Windows con backend WSL2.

Apri PowerShell ed esegui:

# Crea la cartella e scarica i file di setup
mkdir mdexplorer; cd mdexplorer
Invoke-WebRequest -Uri https://mdexplorer.net/docker/docker-compose.yml -OutFile docker-compose.yml
Invoke-WebRequest -Uri https://mdexplorer.net/docker/start.ps1 -OutFile start.ps1

# Avvia
.\start.ps1

Lo script scrive automaticamente un file .env con il percorso assoluto della cartella workspace (su Windows è necessario per la funzione "Apri in VS Code"; PowerShell non propaga $PWD ai processi figli come fa bash su Unix).

🛠️ Cosa è incluso nell'immagine

  • MdExplorer Service (backend .NET 8 + frontend Angular)
  • Pandoc — export Word / HTML / EPUB
  • Graphviz + PlantUML jar — rendering diagrammi UML
  • OpenJDK 17 (per PlantUML)
  • Git + OpenSSH — operazioni repository
  • SQLite — storage embedded

🔒 Sicurezza & rete

Il container è raggiungibile solo dal browser sulla stessa macchina: il binding host è 127.0.0.1:5000:5000, Docker non pubblica la porta su nessuna interfaccia di rete. Stesso comportamento della versione desktop di MdExplorer.

⛔ NON cambiare il binding in 5000:5000 senza prima aggiungere autenticazione: MdExplorer non ha un sistema di login (è pensato come app personale single-user). Esporlo sulla LAN aziendale significa esporre tutti i tuoi documenti.

🤝 Open in VS Code — come funziona

Quando clicchi "Apri in editor" in MdExplorer dentro al container, il backend non può lanciare VS Code (è isolato). Invece:

  1. Il backend traduce il path container (/workspace/foo.md) nel path host (/Users/tu/mdexplorer/workspace/foo.md).
  2. Restituisce un URL vscode://file//Users/tu/.../foo.md.
  3. Il browser lo passa al sistema operativo.
  4. macOS / Windows / Linux lanciano VS Code nativo sul file giusto.

Funziona anche con IntelliJ IDEA se selezionato come IDE preferito.

🐛 Troubleshooting

"Cannot connect to the Docker daemon"

Docker Desktop non è in esecuzione. Avvialo e riprova.

Il browser si apre ma vedo "Connection refused"

Il container è ancora in inizializzazione. Aspetta qualche secondo e ricarica. Se persiste:

docker compose logs --tail 50

Modifico un file dall'host ma MdExplorer non lo vede Windows

Su Windows + WSL2, gli eventi inotify dei filesystem Windows non sempre si propagano nei container Linux. Workaround: tieni i progetti in una cartella WSL2 nativa, oppure aspetta che un altro evento triggerà la lettura.

Voglio cancellare tutto e ricominciare

docker compose down
rm -rf workspace data    # ATTENZIONE: cancella anche i tuoi .md
rm .env                  # solo su Windows
./start.sh

📦 Dettagli tecnici

← Torna ai download

🐳 MdExplorer on Docker

A single Docker image (~1 GB) that runs MdExplorer on macOS, Linux and Windows with no native install, no .NET dependencies, no system tweaks. Open your browser and use it as a local web app.

Image
ghcr.io/salaroglio/mdexplorer
Tag
latest · 0.1.1-preview
Size
~1 GB
Port
127.0.0.1:5000
Auth
Loopback only (no LAN)
License
AGPL-3.0
⚠️ Preview release. This is the first public iteration. Working: indexing, knowledge graph, Git, PlantUML, export, "Open in VS Code" via host-side redirect. Pending: browser clipboard integration, some external-edit cases with Windows bind-mounts, parts of the Git credential flow.

🍎 Quickstart — macOS macOS

Prerequisite: Docker Desktop for Mac installed and running.

Open Terminal and run:

# Create folder and download the two setup files
mkdir mdexplorer && cd mdexplorer
curl -O https://www.mdexplorer.net/docker/docker-compose.yml
curl -O https://www.mdexplorer.net/docker/start.sh
chmod +x start.sh

# Start (opens the browser automatically when MDE is ready)
./start.sh

On first run Docker pulls the image (~1 GB) and the container takes a few seconds to initialise its database. The script waits until MdExplorer responds, then opens Safari/Chrome on http://127.0.0.1:5000/client2/index.html.

📁 Where your files live: markdown projects sit in mdexplorer/workspace/ on your Mac. You can edit them either from MdExplorer (in the browser) or from VS Code, BBEdit, or any other editor — the FileSystemWatcher will pick up external changes.

Useful commands

# Stop the container (data is preserved)
docker compose down

# Start again
./start.sh

# Update to the latest version
docker compose pull && docker compose up -d

# Tail the logs
docker compose logs -f

🐧 Quickstart — Linux Linux

Same procedure as macOS. The start.sh script detects the OS and uses xdg-open for the browser.

mkdir mdexplorer && cd mdexplorer
curl -O https://www.mdexplorer.net/docker/docker-compose.yml
curl -O https://www.mdexplorer.net/docker/start.sh
chmod +x start.sh
./start.sh

🪟 Quickstart — Windows Windows

Prerequisite: Docker Desktop for Windows with the WSL2 backend.

Open PowerShell and run:

# Create folder and download setup files
mkdir mdexplorer; cd mdexplorer
Invoke-WebRequest -Uri https://mdexplorer.net/docker/docker-compose.yml -OutFile docker-compose.yml
Invoke-WebRequest -Uri https://mdexplorer.net/docker/start.ps1 -OutFile start.ps1

# Start
.\start.ps1

The script writes a .env file with the absolute path to the workspace folder (needed on Windows for the "Open in VS Code" feature — PowerShell does not propagate $PWD to child processes like bash does on Unix).

🛠️ What's inside the image

  • MdExplorer Service (.NET 8 backend + Angular frontend)
  • Pandoc — Word / HTML / EPUB export
  • Graphviz + PlantUML jar — UML diagram rendering
  • OpenJDK 17 (for PlantUML)
  • Git + OpenSSH — repository operations
  • SQLite — embedded storage

🔒 Security & networking

The container is only reachable from the browser on the same machine: the host binding is 127.0.0.1:5000:5000, Docker does not publish the port on any network interface. Same posture as the desktop version of MdExplorer.

⛔ Do NOT change the binding to 5000:5000 without first adding authentication: MdExplorer has no login system (it's designed as a personal single-user app). Exposing it on the corporate LAN means exposing all of your documents.

🤝 "Open in VS Code" — how it works

When you click "Open in editor" inside the containerised MdExplorer, the backend can't launch VS Code (it's isolated). Instead:

  1. Backend translates the container path (/workspace/foo.md) into the host path (/Users/you/mdexplorer/workspace/foo.md).
  2. Returns a vscode://file//Users/you/.../foo.md URL.
  3. The browser hands it off to the OS.
  4. macOS / Windows / Linux launches native VS Code on the right file.

Works with IntelliJ IDEA too if you select it as the project's preferred IDE.

🐛 Troubleshooting

"Cannot connect to the Docker daemon"

Docker Desktop isn't running. Start it and retry.

Browser opens but I get "Connection refused"

The container is still starting up. Wait a few seconds and refresh. If it persists:

docker compose logs --tail 50

I edit a file from the host but MdExplorer doesn't notice Windows

On Windows + WSL2, inotify events from Windows filesystems don't always propagate into Linux containers. Workaround: keep your projects in a WSL2-native folder, or wait for another event to trigger a re-read.

I want to wipe everything and start over

docker compose down
rm -rf workspace data    # WARNING: this also deletes your .md files
rm .env                  # Windows only
./start.sh

📦 Technical details

← Back to downloads