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

```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
```