Orchestrator/shared/OrgMyLife/DEPLOY.md

# Deployment Guide — OrgMyLife on a VPS

## Architecture (Multi-Machine)

```
┌─────────────────┐     ┌──────────────────────────────┐
│  Your Laptop    │     │  VPS (e.g., IONOS)           │
│  ─────────────  │     │  ──────────────────          │
│  AI-Orchestrator│────▶│  OrgMyLife (Docker)           │
│  (polls API)    │     │  PostgreSQL (Docker)          │
│                 │     │  https://api.knie.email       │
└─────────────────┘     └──────────────────────────────┘
        │                           │
        │                           │ syncs with
        ▼                           ▼
┌─────────────────┐     ┌──────────────────────────────┐
│  Other machines │     │  Nextcloud (existing)         │
│  (API clients)  │     │  Calendar + ToDo persistence  │
└─────────────────┘     └──────────────────────────────┘
```

## Option 1: IONOS VPS (Recommended — 3-5€/month)

### 1. Get a VPS

- Go to IONOS Cloud or VPS section
- Pick the smallest Linux VPS (1 vCPU, 1GB RAM is enough)
- Choose Ubuntu 22.04 or Debian 12
- Note the IP address

### 2. Point your domain

Since you own `andreknie.de`, add a DNS record:
- `A` record: `api.andreknie.de` → your VPS IP (`217.160.174.2`)

### 3. SSH into the VPS and install Docker

```bash
ssh root@YOUR_VPS_IP

# Install Docker
curl -fsSL https://get.docker.com | sh

# Install docker-compose
apt install docker-compose-plugin
```

### 4. Deploy OrgMyLife

```bash
# Clone your repo
git clone https://github.com/DoctoDre/OrgMyLife.git
cd OrgMyLife

# Create .env with your real credentials
cp .env.example .env
nano .env
# Fill in:
#   POSTGRES_PASSWORD=<strong random password>
#   API_SECRET=<strong random token for orchestrator auth>
#   NEXTCLOUD_URL, NEXTCLOUD_USERNAME, NEXTCLOUD_PASSWORD
#   IMAP_SERVER, EMAIL_USERNAME, EMAIL_PASSWORD

# Start everything
docker compose up -d

# Check it's running
docker compose logs -f app
```

### 5. Add HTTPS with Caddy (reverse proxy)

```bash
# Install Caddy
apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | tee /etc/apt/sources.list.d/caddy-stable.list
apt update && apt install caddy
```

Create `/etc/caddy/Caddyfile`:
```
api.andreknie.de {
    reverse_proxy localhost:8000
}
```

```bash
systemctl restart caddy
```

Caddy automatically gets a Let's Encrypt certificate. Your API is now at `https://api.andreknie.de`.

### 6. Configure AI-Orchestrator on your machines

Update `WORKFLOW.md` on any machine:
```yaml
tracker:
  kind: orgmylife
  endpoint: https://api.andreknie.de
  api_key: $ORGMYLIFE_API_SECRET
```

Set the env var:
```bash
export ORGMYLIFE_API_SECRET=<same token you put in .env on the VPS>
```

---

## Option 2: Run Locally with Docker (No Server Needed)

If you just want multi-machine via your home network or Tailscale:

```bash
cd OrgMyLife

# Add to your .env:
# POSTGRES_PASSWORD=localdev
# API_SECRET=  (empty = no auth, fine for local)

docker compose up -d
```

Access from other machines on your network at `http://YOUR_IP:8000`.

For access outside your network without a VPS, use **Tailscale** (free):
- Install Tailscale on all your machines
- Access OrgMyLife at `http://your-tailscale-ip:8000`

---

## Option 3: IONOS Managed Domain Only (No VPS)

If you really don't want a VPS yet, you can use a free tier service:

- **Railway.app** — free tier, deploy from GitHub, auto-HTTPS
- **Render.com** — free tier with PostgreSQL
- **Fly.io** — free tier, deploy Docker containers

These all support Docker and can connect to your `knie.email` domain via CNAME records.

---

## Nextcloud as Persistence Layer

Regardless of where OrgMyLife runs, Nextcloud stays the durable backend:

1. OrgMyLife syncs tasks FROM Nextcloud (import)
2. OrgMyLife syncs changes BACK to Nextcloud (two-way)
3. If OrgMyLife goes down, your tasks are still in Nextcloud
4. If you rebuild OrgMyLife, just re-sync from Nextcloud

This means Nextcloud is your backup and your mobile access (Nextcloud Tasks app on phone).

---

## Periodic Sync (Cron)

Add automatic syncing so OrgMyLife stays fresh:

```bash
# Add to crontab on the VPS (or as a Docker healthcheck)
# Sync every 5 minutes
*/5 * * * * curl -s -X POST http://localhost:8000/api/sync/nextcloud-todo
*/5 * * * * curl -s -X POST http://localhost:8000/api/sync/email
```

Or add a background scheduler inside the app (future enhancement).

---

## Security Checklist

- [ ] Strong `POSTGRES_PASSWORD` (use `openssl rand -hex 32`)
- [ ] Strong `API_SECRET` (use `openssl rand -hex 32`)
- [ ] HTTPS enabled (Caddy handles this automatically)
- [ ] Firewall: only ports 80, 443, 22 open on VPS
- [ ] Don't expose PostgreSQL port (5432) to the internet
- [ ] Keep `.env` out of git (already in .gitignore)