ost2pst/README.md

OST to PST / MBOX Converter

A self-contained web app that converts Outlook .ost files to PST or MBOX (ZIP) format, including contacts as vCard .vcf files. Runs entirely locally — no cloud, no data leaves your machine.

Supports linux/amd64 (x86 servers, most PCs) and linux/arm64 (Apple M-series, Raspberry Pi, AWS Graviton).

---

🚀 Quickest start — pull from Docker Hub

# Pull and run (no source code needed)
docker run -d \
  --name ost2pst \
  -p 3000:3000 \
  -v $(pwd)/converted:/app/converted \
  yourname/ost2pst:latest

# Open in browser
open http://localhost:3000

Or with Compose (just a docker-compose.yml file needed):

DOCKER_IMAGE=yourname/ost2pst:latest docker compose up -d

---

📤 Publishing to Docker Hub (multi-arch)

Option A — Local build & push (one-time or on-demand)

chmod +x build-multiarch.sh
./build-multiarch.sh yourDockerHubUsername           # pushes :latest
./build-multiarch.sh yourDockerHubUsername v1.0.0    # pushes :v1.0.0 + :latest

This uses docker buildx to build native amd64 and arm64 layers simultaneously and push a multi-arch manifest to Hub.

Option B — Automated via GitHub Actions (CI/CD)

1. Push this repo to GitHub.
2. Go to Settings → Secrets and variables → Actions and add:
   • DOCKERHUB_USERNAME — your Docker Hub username
   • DOCKERHUB_TOKEN — a Docker Hub access token
3. Every push to main publishes :latest; every v*.*.* tag also publishes versioned tags.

---

Requirements

Method	What you need
Docker (recommended)	Docker Desktop or Docker Engine
Raw Node.js	Node.js ≥ 18, Java JRE ≥ 11

---

🐳 Option A — Docker (recommended, zero setup)

Everything — Java, Node.js, and the Aspose library — is bundled inside the image.

One-liner (uses run.sh)

./run.sh

Then open http://localhost:3000 in your browser.

Converted files are saved to ./converted/ on your host automatically.

---

With Docker Compose

# Build & start
docker compose up -d --build

# Open the app
open http://localhost:3000      # macOS
xdg-open http://localhost:3000  # Linux

# Stop
docker compose down

---

Plain Docker commands

# Build
docker build -t ost2pst:latest .

# Run
docker run -d \
  --name ost2pst \
  -p 3000:3000 \
  -v $(pwd)/converted:/app/converted \
  ost2pst:latest

# Stop
docker stop ost2pst && docker rm ost2pst

---

Change the port

PORT=8080 ./run.sh
# or
docker run -d -p 8080:3000 -v $(pwd)/converted:/app/converted ost2pst:latest

---

⚙️ Option B — Run directly with Node.js + Java

Use this if you already have Node.js and a Java JRE installed locally.

# Install Node dependencies
npm install

# Start the server
node server.js

Open http://localhost:3000.

Requirements:

• Node.js ≥ 18
• Java JRE ≥ 11 (java must be on $PATH)
• The file aspose-email-24.12-jdk16.jar must be in the project root (already included)

---

📦 Distributing to another machine

To move the whole app:

# On the source machine — package everything
tar -czf ost2pst.tar.gz \
  Dockerfile docker-compose.yml run.sh \
  server.js Convert.java package.json package-lock.json \
  aspose-email-24.12-jdk16.jar public/

# On the target machine
tar -xzf ost2pst.tar.gz
cd ost2pst
./run.sh          # or: docker compose up -d --build

Or share the Docker image directly:

# Save image to a file
docker save ost2pst:latest | gzip > ost2pst-image.tar.gz

# Load on another machine (no build needed)
docker load < ost2pst-image.tar.gz
docker run -d -p 3000:3000 -v $(pwd)/converted:/app/converted ost2pst:latest

---

How it works

Format	Output	Use case
PST	.pst file	Direct import into Outlook; Google Workspace migration via GWMMO
MBOX (ZIP)	.zip with .mbox files + .vcf contacts	Thunderbird, Apple Mail, or Gmail import
MBOX + Merged VCF	.zip with a single contacts.vcf	Drag-and-drop import into contacts.google.com

Conversions run entirely in-process using the Aspose.Email for Java library. No data is sent to any external server.

---

Project structure

ost2pst/
├── Dockerfile                    # Container definition
├── docker-compose.yml            # Compose config
├── run.sh                        # One-command launcher
├── server.js                     # Express backend + SSE streaming
├── Convert.java                  # Java conversion engine
├── aspose-email-24.12-jdk16.jar  # Aspose library (bundled)
├── package.json
└── public/
    ├── index.html
    ├── style.css
    └── app.js