dyolink/infrastructure/DEPLOY.md

# Dyolink — Production Server Deploy Guide

Deploy the full stack (Postgres, NestJS API, Next.js, Nginx, Let's Encrypt) on a fresh Linux server using **Docker Hub** images.

**Example used in production:** `https://wixur.ir` on server `185.243.48.140`.

---

## Architecture

```
Internet → Nginx (:80 / :443)
              ├── /      → frontend:3000  (Next.js)
              └── /api   → backend:3000   (NestJS)
                            └── postgres:5432
```

| Service   | Image                              | Notes                          |
|-----------|------------------------------------|--------------------------------|
| postgres  | `postgres:15-alpine`               | Data in Docker volume          |
| backend   | `dyolink/dyolink-backend:latest`   | Runs migrations + seed on start |
| frontend  | `dyolink/dyolink-frontend:latest`  | URLs baked in at **build time** |
| nginx     | `nginx:alpine`                     | SSL termination + reverse proxy |
| certbot   | `certbot/certbot`                  | Auto-renews certificates       |

---

## Prerequisites

### On your Mac (build machine)

- Docker Desktop running
- Repo cloned
- Docker Hub account (`dyolink`) with images pushed

### On the server

- Ubuntu 24.04 (or similar)
- Root or sudo access
- **Domain** with DNS **A record** → server public IP
- Ports **22**, **80**, **443** open (UFW + cloud provider firewall)

---

## Part 1 — Build & push images (Mac)

Frontend URLs are **compiled into the image**. Always build with the real public domain:

```bash
cd /path/to/dyolink
docker login   # only needed on Mac to push

./infrastructure/scripts/build-and-push-prod.sh YOUR_DOMAIN.com latest
```

Example:

```bash
./infrastructure/scripts/build-and-push-prod.sh wixur.ir latest
```

This pushes:

- `dyolink/dyolink-backend:latest`
- `dyolink/dyolink-frontend:latest`

**When to rebuild:** domain changes, frontend env (`NEXT_PUBLIC_*`) changes, or new app release.

---

## Part 2 — Server bootstrap (once per server)

SSH as root:

```bash
ssh root@YOUR_SERVER_IP
```

### 2.1 Update system & create deploy user

```bash
apt update && apt upgrade -y
apt install -y curl git ufw fail2ban

adduser dyolink
usermod -aG sudo dyolink

# Optional: copy SSH keys from root
mkdir -p /home/dyolink/.ssh
cp /root/.ssh/authorized_keys /home/dyolink/.ssh/ 2>/dev/null || true
chown -R dyolink:dyolink /home/dyolink/.ssh
chmod 700 /home/dyolink/.ssh
```

### 2.2 Install Docker

If `curl -fsSL https://get.docker.com | sh` returns **403**, use Ubuntu packages:

```bash
apt update
apt install -y docker.io docker-compose-v2
systemctl enable --now docker
usermod -aG docker dyolink
```

Verify:

```bash
docker --version
docker compose version
```

### 2.3 Docker Hub login (if images are private)

```bash
docker login
```

Public images skip this step.

### 2.4 Firewall

```bash
ufw default deny incoming
ufw default allow outgoing
ufw allow OpenSSH
ufw allow 80/tcp
ufw allow 443/tcp
ufw --force enable
```

Also open **80** and **443** in your VPS provider's cloud firewall panel if one exists.

### 2.5 DNS

Before SSL, confirm DNS:

```bash
dig +short YOUR_DOMAIN.com
# Must return YOUR_SERVER_IP
```

---

## Part 3 — Copy infrastructure to server (Mac)

```bash
cd /path/to/dyolink

ssh dyolink@YOUR_SERVER_IP "sudo mkdir -p /opt/dyolink/secrets && sudo chown -R dyolink:dyolink /opt/dyolink"

scp -r infrastructure/docker-compose.prod.yml \
       infrastructure/nginx \
       infrastructure/scripts \
       infrastructure/database \
       infrastructure/deploy.prod.env.example \
       infrastructure/backend.prod.env.example \
       infrastructure/database.prod.env.example \
       dyolink@YOUR_SERVER_IP:/opt/dyolink/infrastructure/
```

On the server:

```bash
ssh dyolink@YOUR_SERVER_IP
chmod +x /opt/dyolink/infrastructure/scripts/*.sh
```

---

## Part 4 — Configure secrets (server)

### 4.1 Main `.env`

```bash
cd /opt/dyolink/infrastructure
cp deploy.prod.env.example .env
nano .env
```

```env
DOMAIN=wixur.ir
DOCKER_USERNAME=dyolink
TAG=latest
LETSENCRYPT_EMAIL=your-email@example.com
DEPLOY_SECRETS_DIR=/opt/dyolink/secrets
```

### 4.2 Database secrets

```bash
cp database.prod.env.example /opt/dyolink/secrets/database.env
nano /opt/dyolink/secrets/database.env
```

```env
POSTGRES_USER=dyolink_user
POSTGRES_PASSWORD=STRONG_PASSWORD_HERE
POSTGRES_DB=dyolink_db
```

### 4.3 Backend secrets

```bash
cp backend.prod.env.example /opt/dyolink/secrets/backend.env
nano /opt/dyolink/secrets/backend.env
```

Generate JWT secrets:

```bash
openssl rand -hex 32   # use for JWT_SECRET
openssl rand -hex 32   # use for JWT_REFRESH_SECRET (must be different)
```

```env
NODE_ENV=production
PORT=3000

DATABASE_URL=postgresql://dyolink_user:STRONG_PASSWORD_HERE@postgres:5432/dyolink_db

JWT_SECRET=<first openssl output>
JWT_EXPIRES_IN=15m
JWT_REFRESH_SECRET=<second openssl output>
JWT_REFRESH_EXPIRES_IN=30d

FRONTEND_URL=https://wixur.ir

SMS_IR_API_KEY=your_key
SMS_IR_TEMPLATE_ID=your_template_id
```

**Critical checks:**

| Rule | Why |
|------|-----|
| `DATABASE_URL` password = `POSTGRES_PASSWORD` | Backend cannot connect otherwise |
| `FRONTEND_URL` = `https://YOUR_DOMAIN` | CORS, cookies, invite links |
| JWT secrets must **not** contain `CHANGE_ME` | App refuses to start (by design) |
| Postgres password set **before first** `up` | Password only applied on first volume create |

---

## Part 5 — Deploy (server)

```bash
cd /opt/dyolink/infrastructure
./scripts/deploy-prod.sh
```

This script:

1. Issues Let's Encrypt certificate (first run)
2. Renders HTTPS nginx config
3. Pulls images from Docker Hub
4. Starts all containers

First deploy takes **3–5 minutes**.

---

## Part 6 — Verify

```bash
docker compose -f docker-compose.prod.yml --env-file .env ps
```

Expected:

| Container | Status |
|-----------|--------|
| dyolink_db_prod | Up (healthy) |
| dyolink_backend_prod | Up (healthy) |
| dyolink_frontend_prod | Up |
| dyolink_nginx_prod | Up |
| dyolink_certbot_prod | Up |

```bash
curl -s https://YOUR_DOMAIN/api/health
# {"status":"ok","timestamp":"..."}

curl -I https://YOUR_DOMAIN/
# HTTP/2 200
```

Open `https://YOUR_DOMAIN` in a browser.

---

## Updating the app (new release)

**On Mac** — build & push:

```bash
./infrastructure/scripts/build-and-push-prod.sh wixur.ir latest
```

**On server:**

```bash
cd /opt/dyolink/infrastructure
docker compose -f docker-compose.prod.yml --env-file .env pull backend frontend
docker compose -f docker-compose.prod.yml --env-file .env up -d
```

Backend runs `prisma migrate deploy` automatically on container start.

---

## Troubleshooting

### Docker install: `get.docker.com` returns 403

Use `apt install docker.io docker-compose-v2` (see Part 2.2).

### Docker Hub pull: 403 Forbidden

```bash
docker login
```

If still blocked, transfer images from Mac:

```bash
# Mac
docker save dyolink/dyolink-backend:latest dyolink/dyolink-frontend:latest \
  postgres:15-alpine nginx:alpine certbot/certbot:latest | gzip > images.tar.gz
scp images.tar.gz dyolink@SERVER:/tmp/

# Server
gunzip -c /tmp/images.tar.gz | docker load
```

### Backend crash: `JWT_SECRET must be changed from the placeholder value`

Edit `/opt/dyolink/secrets/backend.env` — replace JWT secrets with `openssl rand -hex 32` output. Restart:

```bash
docker compose -f docker-compose.prod.yml --env-file .env up -d backend
```

### HTTP shows "obtaining SSL certificate" / HTTPS fails

Nginx is still on the bootstrap config. Fix:

```bash
cd /opt/dyolink/infrastructure
./scripts/render-nginx-ssl.sh
docker compose -f docker-compose.prod.yml --env-file .env up -d nginx --force-recreate
curl -s https://YOUR_DOMAIN/api/health
```

### Backend `Restarting` — database password mismatch

If you changed `POSTGRES_PASSWORD` after the first deploy, reset the DB volume (destroys data):

```bash
docker compose -f docker-compose.prod.yml --env-file .env down
docker volume rm dyolink_postgres_data_prod
# Fix database.env + backend.env passwords to match
./scripts/deploy-prod.sh
```

### View logs

```bash
docker compose -f docker-compose.prod.yml --env-file .env logs backend --tail 50
docker compose -f docker-compose.prod.yml --env-file .env logs nginx --tail 50
docker compose -f docker-compose.prod.yml --env-file .env logs frontend --tail 50
```

### Internal health checks (bypass public network)

```bash
docker compose -f docker-compose.prod.yml --env-file .env exec nginx \
  wget -qO- http://backend:3000/api/health

docker compose -f docker-compose.prod.yml --env-file .env exec frontend \
  wget -qO- http://127.0.0.1:3000/ | head -3
```

---

## File reference

| Path on server | Purpose |
|----------------|---------|
| `/opt/dyolink/infrastructure/.env` | Domain, Docker Hub user, Let's Encrypt email |
| `/opt/dyolink/secrets/database.env` | Postgres credentials |
| `/opt/dyolink/secrets/backend.env` | API secrets, DATABASE_URL, JWT, SMS |
| `/opt/dyolink/infrastructure/nginx/generated/default.conf` | Auto-generated nginx SSL config |
| `/opt/dyolink/infrastructure/scripts/deploy-prod.sh` | Main deploy entry point |
| `/opt/dyolink/infrastructure/scripts/build-and-push-prod.sh` | Build & push (run on Mac) |

---

## Quick checklist (new server)

- [ ] DNS A record → server IP
- [ ] Docker installed on server
- [ ] UFW + cloud firewall: 22, 80, 443 open
- [ ] Images built with correct domain and pushed to Docker Hub
- [ ] `infrastructure/` copied to `/opt/dyolink/`
- [ ] `.env`, `database.env`, `backend.env` configured (real passwords + JWT)
- [ ] `./scripts/deploy-prod.sh` completed
- [ ] `curl https://DOMAIN/api/health` returns `{"status":"ok",...}`
- [ ] App loads in browser

---

## Issues encountered on first deploy (wixur.ir) — summary

| Problem | Cause | Type |
|---------|-------|------|
| `get.docker.com` 403 | Regional/network block | **Server setup** — use `apt install docker.io` |
| Docker Hub pull 403 | Hub blocked without login | **Server setup** — `docker login` |
| Backend crash loop | `JWT_SECRET` still had `CHANGE_ME` | **Config** — edit `backend.env` |
| HTTP "obtaining SSL" / HTTPS broken | Nginx not recreated after SSL config | **Deploy script** — fixed in `init-letsencrypt.sh` / `deploy-prod.sh` |
| Frontend "unhealthy" in `docker ps` | Healthcheck timing; app still served pages | **Cosmetic** — no action needed |

**No application code changes were required.** The app, migrations, and seed all worked on first deploy once config was correct.