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):

# 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:

git remote -v   # should list 'gitea'

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

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:

./scripts/push-to-gitea.sh

(Or directly: git push gitea main.)

B. Redeploy on the Mac Mini

./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).