qlockify-core-deployment/README.md

# Qlockify Deployment

Main deployment and operations repository for Qlockify.

This repo is the entrypoint for running the full product stack in production.

## Related Repositories

- Deployment repository declared by `origin`: `https://git.amiirkhl.ir/Qlockify/qlockify-core-deployment.git`
- Backend repository declared by its `origin`: `https://git.amiirkhl.ir/Qlockify/qlockify-backend-deployment.git`
- Frontend repository declared by its `origin`: `https://git.amiirkhl.ir/Qlockify/qlockify-frontend-deployment.git`

Use this repo for:

- Docker Compose orchestration
- Nginx
- SSL certificate mounting
- domain routing
- environment layout
- production service startup

Use the backend and frontend repos for application-level implementation details.

## What This Repo Contains

- `docker-compose.yml`
- Nginx config
- Postgres support files
- Dockerfiles for production images
- deployment environment samples
- container networking and volume wiring

## Architecture

Main deployed services:

- `nginx`
- `frontend`
- `backend`
- `celery`
- `celery-beat`
- `redis`
- `db`

Traffic pattern:

- `qlockify.ir` serves the frontend
- `api.qlockify.ir` serves the backend API, admin, docs, static, and media
- Nginx terminates TLS and proxies requests to the frontend and backend containers

## Expected Repository Layout

Docker builds read from nested application directories inside this repository:

- `./backend/qlockify-backend-deployment`
- `./frontend/qlockify-frontend-deployment`

Expected layout:

```text
qlockify-deployment/
  backend/
    Dockerfile
    .env.sample
    qlockify-backend-deployment/
  frontend/
    Dockerfile
    .env.sample
    qlockify-frontend-deployment/
  nginx/
  postgres/
  docker-compose.yml
```

## Deployment Flow

### 1. Place application source

Put the app repos into:

- `./backend/qlockify-backend-deployment`
- `./frontend/qlockify-frontend-deployment`

### 2. Configure env files

Create and fill:

- `./.env`
- `./backend/qlockify-backend-deployment/.env`
- `./frontend/qlockify-frontend-deployment/.env`

### 3. Build and run

```powershell
docker compose up -d --build
```

The backend container runs:

- database migrations
- `collectstatic`
- Gunicorn startup

## Domain and Routing

Configured domains:

- `qlockify.ir`
- `www.qlockify.ir`
- `api.qlockify.ir`

Behavior:

- `www.qlockify.ir` redirects to `qlockify.ir`
- `http` redirects to `https`
- frontend is served from `qlockify.ir`
- backend traffic is served from `api.qlockify.ir`

Before production startup:

1. Point DNS records for `qlockify.ir`, `www.qlockify.ir`, and `api.qlockify.ir` to the server.
2. Make sure `80` and `443` are open on the server firewall.
3. Make sure the TLS certificate covers all required names.

## SSL Certificates

Place certificate files here:

```text
./nginx/certs/fullchain.pem
./nginx/certs/privkey.pem
```

The repository intentionally keeps only:

- `./nginx/certs/.gitkeep`

Real certificate files are ignored by git.

## Required Backend Environment

Set these in:

```text
./backend/qlockify-backend-deployment/.env
```

Core production values:

- `DJANGO_ALLOWED_HOSTS=api.qlockify.ir,qlockify.ir,www.qlockify.ir`
- `CORS_ALLOWED_ORIGINS=https://qlockify.ir,https://www.qlockify.ir`
- `CSRF_TRUSTED_ORIGINS=https://api.qlockify.ir,https://qlockify.ir,https://www.qlockify.ir`
- `BASE_URL=https://api.qlockify.ir`
- `POSTGRES_HOST=db`
- `REDIS_HOST=redis`
- `REDIS_URL=redis://redis:6379/0`
- `CELERY_BROKER_URL=redis://redis:6379/0`
- `CELERY_RESULT_BACKEND=redis://redis:6379/1`

Google OAuth values:

- `GOOGLE_OAUTH_CLIENT_ID=...`
- `GOOGLE_OAUTH_CLIENT_SECRET=...`
- `GOOGLE_OAUTH_REDIRECT_URI=https://api.qlockify.ir/api/users/oauth/google/callback/`
- `GOOGLE_OAUTH_FRONTEND_CALLBACK_URL=https://qlockify.ir/auth/google/callback`

## Required Frontend Environment

Set this in:

```text
./frontend/qlockify-frontend-deployment/.env
```

```text
VITE_API_BASE_URL=https://api.qlockify.ir/api
```

## Background Workers

This stack includes:

- `celery` for async jobs
- `celery-beat` for scheduled jobs

If background scheduling stops working, inspect:

```powershell
docker compose logs -f celery
docker compose logs -f celery-beat
```

## Notifications and SSE

Notifications use Server-Sent Events at `/api/notifications/stream/`.

Current behavior:

- Nginx disables buffering for the SSE endpoint
- Gunicorn is tuned to tolerate connected streams for current traffic
- if concurrency grows materially, move SSE to async workers or a dedicated ASGI service

## Useful Operations

Build/rebuild:

```powershell
docker compose up -d --build
```

Restart a subset:

```powershell
docker compose up -d --build nginx backend frontend
```

Inspect running services:

```powershell
docker compose ps
```

Follow logs:

```powershell
docker compose logs -f nginx
docker compose logs -f backend
docker compose logs -f celery
docker compose logs -f celery-beat
```

Stop everything:

```powershell
docker compose down
```

## Scope Boundary

This repo should document:

- infrastructure
- runtime topology
- domains
- Nginx
- Docker Compose
- SSL
- operational startup and troubleshooting

It should not duplicate the application-specific implementation details already documented in the backend and frontend repositories.