feat: initial commit — OST to PST/MBOX converter with Docker support

README.md

@@ -0,0 +1,193 @@
+# 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
+
+```bash
+# 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):
+```bash
+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)
+```bash
+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](https://hub.docker.com/settings/security)
+3. Every push to `main` publishes `:latest`; every `v*.*.*` tag also publishes versioned tags.
+
+---
+
+## Requirements
+
+| Method | What you need |
+|---|---|
+| **Docker (recommended)** | [Docker Desktop](https://www.docker.com/products/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`)
+```bash
+./run.sh
+```
+Then open **http://localhost:3000** in your browser.
+
+Converted files are saved to `./converted/` on your host automatically.
+
+---
+
+### With Docker Compose
+```bash
+# 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
+```bash
+# 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
+```bash
+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.
+
+```bash
+# 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:
+
+```bash
+# 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:
+```bash
+# 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](https://contacts.google.com) |
+
+Conversions run entirely in-process using the [Aspose.Email for Java](https://products.aspose.com/email/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
+```