Ehsan/DEPLOYMENT.md

# Deployment: Replit → Gitea → Mac Mini (Docker)

This project is developed on **Replit** and self-hosted on a **Mac Mini** using
Docker. **Gitea** is the central Git repository. Nothing deploys directly from
Replit, and GitHub is not used.

```
Replit (dev)  ──push──▶  Gitea (central repo)  ──pull──▶  Mac Mini  ──▶  Docker redeploy
```

- **Default branch:** `main`
- **Git remote name (everywhere):** `gitea`

---

## What's in this repo

| File | Runs on | Purpose |
|------|---------|---------|
| `scripts/push-to-gitea.sh` | Replit | Push `main` to the `gitea` remote |
| `deploy.sh` | Mac Mini | Pull `main`, then rebuild & restart Docker |
| `docker-compose.yml` | Mac Mini | Defines the `web` + `api` services |
| `Dockerfile.web` | Mac Mini | Builds the SPA, serves it via nginx (+ `/api` proxy) |
| `Dockerfile.api` | Mac Mini | Builds & runs the Express API server |
| `docker/nginx.conf` | Mac Mini | Static serving + reverse proxy to the API |

---

## One-time setup

### 1. On Replit — add the `gitea` remote

The Gitea repo URL is provided later. Add it once (HTTPS with a token, or SSH):

```bash
# HTTPS (token embedded) — simplest for a headless push
git remote add gitea https://<user>:<token>@<gitea-host>/<owner>/<repo>.git

# …or SSH
git remote add gitea git@<gitea-host>:<owner>/<repo>.git
```

Verify:

```bash
git remote -v   # should list 'gitea'
```

### 2. On the Mac Mini — clone the repo from Gitea

```bash
git clone -b main https://<gitea-host>/<owner>/<repo>.git ehsan
cd ehsan
# Make sure the remote is named 'gitea' (clone names it 'origin' by default):
git remote rename origin gitea   # only if needed
chmod +x deploy.sh
```

Requirements on the Mac Mini: **Docker Desktop** (or Docker Engine) with the
`docker compose` plugin. On Apple Silicon, the images build for `linux/amd64`
and run under Rosetta/emulation automatically.

---

## Everyday workflow

### A. Push from Replit

Commit your changes (via the Replit Git pane), then:

```bash
./scripts/push-to-gitea.sh
```

(Or directly: `git push gitea main`.)

### B. Redeploy on the Mac Mini

```bash
./deploy.sh
```

`deploy.sh` will, in order:

1. `git pull gitea main`
2. `docker compose down` (stop current containers)
3. `docker compose build` (rebuild images)
4. `docker compose up -d` (start again)

It prints a clear **SUCCESS** message and the running containers, or an
**ERROR** and a non-zero exit code if any step fails.

After a successful deploy the app is available on the Mac Mini at
`http://localhost:8080` (override the host port with `WEB_PORT`, e.g.
`WEB_PORT=3000 ./deploy.sh`).

---

## Notes & constraints

- **Replit stays the development environment.** Its workflows/preview are
  unchanged by this setup.
- **amd64 / glibc only.** The pnpm workspace strips every native binary that is
  not `linux-x64-gnu`, so the Dockerfiles use `node:24-bookworm-slim` (not
  alpine) and pin `platform: linux/amd64`. Do not switch the build base to
  alpine or arm64 — the web build (rollup / tailwind oxide / lightningcss) will
  fail to find its native binaries.
- **Web ↔ API.** The browser calls same-origin `/api/...`; nginx proxies that to
  the `api` container, so no API URL needs to be configured in the frontend.
- **Data.** The API currently uses in-memory demo data, so no database service
  is included. Restarting the `api` container resets it.
- **Secrets.** Do not commit the Gitea URL/token. Keep it in the local `gitea`
  remote (or pass `GITEA_REMOTE_URL` at push time).