dyolink/infrastructure/DEPLOY.md

# Dyolink — Production Server Deploy Guide

Linux VPS serves **`https://nudentic.ir` only**. Images come from the **Gitea registry** (`wixur.ir:3000`) on git tags. Staging is Windows (`https://wixur.ir`) — see [`STAGING-DEPLOY.md`](STAGING-DEPLOY.md).

**Automated path:** tag `v1.0.1` → [`.gitea/workflows/prod-tag-deploy.yml`](../.gitea/workflows/prod-tag-deploy.yml) (Windows runner builds, SSH to this server).

**Manual / first SSL:** Docker Hub + [`scripts/build-and-push-prod.sh`](scripts/build-and-push-prod.sh) is still documented below as a fallback.

**Example host:** `https://nudentic.ir` (do not point `wixur.ir` at this VPS).

---

## Automated deploy (Gitea tags)

```
git tag v1.0.1 && git push origin v1.0.1
        ↓
Windows act_runner builds frontend with https://nudentic.ir
        ↓
Push wixur.ir:3000/<owner>/dyolink-*:v1.0.1   (never :latest)
        ↓
SSH → Linux  docker login wixur.ir:3000  →  compose pull + up
        ↓
https://nudentic.ir
```

`:latest` is **staging only** (wixur.ir baked in). Production compose must pin `TAG=v1.0.1`.

### One-time on the Linux server

1. **HTTP registry** — Gitea is `http://wixur.ir:3000`. In `/etc/docker/daemon.json`:

```json
{
  "insecure-registries": ["wixur.ir:3000"]
}
```

Then `sudo systemctl restart docker` (containers restart).

2. **`.env`** in `/opt/dyolink/infrastructure/` — from [`deploy.prod.env.example`](deploy.prod.env.example):

- `DOMAIN=nudentic.ir`
- `REGISTRY_PREFIX=wixur.ir:3000/<gitea-owner>` (same owner as Gitea `REGISTRY_OWNER`)
- `TAG=v1.0.1` (CI overrides per release)

3. **`secrets/backend.env`:** `FRONTEND_URL=https://nudentic.ir`, `COOKIE_SECURE=true`

4. **SSH** — user that can run `docker` (e.g. `dyolink` in the `docker` group). Put the matching **public** key in `~/.ssh/authorized_keys`.

5. **Test pull** (after a staging or prod image exists):

```bash
docker login wixur.ir:3000 -u <gitea-user>
docker pull wixur.ir:3000/<owner>/dyolink-backend:<sha-or-tag>
```

### Gitea (same repo as staging)

**Variables:** `PROD_PUBLIC_BASE_URL=https://nudentic.ir`, `PROD_REGISTRY_HOST=wixur.ir:3000`, `PROD_INFRA_DIR=/opt/dyolink/infrastructure`, plus existing `REGISTRY_HOST` / `REGISTRY_OWNER` / `CLONE_HOST`.

**Secrets:** `PROD_SSH_HOST`, `PROD_SSH_USER`, `PROD_SSH_KEY` (private key). Reuse `REGISTRY_USERNAME` / `REGISTRY_PASSWORD`. Optional `PROD_SSH_PORT` (default 22).

OpenSSH must be on the Windows runner (`ssh.exe` / `scp.exe`).

### Release

```bash
git tag v1.0.1
git push origin v1.0.1
```

Or Gitea → Actions → **Production — tag build, push, deploy** → Run → tag `v1.0.1`.

Check `https://nudentic.ir/api/health`.

---

## 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   | `REGISTRY_PREFIX/dyolink-backend:TAG` | Gitea `v*` or Hub `dyolink/…` |
| frontend  | `REGISTRY_PREFIX/dyolink-frontend:TAG` | 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)

**Preferred:** `git tag vX.Y.Z && git push origin vX.Y.Z` (Gitea production workflow).

**Fallback (Docker Hub from a Mac):**

```bash
./infrastructure/scripts/build-and-push-prod.sh nudentic.ir v1.0.1
```

**On server** (if not using CI):

```bash
cd /opt/dyolink/infrastructure
# TAG in .env or: TAG=v1.0.1 docker compose -f docker-compose.prod.yml --env-file .env pull backend frontend
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
```

### Docker login to `wixur.ir:3000`: `http response to HTTPS client`

Add `"insecure-registries": ["wixur.ir:3000"]` to `/etc/docker/daemon.json` and restart Docker.

### 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`, `REGISTRY_PREFIX`, `TAG`, Let's Encrypt email |
| `/opt/dyolink/secrets/database.env` | Postgres credentials |
| `/opt/dyolink/secrets/backend.env` | API secrets, DATABASE_URL, JWT, SMS, `FRONTEND_URL` |
| `/opt/dyolink/infrastructure/nginx/generated/default.conf` | Auto-generated nginx SSL config |
| `/opt/dyolink/infrastructure/scripts/prod-remote-deploy.sh` | Tag deploy (CI SSH) |
| `/opt/dyolink/infrastructure/scripts/deploy-prod.sh` | First-time SSL + stack up |
| `.gitea/workflows/prod-tag-deploy.yml` | CI: build, push `:v*`, SSH deploy |

---

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